AD Studio

Add audio description to videos: a narrator that says what is on screen, mixed into the original soundtrack.

AD Studio watches your video with a vision model, writes short descriptions, voices them with a text-to-speech engine and mixes them into a descriptive audio track (or a longer video that pauses for them). It is made for lectures, slide decks, screen recordings and everyday videos, so people who are blind or have low vision can follow along.

It runs as one small Docker container (no GPU, no PyTorch) and talks to three services over HTTP. It is built with Unraid in mind (there is a Community Apps template) but runs anywhere Docker does.

Features

• Five ways to place descriptions
  • Pauses, extend when needed (default): speaks in gaps in the original speech; when a description needs more time than its gap, the picture freezes just long enough for it to finish (a slightly longer video only when needed).
  • Fit in pauses: only speaks in gaps in the original speech.
  • Talk over speaker: speaks over the video and lowers the original audio underneath.
  • Extended (pause the video): freezes the picture to fit longer descriptions, producing a longer video.
  • Describe screen changes: detects page and slide switches and handwriting, and describes them without pausing.
• Vision backends: local Ollama (default qwen3-vl:8b-instruct) or Google Gemini (cloud, gemini-2.5-flash).
• Edit before you build: a description table you can edit, with a preview player that follows along. Rows that are too long for their gap are flagged.
• Batch mode: drop many videos, review each one's descriptions for a few seconds, and download everything as a .zip.
• Private by design: the server keeps no uploads or results. Everything lives in a per-browser-tab scratch folder that is deleted when the tab closes, on a timer, and at startup. You download your results.
• Download / load descriptions (.json) to and from your own computer.
• Settings can be saved from the UI or preset with environment variables, with Test buttons for each service.

What you need

AD Studio itself only orchestrates. You run these alongside it:

A GPU helps Whisper and Ollama a lot but is not required by AD Studio itself. If you only use Gemini you do not need Ollama.

Install

Unraid (Community Apps)

Search for AD Studio in Community Apps and fill in the three service addresses. Put Scratch on a cache-pool path (not inside docker.img).

To install by hand before it appears in the store, add this template URL under Docker, Add Container, template:

https://raw.githubusercontent.com/Chrisv006/ad-studio/main/unraid/ad-studio.xml

Docker Compose

git clone https://github.com/Chrisv006/ad-studio.git
cd ad-studio
cp .env.example .env      # edit the three service URLs
mkdir -p config scratch && sudo chown 99:100 config scratch
docker compose up -d

Open http://localhost:8585, then use the Admin tab to check the connections and set a password.

Docker run

docker run -d --name ad-studio --user 99:100 -p 8585:8585 \
  -v /path/to/config:/config -v /path/to/scratch:/scratch \
  -e WHISPER_URL=http://SERVER:9000 \
  -e OLLAMA_URL=http://SERVER:11434 \
  -e TTS_URL=http://SERVER:8880/v1 \
  ghcr.io/chrisv006/ad-studio:latest

Both folders must be writable by UID 99 / GID 100 (Unraid's nobody:users).

Configuration

Every setting is an environment variable; blank or unset uses the built-in default. Values saved from the UI (Save settings) override the environment, and Reset settings goes back to it.

Using it

1. Analyze: pick a video and press Analyze. The video is transcribed, a vision model describes it, and the descriptions appear in a table.
2. Edit: click a row to jump the video there, fix wording or timing, delete or add rows.
3. Build: produces descriptive.mp3, a preview.mp4 and (in Extended mode) the longer video. Download them.

In Batch, drop several files, set a review time and press Analyze & build all. You can pause on any video to edit its descriptions. Closing the tab cancels the batch.

Choosing Gemini or this server

Describe with is on the main page, per browser tab. Google Gemini is greyed out until a key is available: the server's key (KEY_MODE=server), or the visitor's own key typed into the Gemini API key box (KEY_MODE=user). Choosing Gemini pops up a warning that video frames and text go to Google and that charges may apply, with OK / Cancel.

Admin tab

Anything that configures or could break the app lives here, not on the main page: the Whisper, Kokoro and Ollama addresses, the Ollama vision model and frames per description, the Gemini model (with a Load models button), the shared Gemini key (KEY_MODE=server), Save settings / Reset settings, a Test button for each of Whisper, Kokoro, Ollama and Gemini, and the list of feedback sent with the Feedback button.

Set a password under Admin password in the tab (stored only as a salted hash in /config), or fix one with ADMIN_PASSWORD. Until a password is set, anyone who can open the page can use Admin. The server itself reads these settings and ignores what a browser sends for them, so the lock cannot be bypassed from the page or the API.

Security and privacy

• There are no user accounts. Only the Admin tab can be password protected. If you expose AD Studio beyond your home network, set an admin password and put it behind a reverse proxy with authentication, or set ADMIN_FEATURES=off.
• Public deployments should keep KEY_MODE=user so your own Gemini key is never stored or shared.
• When Gemini is the backend, video frames and transcript text are sent to Google. With Ollama everything stays on your network.
• Uploads and results exist only in /scratch while your tab is open.

Development

pip install -r requirements.txt
WHISPER_URL=... TTS_URL=... OLLAMA_URL=... python -m ad_studio     # needs ffmpeg on PATH

The UI is Gradio (pinned at 6.30.0); the preview window depends on Gradio's table markup, so re-check the preview popup and row highlighting when upgrading. Styles are in ad_studio/assets/app.css, the preview script in ad_studio/assets/preview.js.

License

MIT, see LICENSE.