Getting Started Desktop

The Photosphere Desktop app is an application for managing your media file database through a graphical user interface on Windows, macOS, and Linux.

Installation

Start here: install the desktop app before anything else. See Installation-Desktop for download links, the correct file names, and platform-specific setup steps.

Photosphere also requires FFmpeg and ImageMagick. See Required-Tools for instructions.

Quick Start

1. Open or Create a Database

When you launch Photosphere, the startup screen offers New database, Open database, and Add database buttons, along with a list of recent databases.

• Create new: Click New database, choose a directory (or create one), and confirm. Photosphere will initialise a new database there.
• Open existing: Click Open database and navigate to a directory that already contains a Photosphere database.

The app remembers your recently opened databases and will automatically reopen the last one on subsequent launches.

2. Add Media Files

Add photos and videos directly in the desktop app from the Import page. You can import individual files, an entire directory, or a zip archive (videos are supported too).

3. Browse Your Gallery

Your media is displayed in a scrollable gallery sorted by date (newest first). You can:

• Scroll through the gallery to browse all your photos and videos
• Click a photo to open a full-size view
• Search using the search icon in the navigation bar, see Gallery-Search to search for photos by name, description, location, label, etc.

4. Photo View

Click any photo in the gallery to open the full-screen view. The toolbar at the top contains:

• Star: marks the photo with a "starred" label for easy filtering
• Flag: marks the photo with a "flagged" label
• Download: saves the original file to your local filesystem
• Copy to clipboard: copies a display-quality version as a PNG
• Info: opens the Photo Details panel (see below)
• Delete: removes the photo (with a confirmation prompt)

Labels are shown at the bottom of the screen. Click a label to search the gallery for other photos with the same label. Use the tag icon to add a new label inline.

Click Download to save the original file.

5. Photo Details

Click the Info button in the photo view to open the Photo Details panel. This shows:

• Description: editable free-text field
• Asset ID and Asset hash
• Date and time the photo or video was taken
• Location (if present in the file metadata)
• Original filename and dimensions
• Labels: add or remove labels; click a label to search the gallery for matching photos
• Star / Flag toggles
• Delete button

6. Working with multiple photos

To select multiple photos, hover over any photo in the gallery and click the checkmark that appears. You can also select the current photo while in the photo view using the select button in the toolbar.

When one or more photos are selected, the navbar shows the selection count. Open the overflow menu (⋮) to perform bulk operations:

• Move to: move selected photos to another open database
• Download: save all selected photos to your local filesystem
• Delete: delete all selected photos (with a confirmation prompt)

Click the ✕ next to the selection count in the navbar to clear the selection.

Managing Databases

The desktop app includes a database management page for registering, editing, and removing database entries. Open it from the left sidebar by clicking Manage Databases. Each entry has a name, path, and optional links to shared secrets, when you open a database with linked secrets, credentials are resolved automatically.

See Managing-Databases for full details.

Managing Secrets

The desktop app includes a secrets management page for storing S3 credentials, encryption keys, and API keys. Open it from the left sidebar by clicking Manage Secrets. Secrets can also be created inline when adding or editing a database entry.

See Managing-Secrets for full details.

Where to Store Your Database

A Photosphere database can live on your local filesystem or on S3-compatible cloud storage. The recommended setup is:

1. Keep your primary database on your local disk. It is fast and works offline.
2. Replicate it to the cloud for an encrypted, off-site backup using the replicate action on the Manage Databases page. Re-run it to keep the backup up to date.
3. On space-limited devices, create a partial (lazy) replica. It stores only metadata and thumbnails; full-size originals are pulled from the cloud on demand, keeping the on-device footprint small.

flowchart TD
    local[("Local database<br/>(full, primary)")]
    cloud[("Cloud backup<br/>(full, encrypted)")]
    device[("Space-limited device<br/>(partial lazy replica)")]

    local -->|"replicate"| cloud
    cloud -->|"replicate (partial)"| device
    device -.->|"pull originals on demand"| cloud

Loading

Cloud Storage (S3)

You can store your database on S3-compatible cloud storage. See Configuration-Cloud-Storage for setup and configuration.

Configuration

The desktop app stores preferences in ~/.config/photosphere/desktop.toml, including:

• UI theme (light, dark, or system)
• Last opened database (auto-reopened on launch)
• Recent gallery searches, last download folder, and the FPS indicator toggle

The list of recently opened databases is stored separately in the database registry (databases.toml), not in the desktop preferences file.

See Configuration-Desktop for the full list of configuration keys.