Documentation & Setup Guide

Getting started

• TripShow opens a new, empty project on launch — there's no file to pick first.
• Click Import in the toolbar and choose Folder… (photos on disk) or Photos Album…. You can combine several imports in one project.
• The first time you pick a Photos album, macOS asks for permission — click Allow. (TripShow needs macOS 26 on Apple Silicon.)
• Photos appear in a grid, sorted by the time they were taken. Your work is saved as a .tripshow document.

Choosing & ordering photos

• Click a photo's badge (or its thumbnail) to select or deselect it for the slideshow.
• Drag a photo to reorder. The order you set is kept.
• Type a short caption in the field under any photo; press Return to save it.
• ⌘-click to mark several photos, then right-click ▸ Remove from Project (or press ⌫).
• Right-click a single photo ▸ Regenerate Caption to rewrite just that one with AI.

Analyze

• Analyze looks up each photo's city & country from its GPS, groups near-duplicate bursts, and pre-selects the sharpest shot in each group.
• Photos without GPS get an approximate location inferred from their neighbours (marked with a ⌖ badge).
• More ▸ Reset Analysis clears those automatic choices; your manual selections and captions are always kept.

Project Settings

The Project Settings button (toolbar) opens a popover of options saved inside this document. It starts from your global defaults and overrides them per project.

• Seconds per photo — drag the slider (2–20 s) for how long each photo stays on screen.
• Ken Burns motion — the slow zoom/pan across each photo. Turn off for static frames.
• Chapter titles — Separate title slide (a full-screen card before each new place) or Overlay on first photo (the place name drawn over the first shot of the run).
• Show captions on video — burn captions into the slideshow and export. Off hides them without deleting.
• Generate captions with AI — enables the Generate Captions button and per-photo Regenerate.
• AI provider — which configured provider writes captions for this project.

Captions

• Generate Captions writes a one-line description for each selected photo.
• Caption Prompt (toolbar) steers the tone and interpretation of every generated caption — e.g. “witty postcard voice”, “focus on the food”.
• A caption you type yourself is never overwritten by a batch Generate Captions (a single-photo Regenerate does replace it, since you asked for it).

Setting up AI captions

Captions need an AI backend. Pick one, configure it in Settings ▸ AI providers, then select it in Project Settings ▸ AI provider. Every option needs a vision-capable model — one that can actually look at the photo. A text-only model will not work.

Which model? A bigger local model like gemma4:12b gives richer captions but needs more RAM and runs slower than a small one like llava. Cloud models are fast and capable but cost per image and send your photos to the provider.

Managing sources

A project can pull from several folders and Photos albums at once. More ▸ Manage Sources… is where you review and prune them.

• The list shows every folder and Photos album you've imported into this project.
• Click the 🗑 trash next to a source to remove that whole folder or album — and all of its photos — from the project in one step.
• This only affects the project. The original folder on disk and your Photos albums are never touched.
• Great for swapping an album out: remove the wrong one here, then Import a different one.

Music & analysis

• More ▸ Choose Music… adds a background track that fades in, loops, and fades out under the slideshow. Change or remove it from the same menu.
• More ▸ Reset Analysis clears the automatic locations/duplicate/best-shot choices; your manual selections and captions are kept.

Play

• Play runs the full-screen slideshow: crossfades, gentle Ken Burns motion, location overlays, and a title at each new place.
• Controls: play/pause, next/previous, and Esc (or ✕) to exit.

Export

• Export… renders the slideshow to a video file, exactly as it plays.
• Choose 1080p or 4K and H.264 or HEVC. Progress is shown and you can cancel.

Settings vs. Project Settings

• Settings (⌘,) holds app-wide defaults — seconds per photo, Ken Burns, chapter titles, captions, export resolution/codec — plus your AI provider credentials (Ollama URL/model, OpenRouter key/model) and the default provider.
• Project Settings (main toolbar) overrides any of those per document. A new project starts from the defaults; whatever you change is saved inside that .tripshow file.

Privacy

• Analysis, playback and export run entirely on your Mac — your photos never leave it.
• The only exception is captions via a cloud provider (OpenRouter): that path uploads the photo. TripShow warns and asks you to confirm before switching to it, and flags it with a red banner. Apple and local Ollama keep everything on the machine.
• Your OpenRouter key is stored in app Settings, not inside the shared .tripshow file.