---
name: soundtrack
description: "Turns a song or a script into a video's soundtrack plus the timing data the picture syncs to: beats, downbeats, sections and word timings as JSON, narration and music generated with ElevenLabs (asking before spending credits), sound effects, and the video's mix of voice, music and effects. Use it whenever a video or animation needs its music analyzed, a voiceover made, lyrics or words timed, background music or effects created, or its audio mixed, even if the user only says \"make it sync\" or \"add a voiceover\". Not for podcasts, voice cloning, noise removal, mastering a song for streaming, or app code that calls a speech API."
---

# soundtrack

Turns what a video has (a song, a script, or nothing yet) into audio plus the timing data the picture syncs to: audio in `videos/<video>/audio/`, `data/audio.json` (beats, downbeats, sections, envelopes, onsets, cues) and/or `data/words.json` (timed sung or spoken words), as the code-video engine reads them (`--out <dir>` outside an audara project). What the user sets (words, voice, length, levels, silence) is followed; the rest are defaults. `<skill>` is this skill's folder, other paths the project's; every script runs with uv and has `--help` with examples.

## Fixed
- **Spending waits for a yes.** Before any generation that costs credits, say what it will make (characters, length, credits, voice, model) and wait; the scripts print that plan and refuse to spend without `--yes`. A budget the director sets in their own words is the yes for what fits it (its running total goes in the video's TREATMENT.md, Decisions). A key in the environment, or a question tool that answers before anyone could, is not a yes. Make one voice block first and check it (pace, loudness, what was said) before the rest.
- **The key stays in the environment** (`ELEVENLABS_API_KEY`): never in a file, a log or a command line.
- **Generated audio is an asset, not a build step.** Generate once, keep the file and the request record beside it; the scripts regenerate only when the request changed, and renders never call the API.
- **Licenses are respected:** say what a voice, a model or a plan allows before relying on it, and again when handing over audio for a client or a monetized video, naming the account's plan as the scripts print it (free ElevenLabs plans are non-commercial; some alignment models are non-commercial too).
- **Numbers are measured, not claimed.** Report what the scripts measured.

## Which path
- **The user's song**: `uv run <skill>/scripts/beats.py <song> --video <video>` gives beats, downbeats, sections, envelopes and onsets, on a fitted grid when the tempo is steady. Pass on its time line as printed: never tell anyone to shift the times. Words on screen: `uv run <skill>/scripts/align.py song <song> --lyrics lyrics.txt --video <video>` (heavy: models download once).
- **A window of the song**, for a video shorter than it: `uv run <skill>/scripts/beats.py window --video <video> --from <start> --to <end> [--fade <seconds>]` cuts `audio/<song>-window.wav` from the song's samples and writes the window's data in video time (the whole song's stays in `data/song/`). An end off a downbeat moves to the nearest one (a length asked in seconds is no reason for `--exact`; one called exact, or a slot, is): tell the director the length it prints. It warns, with the fix, when an end cuts a sung word, writes `window.png` and `clicks.m4a`, and prints the `video.json` edit.
- **A script to narrate**: a script the director gives is locked: its words, in order. Respellings go in a `--say` map ("SQL" said as "sequel"); visual or timing notes leave the spoken text (they are the storyboard); a problem (too long, a word the voice will trip on) is raised with a fix, not edited in. `uv run <skill>/scripts/eleven.py tts script.txt --video <video> --voice <id>` prints what it would make and cost; after a yes, `--only 1 --yes` makes the voice test, then `--yes` the rest once it passes (the director's ear when they want it). One paragraph is one block; the picture cuts in the silences between blocks; phrase edges are snapped onto the sound. Pick the voice from `eleven.py voices` (free previews), with the director or yourself when it's left to you.
- **Music**: `eleven.py music plan` (free) with sections that match the edit (`--sections` start times with `--length`, or `--lengths`) or the narration's chapters (`--from-narration`); after approval, `eleven.py music compose --plan <file> --takes 2 --yes`, then `--pick K` (by its measurements when it's left to you; say nobody has listened) and the `beats.py` command it prints. The plan asks for no long intro and a resolved ending unless `--free-form` (a slow swell, a fade-out). Music you synthesize is fine too: keep the seeded script (packages pinned) beside the audio, write its grid and cues with `beats.py grid` (scenes find a cue with `audio.cue('hit')`), level it with `mix.py build` (it limits 4 dB at most).
- **Effects**: synthesized in code (free, seeded like music), or `eleven.py sfx "<prompt>" --n 4`, which screens the candidates by analysis before anyone listens; place each one by its measured onset (a whoosh by its peak, on the cut).
- **Mix**: `uv run <skill>/scripts/mix.py build --video <video>` mixes `videos/<video>/mix.json` into `mix.wav` and `music-only.wav` at delivery loudness and prints the video.json edit; `mix.py measure <file>` reports what a listener hears (loudness per section, the build into each hit, a phone-speaker check). A gentler build or hit: `build_lu` or `hit_lu` in mix.json, with the reason.
- **Word timings against the sound**: narration from `eleven.py tts` is snapped already. `standin.py` levels and snaps its own. Any other voice (the user's recording, a provider they name: follow them, spending rules included) is levelled as eleven.py levels narration (-16 LUFS, true peak at or under -1 dBTP, as `mix.py measure` reads them), timed with `align.py song <audio> --lyrics <script> --no-separate --video <video>`, then `uv run <skill>/scripts/align.py check <audio> --words videos/<video>/data/words.json --fix`; a generator you write ends with that check, so a re-run stays on it. On a song, `check` validates the structure only, and `align.py song`'s review list and sheets are the check.
- **No key, or no yes yet**: run the command anyway (`eleven.py tts <script>`, or `music plan` with its length): it spends nothing and prints the cost and what a key adds. Say both in one line, name the free paths, and go on with the one that fits unless the user picks another: their own recording; a stand-in voice, `uv run <skill>/scripts/standin.py <script>` (Kokoro-82M, Apache-2.0: its license line says what it allows and how the swap keeps sync); music you synthesize; or silence (`"audio": null` and a `duration`). The picture never waits for the sound.

If a sandbox stops uv writing its cache, set `UV_CACHE_DIR` to `.audara-cache/uv` in the project (git-ignored), or `C:\uvc` when the project's path is long (uv fails past Windows' 260 characters).

## Show the work
Before a step that takes minutes, a line on what comes. After each step, and in every turn's last reply, even one that only confirms earlier work: every file you wrote, the data file first; the numbers the scripts measured, under their labels (a song: tempo, fit residual rms and worst, first and last beat, the time line; a voice: duration, LUFS, true peak, worst phrase edge before the snap, its license or plan line; music: length, hit time and contrast, the build, LUFS, true peak); the review images in `out/<video>/`; with no key, what a key adds and its cost; what is not checked yet and the cache lines (where, size on disk) as printed; and, when the preview runs, `?v=<video>&t=` links to the moments that matter.

## Read when
- references/elevenlabs.md: before generating anything (costs and how to estimate them, plan terms, voices and models, lessons for voice, music and effects).