descriptive_audio_tracks v1.0.2

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. 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). 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.