PhotoDesc User Guide

Audio-described videos from your photos

1. Getting Started

Installing

Open the DMG file and drag PhotoDesc to your Applications folder. First launch, macOS will ask you to confirm you want to open it since it wasn't downloaded from the App Store. That's normal. Click Open. PhotoDesc runs on Apple Silicon (M-series) Macs.

Setting Up Your API Key

PhotoDesc uses Google's Gemini AI to look at each photo and write a description, and (optionally) to narrate it. You'll need a free Gemini API key.

1. Go to Google AI Studio and sign in with a Google account
2. Create an API key
3. When PhotoDesc launches the first time, it'll ask for that key. You can also click Skip for now and add it later. You can import photos without a key; you just need one to generate descriptions or AI narration.
4. The key is stored in your macOS Keychain, so you only enter it once

You can update the key anytime in Settings > API Key. Click Save, then Test to confirm it works. The dot in the top-right corner shows the key's status. ● API ✓ when it's connected, ● API ✗ if there's a problem.

Choosing a Voice

PhotoDesc can narrate with Google's natural Gemini voices (default: Kore) or with the built-in macOS voices (default: Samantha), which are free and work offline. Pick the engine and voice in Settings > Voice.

2. Basic Workflow

1. Add photos — Click ＋ Click here to add images in the middle of the window (or ＋ Add more images at the bottom once you have some). Pick one photo or several. A project folder is created automatically the first time you add images.
2. Generate descriptions — Click Generate All Text to have the AI describe every photo, or use the + chip on a single row to describe just that one. (The button becomes Generate Missing Text once some rows already have descriptions.)
3. Review and edit — Each photo shows up as a row with its description. Read it, edit the wording, re-crop the frame, change the voice, whatever you need (see the next section).
4. Pick a voice (and optionally music) — Set the voice in Settings; choose a background-music track from the Music menu at the bottom if you want one.
5. Choose the frame shape — Set the Aspect ratio (16:9, 9:16, 1:1, 4:5) and Frame rate on the project line above the photos.
6. Choose how to export — Flip the Export toggle to Per image or Sequence (details below).
7. Click Create Videos — PhotoDesc generates the narration and renders your video(s) into the project folder. Use In… instead if you want them somewhere else.

3. Two Ways to Export

The Export toggle at the bottom decides what you get when you click Create Videos.

Per Image

Each photo becomes its own short video, the image on screen while its description is read. Good for posting one at a time, or when each photo stands on its own.

Combined Sequence

All the approved photos play back to back as a single video, each shown while its narration plays, with optional dissolves between them. (Sequence is only available when you have more than one photo.)

4. The Review Screen

Every photo you add becomes a row. Here's what's on it:

• Thumbnail — A preview of the photo. Click Crop / Frame to reposition or zoom how it sits in the chosen aspect ratio.
• Description — The text the AI wrote. Click into it and edit freely; your changes are saved automatically.
• Text chip — A + generates a description if the row doesn't have one; a ↻ reopens it for a guided rewrite (you can add a note like "focus on the dog in the foreground" and the photo, current text, and your note are sent together).
• Voice chip — A + generates the narration audio; a ↻ regenerates it (after editing the text, for example).
• ▶ / ⏹ — Play or stop the generated narration for that row.
• Read by — Shows which voice the row will use.
• Reject — Leaves the photo out of the output. Click again to bring it back (it reads Rejected while excluded).
• Create — Renders just that one photo to a video, without doing the whole set.
• ⠯ handle — Drag to reorder photos (matters for Sequence export).

Generating audio costs money (see Settings > cost note); editing text and re-cropping are free. Nothing is final until you click Create Videos.

5. Voices and Background Music

Set the narration voice in Settings > Voice, a range of natural Gemini voices, or the free macOS voices. You can also override the voice on an individual photo.

To add music, pick a track from the Music menu at the bottom of the window (a few are built in, and ＋ Add your own… lets you import a file). The track is looped to the length of the video, faded in and out, and ducked. It drops down whenever the narration is speaking and comes back up in the gaps, so the words always stay clear. The ▶ next to the menu previews the track; the Volume slider in Settings sets how loud it sits under the voice (default 22%).

6. Output Files

Everything for a project lives in its folder under ~/Documents/PhotoDesc/ (or wherever you exported with In…).

After a render, an Open Folder button appears at the bottom so you can jump straight to the files in Finder.

7. Settings Reference

API & Model

Voice

Slideshow

Background Music

Framing

Dissolves & Transitions

Output

Accessibility

8. Troubleshooting

API key not found

If the top-right dot shows ● API ✗, open Settings, paste in your key, click Save, then Test. The key is stored in macOS Keychain after that.

No description generated for a photo

Make sure you have a working API key (the dot should read ● API ✓), then click the + chip on that row, or Generate Missing Text to fill in any that are blank. If a description came out wrong, click the ↻ chip and add a short note about what to focus on.

I don't hear music in the video

Pick a track from the Music menu before you click Create Videos. Selecting music only affects videos rendered afterward, and the volume slider must be above 0%. The music ducks low while the voice is speaking, so it's most audible in the gaps and at the start and end.

My project folder warning appeared

If you move or delete a project's folder in Finder while it's open, PhotoDesc shows a banner because it can no longer save there. Start a New Project, or reopen the folder if you can put it back.

Render was cancelled or interrupted

Press Cancel once for a graceful stop that keeps everything done so far; the narration you already generated is cached, so picking back up doesn't re-charge you.

9. Tips

Edit the descriptions to taste before generating audio. The AI gives you a solid first draft, but a quick human pass makes the narration feel intentional. Text edits are free; only the audio costs anything.

Use blank (no-description) photos as title cards or pauses, and turn on Randomize so a long slideshow breathes naturally instead of marching at a fixed beat.

For social media, set the aspect ratio to 9:16 (vertical) or 1:1 (square) before you render. It reframes every photo to fit, and you can fine-tune any individual crop with Crop / Frame.

Keep an eye on usage at Google AI Studio. The run log saved with each project lists an estimated cost if you want to track it.

10. Get in Touch

PhotoDesc is built and maintained by Brian Paris at Sounds and Colors. If you run into something this guide doesn't cover, find a bug, or just want to share how you're using it, send a note to Loading….

Real feedback from people actually using this is how the app gets better. Don't hesitate to reach out.