---
name: "descriptive_audio_tracks"
description: 'Write and mix audio-description (AD) tracks for video: spot narration cues into dialogue pauses, draft a narration script that follows AD writing standards, and mix narration over the program bed with ducking. Trigger on phrasings like ''add audio description'', ''write an AD script'', ''describe this video for blind viewers'', ''mix narration over this video'', or ''audio description track''.'
---

# Descriptive Audio Tracks

## Purpose

Audio description is a separate narration track that tells blind and low-vision
viewers what is happening visually. This skill covers the whole job: cueing
(where narration goes), writing (what the narration says), voicing/recording, and
mixing (how it sits in the final audio). It follows W3C WAI technique G166 and
WCAG 2.2 success criteria 1.2.3 (Level A) and 1.2.5 (Level AA) for prerecorded video.

## Workflow

1. **Understand the video.** Watch or get a transcript. Note dialogue windows (start/end
   of every spoken line) and critical sound effects or music moments that must not be
   covered.
2. **Spot the cues.** AD lives in the natural pauses between dialogue. Find every gap
   of ~1.5 seconds or more. Record each cue as `{start, end, text}` with times in
   seconds. Keep narration inside its gap; never let it bleed over dialogue.
3. **Write the script** following the writing rules in
   [references/writing_rules.md](references/writing_rules.md). Prioritize what matters,
   describe at the moment the action happens, never editorialize.
4. **Validate the cue sheet.** Run `bin/adcue check cues.json` (see Tooling below). It
   checks overlaps, gaps, and speaking-rate fit (~160 words/min target).
5. **Record the narration.** Any neutral voice works: studio VO, a narrator on mic, or
   TTS. Match tone to the material; keep it calm and clear. Record narration as one
   clean WAV, with narration only, at the same times as the cue sheet (silence between
   cues).
6. **Mix.** Duck the program bed under narration and combine:
   `[program][narration] sidechaincompress + amix` (see [references/mixing.md](references/mixing.md)).
   Deliver as a separate AD audio track (preferred: keeps the original untouched) or as
   a pre-mixed MP4.
7. **QC.** Play the mix blindfolded (or with the picture off). If the story makes sense
   without the picture, it is done. Verify no narration overlaps dialogue.

## Tooling

`bin/adcue` is a helper for cue-sheet work. JSON cue sheet format:

```json
[
  {"start": 12.5, "end": 16.0, "text": "A woman climbs into a small sailing boat."},
  {"start": 31.0, "end": 35.5, "text": "The sails billow in the wind."}
]
```

- `bin/adcue check cues.json` validates: cues sorted, none overlapping, each cue fits
  a ~160 words/min narration rate in its window, warnings for sub-1.5s gaps.
- `bin/adcue mixcmd --video in.mp4 --narration narration.wav --out out-ad.mp4`
  prints the ffmpeg command that ducks the program audio under narration and muxes
  the result. Requires ffmpeg on PATH.

## Output Contract

- **Cue sheet** (`cues.json`): one cue per gap, times in seconds, text in present tense.
- **Script** (`ad-script.md`): cues rendered in order, one line per cue with
  timecode, ready for a narrator to read.
- **Mixed output**: MP4 with the AD audio track (separate labeled track preferred,
  pre-mixed accepted), plus optionally a WebVTT `descriptions` file for HTML5 players.
- Every factual claim about standards in the deliverable comes from a primary source;
  the writing rules reference lists them.

## Operating Rules

1. Never describe what the audience can already hear. If dialogue or sound effects
   carry the information, skip it.
2. Never let narration overlap dialogue, critical sound effects, or music lyrics.
   Tight gap? Shorten the text, never the rule.
3. Present tense, concrete nouns, no interpretation of motive or emotion. Say "She
   slams the door" not "She slams the door, furious that he left."
4. Do not invent names for unnamed characters. Use role labels ("a guard", "the
   woman in red") until the story names them.
5. No em dashes in scripts or docs, no marketing language. Plain, direct sentences.
6. On-screen text that matters (signs, titles, messages) gets read aloud; decorative
   text gets skipped. Credits relevant to the program get described.
7. Extended AD (pausing the video for longer narration) is allowed only when the
   producer approved it; default to standard AD in natural pauses.