Getting Started

Installation

Riffle can be run as a standalone binary or with Docker. Follow the instructions below to get started.

Prerequisites:

  • Go 1.23 or later
  • Git
  • esbuild
  • libvips (for image processing)
  • exiftool (for EXIF metadata extraction)

Build steps:

  1. Install tools:
    • Install Go
    • Install esbuild
    $ go install github.com/evanw/esbuild/cmd/esbuild@latest
  1. Clone the repository:
    2. $ git clone https://github.com/sheshbabu/riffle.git
 $ cd riffle
  1. Build the application:
    2. $ make build
  1. Set up environment variables (see below)
  1. Run the application:
    2. $ ./riffle
  1. Access Riffle in your browser at http://localhost:8080

Environment Variables

Create a .env file in the project root with the following variables: 

DEV_MODE=false
 PORT=8080
 IMPORT_PATH=/path/to/import
 LIBRARY_PATH=/path/to/library
 THUMBNAILS_PATH=/path/to/thumbnails
 EXPORT_PATH=/path/to/export
  • DEV_MODE - Set to true for development mode (serves assets from file system)
  • PORT - Port number for the web server (default: 8080)
  • IMPORT_PATH - Source folder containing photos to import
  • LIBRARY_PATH - Destination folder for organized photos
  • THUMBNAILS_PATH - Folder for 300x300px thumbnail cache
  • EXPORT_PATH - Destination folder for exported photos

Workflow

Riffle follows a four-step workflow: Import → Curate → Library → Export. This design keeps your culling process fast and your main photo library clean.

1. Import

Point Riffle at your import folder (typically where you copy photos from your camera or phone). The import process:

  • Scans all files recursively from IMPORT_PATH
  • Detects exact duplicates using SHA256 hashing
  • Keeps only the best candidate (prefers files with EXIF data)
  • Moves or copies unique files to LIBRARY_PATH
  • Organizes into Year/Month folders
  • Renames files as YYYY-MM-DD-HHMMSS-hash.ext
  • Generates 300x300px thumbnails
  • Extracts and stores EXIF metadata in SQLite

Note: Original file timestamps are preserved during the move operation.

2. Curate

The Curate view shows only uncurated photos (is_curated = false). This is where you do your culling work:

  • Navigate with arrow keys in grid view
  • Press Enter or Space to open lightbox
  • Use keyboard shortcuts to rate photos:
    • P - Accept (pick)
    • X - Reject (trash)
    • 1-5 - Rate with stars
    • U - Unflag (reset curation state)
  • Photos fade out after action with undo option
  • Auto-advance to next photo in lightbox mode
  • Press I to toggle metadata panel

3. Library

The Library view shows only curated, non-trashed photos (is_curated=true AND is_trashed=false). Features include:

  • Masonry grid layout with responsive columns
  • Group headers showing date, photo count, and size
  • Filter by date range, rating, camera, and location
  • Select photos to add to albums

4. Export

Export your curated photos to a destination folder for use in your main photo management tool:

  • Filter by minimum rating (0-5)
  • Filter by curation status (all photos or picked only)
  • Choose to maintain or flatten folder structure
  • Skip or include duplicate files based on SHA256 hash
  • Optional cleanup: delete originals after successful export
  • Export sessions tracked in database with per-photo status

Keyboard Shortcuts

Riffle is designed for keyboard-driven workflows. All shortcuts work in grid, lightbox, and compare views.

Grid View

  • Arrow Keys - Navigate between photos
  • Enter or Space - Open photo in lightbox
  • C - Open compare mode (side-by-side view)
  • P - Accept photo (mark as curated)
  • X - Reject photo (move to trash)
  • U - Unflag photo (reset curation state)
  • 1-5 - Rate photo with stars
  • Arrow Left/Right - Navigate to previous/next photo
  • P - Accept photo (mark as curated)
  • X - Reject photo (move to trash)
  • U - Unflag photo (reset curation state)
  • 1-5 - Rate photo with stars
  • I - Toggle metadata panel
  • Escape - Close lightbox

Compare Mode

  • Arrow Left/Right - Change candidate photo
  • Arrow Down - Swap reference and candidate positions
  • Arrow Up - Make candidate the new reference
  • P - Accept candidate photo (auto-advances)
  • X - Reject candidate photo (auto-advances)
  • U - Unflag candidate photo
  • 1-5 - Rate candidate photo (auto-advances)
  • I - Toggle metadata panel
  • C or Escape - Close compare mode

Tip: After rating a photo in lightbox or compare mode, Riffle automatically advances to the next photo, keeping your workflow fast.

Features

Duplicate Detection

Riffle uses SHA256 file hashing to identify exact duplicates during import. When duplicates are found:

  • Only the best candidate is moved to the library
  • Files with EXIF data are preferred over those without
  • Duplicates remain in the import folder for manual cleanup
  • All files are scanned for EXIF metadata to aid selection

Burst Detection

Photos taken within a configurable time window (default: 3 seconds) with similar visual content are grouped as bursts:

  • Uses dHash (perceptual hashing) to detect similar images
  • Configurable similarity threshold (default: dHash distance < 4)
  • Displayed as collapsed stacks with count badge
  • Click to expand and review individual photos
  • Can be disabled or reconfigured in Settings → Burst
  • Existing bursts can be rebuilt with new parameters

Albums

Create custom collections to organize photos:

  • User-defined collections for themed groupings
  • Bulk add selected photos from library view
  • Create, view, and manage albums from the Albums page

Calendar

Month-by-month overview of your photo collection:

  • Grid showing curated and uncurated photo counts
  • Cover photos for each month
  • Click to navigate to filtered library view for that month

Stats

Analytics dashboard showing collection statistics:

  • Photo collection statistics over time
  • Stacked bar charts grouped by decade (1920s, 1930s, etc.)
  • Visual insights into your photography history