narration-handoff
Skill1 starsChanged 31 days agoMITView on GitHub
Hand a narration script to a text-to-speech run that happens elsewhere, then verify what comes back. Use when generating voice-over outside the session, or when re-recorded audio needs checking for actual change.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-agent-hardeningSkill
- article-interviewerSkill
- article-outlinerSkill
- build-walkthroughSkill
- cross-model-judge-evalSkill
- narrated-explainerSkill
- page-to-videoSkill
- prompt-engineerSkill
- render-page-to-videoSkill
- tts-narration-buildSkill
- {{name}}Skill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
One voice, one set of settings, all files: If a file is regenerated later, regenerate it with identical settings.
- Distinctive: line 38
Ask for a durations table: id, title, target, actual, delta.
- Distinctive: line 40
Write numbers as words in the script itself ("thirty two million", "ten to the sixtieth").
- Very specific: line 73
Check each clip with ebur128.
- Very specific: line 83
Check what the destination actually serves before asking for a format.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Narration handoff
For voice-over generated outside this session: on a local machine with open-source TTS, by a person in a booth, or by any pipeline you do not control. Two jobs: write a brief that works with no other context, and verify what comes back.
Generate audio last
Audio is the most expensive and least reversible step in a narrated piece. Every edit to the script invalidates a recording. Hold it until the text has stopped moving, even when the script feels nearly done. Most of the churn in these projects traces back to recording too early.
What to hand over
Two files, and nothing that assumes prior context. The receiving session starts cold.
A lines file, one entry per segment:
{ "id": "scene-01", "n": 1, "title": "Cold open",
"target_seconds": 33.8, "text": "Most pills you have ever taken..." }Regenerate target_seconds whenever the script changes. Stale targets make the returned durations table pure noise, and it is the table you retime from.
A brief. The instructions that carry weight, in rough order:
- Use the
textfield verbatim. It matches on-screen captions word for word. Do not reword, re-punctuate or expand abbreviations. - Check current install instructions before starting. Say plainly that your knowledge of these packages may be out of date and the project README wins over anything in the brief about package names, flags or model filenames.
- Engine preference order, stop at the first that works, with a reliable CPU fallback named. Ask it to record which engine, model and voice it settled on.
- Render a few voices on one segment and let the person choose, rather than picking one. Voice is a taste decision and costs a minute to make properly.
- One voice, one set of settings, all files. If a file is regenerated later, regenerate it with identical settings.
- Normalise loudness across all files, around -16 LUFS integrated for spoken web audio, with a true-peak ceiling. Trim leading and trailing silence, then add back about 150 ms of lead-in so playback does not clip the first syllable.
- Fix mispronunciations with the engine's phoneme override, never by editing the text, because the audio has to stay identical to the captions.
- Listen to the named segments before declaring it done. Name them specifically. See below: this is the instruction most likely to be skipped.
- Build it as a single re-runnable script with the output set versioned in both the folder name and the filename.
- Ask for a durations table: id, title, target, actual, delta.
Write numbers as words in the script itself ("thirty two million", "ten to the sixtieth"). Doing it in the text rather than asking the engine to handle it removes a whole class of failure.
For scale: a small local model on CPU synthesises around 17 scenes of documentary narration in a few minutes, so regeneration is cheap and worth asking for whenever the text changes.
Verify what comes back
Hash at the source, not at the destination
Ask for hashes computed on the generating machine, before upload, alongside the files. The destination can only tell you that something is wrong, never what. Files silently failing to update is the single most common failure in this handoff and it costs hours if diagnosed by ear.
Duration proves nothing, and neither does one hash
A deterministic pipeline fed the same text produces the same length, so two files can match in duration and be different recordings, or be the same recording twice. Hash twice per file:
md5sum scene-16.m4a
ffmpeg -v error -i scene-16.m4a -f s16le -ar 16000 -ac 1 - | md5sumThe first catches a file never replaced. The second decodes to raw PCM first, so it catches a file re-encoded from the same source: different bytes, identical speech. Only when both differ has anything been re-recorded. Report per file, by name, so the sender can see which specific files did not come through.
Neural TTS is not bit-reproducible, and that is useful
Re-synthesising identical text with identical settings generally gives the same length but different samples. So byte-identical output across a regeneration is not evidence the engine is cached or repeatable. It is proof the generation step did not run for those files.
The usual causes, worth naming when you report the problem: a --only-style flag skipping scenes, a reuse-cached-intermediate flag, output written to a versioned folder different from the one being uploaded, or a manual rename sitting between the build output and the uploaded filenames. Non-clobbering renames (mv -n) are especially good at leaving stale files that look current.
Measuring is not listening
Loudness, peak and duration can all be correct while the narration says the wrong thing. Mispronounced numbers, units and technical terms pass every measurement. If the brief asked for specific segments to be checked by ear, confirm that happened; it is routinely skipped because the measurements look like verification.
Loudness: compare like with like
Check each clip with ebur128. Spoken web audio wants about -16 LUFS integrated; the spread between clips matters more than the absolute value.
Measure the delivered clips, not a downstream mux. A mono clip upmixed with -ac 2 loses 3 dB of per-channel sample peak to ffmpeg's rematrix while its integrated loudness stays identical, because EBU R128 sums both channels. Measuring the mux and the clips will give different peaks for the same audio, and the difference is not a bug.
Retime to the audio
Set each segment's on-screen duration to its clip length plus a short tail, around 0.8 seconds, so a scene does not cut on the last syllable. Update any total-duration text in the interface, which is easy to leave stale.
Container and format traps
Check what the destination actually serves before asking for a format. Some hosts refuse .m4a while serving .mp4 happily, and the two can hold the identical AAC stream, so renaming is enough and no re-encode is needed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

