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

• Four ways to place descriptions
  • 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.

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.

Security and privacy

• No accounts and no login. If you expose AD Studio beyond your home network, put it behind a reverse proxy with authentication.
• 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.