LightCraft Cloud

Lightroom-style sync for LightCraft, using your own cloud storage. Your home PC stays the master copy, and there is no server of ours in between.

What you get:

• Browse your library on your phone and edit photos there. The edits come back to LightCraft on your PC.
• Keep a full copy of chosen folders on a second PC, edit there too, and import new photos there.
• Send photos from your phone to the home PC: pick them in the app, or let the app send the new camera photos by itself.
• Use any cloud storage that rclone supports: Google Drive, OneDrive, S3, WebDAV, SFTP and more.

How the parts fit

flowchart LR
    subgraph HOME["Home PC (always on, master copy)"]
        LC["LightCraft"]
        APP["LightCraft Cloud app with the engine"]
    end
    subgraph CLOUD["Your cloud storage (any rclone remote)"]
        ORIG["originals"]
        PREV["previews and thumbnails"]
        LIST["photo list"]
        INBOX["inbox (edits as XMP sidecars)"]
        IMP["imports"]
    end
    subgraph OTHER["Other PCs"]
        OAPP["Light app: full copy of chosen folders"]
    end
    PHONE["Phone app: previews only"]

    APP -->|"originals, one way"| ORIG
    APP --> PREV
    APP --> LIST
    ORIG -->|"chosen folders and latest edits"| OAPP
    PREV --> PHONE
    PHONE -->|"edits"| INBOX
    OAPP -->|"edits"| INBOX
    OAPP -->|"photos you import"| IMP
    INBOX -->|"merged into your sidecars"| APP
    IMP -->|"added to the home folder"| APP
    APP <-->|"reads and writes sidecars"| LC

Loading

Three rules hold everywhere:

• The home PC is the master. Originals go out from it to the cloud and your other PCs, and photo files are never changed. A new photo imported on another PC goes to the home PC first, then out like any other.
• Edits travel back as small XMP sidecar files through the inbox. The home PC merges them into its own sidecars.
• Deletions spread only from the home PC. Deleting on another PC only affects that PC.

The parts

Part	What it is	Where
Phone app	Android app. Shows thumbnails and small previews, lets you edit, sends the edits back. Holds no originals.	lightcraft-android, downloads on its Releases page
Home PC app	Tray app on the PC where your master library lives. Publishes your photo folder, makes previews with LightCraft's engine, applies edits that arrive. Linux and Windows (x86-64).	This repository, Releases
Other-PC app	The same tray app without the engine. Keeps a copy of the folders you choose, sends back edits and imported photos. Windows and Linux.	This repository, Releases

The PC apps are one program, lightcraft-cloud-desktop, built two ways (the home build with the engine, the light build without). The phone app is a fork of LightCraft for Android.

What it does, day to day

• Edits. Edit a photo in LightCraft on any PC, or on the phone. The edit is saved as an XMP sidecar next to the photo, travels through the cloud and ends up on every device. If two devices changed the same photo, the edits are merged, as described below.
• Imports. On another PC, import photos in LightCraft into the synced folder, in any folder structure you like. The app keeps your folder structure, sends the photos to the home PC, and they appear in LightCraft there.
• Photos from the phone. In the phone app, on the Cloud library page, choose Send photos to PC and pick photos, or switch on Send new camera photos automatically (off by default; only photos taken after you switch it on; by default only on Wi-Fi). The photos go to the home PC through the same imports as above, into a folder Phone/<date taken> below your photo folder, and appear in LightCraft and on every device like any other photo. Photos stay on the phone, and the app deletes nothing from the gallery. HEIC photos are not sent yet: LightCraft cannot read them.
• Live progress. While it works, the Status window and the tray tooltip show what it is doing, how far along it is and about how long is left, and say so if nothing has moved for a while.
• Refresh of LightCraft. The app tells your running LightCraft about new photos and new edits, so you do not have to run Synchronize Folder. This needs LightCraft to be running and its control port to be on (see Quick start).

If two devices edit the same photo

Usually neither edit is thrown away. Both go to the home PC, which merges them setting by setting, using the version each device started from. This works the same for a laptop that was offline for a week.

• Different settings (exposure on the phone, a rating on the laptop): both are kept.
• The same setting, changed differently: the edit sent last wins that setting. "Last" means when the device sent the edit, by its own clock, not when you made it.
• Crop, geometry, tone curve, profile and white balance each count as one unit, and so do masks and spots. If both sides changed anything inside one, the later edit's whole unit wins.
• If the edits can't be merged safely (the starting version is gone, a file can't be read, the edits use different LightCraft settings formats), the newest edit wins the whole file.

The version that gets replaced or loses is saved in the home PC's history (history/ in its state folder), and every incoming edit stays in the cloud for 30 days. Clashes are written to the log, and getting a losing version back is a manual file copy: there is no screen for it yet. Photo files are never modified. Details: FORMAT.md.

Quick start

The home PC needs an rclone remote for your cloud storage (rclone config). Other PCs and the phone do not: you pair them with the home PC (see Pairing a device), and nobody copies config files by hand.

Downloads are on the Releases page (from v0.2.0; the Windows home PC one from v0.2.1):

File	For
lightcraft-cloud-<version>-windows-setup.exe	Windows, another PC. A normal installer; no administrator needed.
lightcraft-cloud-<version>-windows-home-setup.exe	Windows, the home PC (with the engine). The same kind of installer.
lightcraft-cloud-<version>-linux-light.tar.gz	Linux, another PC (no LightCraft engine).
lightcraft-cloud-<version>-linux-home.tar.gz	Linux, the home PC (with the engine).
SHA256SUMS	checksums of the four files above.

The two Windows installers are the same program in two builds, so they install in the same place and one goes over the other. The home one goes over an installed other-PC app (an upgrade, with your settings). The other-PC installer refuses to go over the home one and changes nothing, because that would stop the home PC from publishing; uninstall first if you really want that. An app updates only to its own kind: a home app never installs the other-PC installer, and the other way round.

Each Linux archive holds the program, librclone.so, the licences and an install.sh. Unpack it and run ./install.sh: it puts the program in ~/.local/bin and the library in ~/.local/lib/lightcraft-cloud/, where the app looks for it. It needs no sudo. The Linux programs need glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora 36 or newer).

1. LightCraft settings, on every PC. In LightCraft open Settings, then the Import tab. Under XMP sidecars tick Automatically write changes into XMP sidecars and set Sidecar names to IMG_1.CR3.xmp. Without this, edits stay inside LightCraft and are never sent.

2. LightCraft control port, on every PC. This lets the app tell LightCraft about new photos and edits. The port listens on this PC only and has no password. Then restart LightCraft.

• Linux Flatpak: flatpak override --user --env=LIGHTCRAFT_CONTROL_PORT=7980 ai.storyteller.lightcraft
• Windows: setx LIGHTCRAFT_CONTROL_PORT 7980

3. Home PC (Linux or Windows).

1. Linux: download lightcraft-cloud-<version>-linux-home.tar.gz from Releases, unpack it and run ./install.sh, then start lightcraft-cloud-desktop. Windows: run lightcraft-cloud-<version>-windows-home-setup.exe and start LightCraft Cloud from the Start menu. Setup opens on the first run.
2. Choose This is my home PC, your photo folder (the folder your photos are in, for example D:\Photos on Windows; never your LightCraft library folder) and your rclone remote with a folder on it.
3. Choose "Originals and previews", or "Previews only" if you do not want the originals in the cloud.
4. Save. The first sync starts and uploads the library.

The app only renders on the home PC: it works on a scratch library of its own in its state folder and never opens, locks or changes your LightCraft library.

4. Another PC.

1. Windows: run lightcraft-cloud-<version>-windows-setup.exe from Releases (not the home one). Linux: unpack lightcraft-cloud-<version>-linux-light.tar.gz and run ./install.sh.
2. Start it. Setup opens on the first run. Choose This is another PC.
3. Pair it with the home PC. On this PC click Pair with my home PC; it shows a code. On the home PC open Status, then Add a device, and type that code. The home PC then shows a QR code and Copy text for another PC; copy the text, and paste it on this PC. The storage is filled in. (If you already have your own rclone remote for the cloud storage on this PC, you can choose One of my rclone remotes instead.)
4. Pick a photo folder on this PC and tick the folders to keep.
5. Add that photo folder to LightCraft, and set LightCraft's import destination to it.

5. Phone.

1. Install the APK from the phone app Releases.
2. In the phone app open Pair with your PC; it shows a code. On the home PC open Status, then Add a device, and type that code. Then press Show pairing QR.
3. In the phone app, scan the QR code on the monitor. You type nothing on the phone. The phone guide has the steps.

Pairing a device

Pairing hands the home PC's cloud sign-in to another device so you do not copy rclone config files by hand. The order matters. The device that is joining (the phone, or the other PC) makes a code such as 7K2M-9QXD-4TB and shows it on its own screen. You type that code into the home PC (a password-style field, so the code is not shown there). Only then does the home PC show a QR code, and the same thing as text. The QR code and the text are the rclone settings for the library's remote, encrypted with the code. The joining device scans or pastes the text, and opens it with the code it already holds; that is all. No server of ours is involved, no port is opened on the home PC, and nothing is sent anywhere, so it works from any network and there is nothing to keep running.

What it hands over, in plain terms:

• The device gets the same access to your cloud storage account as the home PC has, not only to the LightCraft folder. The sign-in token cannot be limited to one folder.
• Only that one remote is included (and, for an encrypted remote, the remote it wraps). Your other rclone remotes are not.
• Do it only for devices you own. The home PC's screen only ever shows the locked QR code, never the code, so a screen share or a photo of the monitor is useless without the code from the device. Still, do not post the QR code or the code.
• To cut off a lost device, sign this app out in your cloud provider's account page (for Google, the third-party access page of your Google account). That signs out every device that uses this sign-in, including the home PC, which then needs signing in again.
• Remotes that cannot be handed over are refused with a reason: a library in a folder on the PC, union and combine remotes, and remotes that use a key file or other file on the PC.
• Only tested with Google Drive so far.

4. Another PC and 5. Phone above say where to click. The pairing window shows the QR code only after you type a valid code and press Show pairing QR, and forgets the code and text when it is closed. A mistyped code is caught before anything is shown (its last character is a check character).

Updates. The app looks on GitHub once a day for a newer published release (the request carries only the app's name and version in its User-Agent, nothing about you or your library; switch it off with "Check for new versions" in Settings). When there is one, the tray menu and the Status window say so. On Windows, Update now downloads the installer of its own kind, checks it against the release's SHA256SUMS, waits until no sync is running, installs it and restarts the app. On Linux it only links to the release; unpack the new archive and run ./install.sh again. Nothing is ever installed without a click.

Status and limits

This is early software.

• Albums are not built. Uploading from the phone sends JPEG, PNG, TIFF, DNG and the raw formats the home PC adopts; HEIC/HEIF and WebP are not sent, and neither are videos.
• The Windows installers and programs are not code-signed, so Windows SmartScreen warns when you first run the installer. The update check compares the installer with a checksum file from the same GitHub release: that catches a damaged download, not a release published by someone who has taken over the GitHub account.
• A Mac build does not exist. The home PC app runs on Linux and on Windows 10 or 11 (x86-64); there is no ARM build of either.
• The Windows home PC app has been built and tested on a real Windows (a CI runner), but not yet used on a real home PC's tray and desktop. What differs from Linux there: another program (LightCraft with a sidecar open, a virus scanner) can hold a file, and then the app waits for the next sync and Status says which file; the history purge needs restic on the PATH (or a path in photo_backup), or photo_backup = ""; "Folders to leave out" are matched with their exact capitals. See desktop-app.md.
• LightCraft must be running for the automatic refresh to work. Without it the photos and sidecars still arrive; run Synchronize Folder in LightCraft.
• On Linux the app needs rclone's librclone.so library in a place it looks; install.sh puts it there (see the config reference for the places).

Docs

• Desktop app: behaviour, another PC, config reference, how LightCraft is told about changes.
• Cloud layout: the files in the cloud and the inbox protocol.
• Building and testing: repository layout, build, Windows build, tests.
• The old Python tool: lc-cloud, the first version, replaced by the desktop app.

Licence and credits

License: MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

This is an independent project. It builds on LightCraft by storytold, LightCraft for Android, and rclone. Thanks to their authors.