-
Notifications
You must be signed in to change notification settings - Fork 0
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.
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.
When you launch Photosphere, you will be presented with the option to open an existing database or create a new one.
- Open existing: Click Open Database and navigate to a directory that already contains a Photosphere database.
- Create new: Click Open Database, navigate to an empty directory (or create a new one), and select it. Photosphere will initialise a new database there.
The app remembers your recently opened databases and will automatically reopen the last one on subsequent launches.
Adding media files directly in the desktop app is coming soon. In the meantime, use the CLI tool to add photos and videos to your database:
psi add ~/Pictures/2024/See Getting-Started-CLI for full details on the psi add command.
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.
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.
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
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.
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.
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.
The desktop app stores preferences in ~/.config/photosphere/desktop.json, including:
- UI theme (light, dark, or system)
- Recently opened databases
- Last opened database (auto-reopened on launch)
See Configuration-Desktop for the full list of configuration keys.