~/.claude/skills/script-audio-align/SKILL.md

---
name: script-audio-align
model: haiku
description: Align an authoritative script (gold standard) to a word-timestamped transcript from groq-transcribe, and output a timestamp for every script word, paragraph start and end times, and a list of words the transcript heard that the script does not have. Use when the user wants a script timed against recorded audio, a per-word or per-beat breakdown of a voice-over, or a check of how closely a recording follows its script.
---

# script-audio-align

The script is the gold standard. Every script word gets a time. The transcript only supplies the times. Script words that the transcript did not hear are interpolated between the nearest heard words, and marked `interpolated` so they are never mistaken for measured times.

## Steps

1. Get a transcript with word timestamps using the `groq-transcribe` skill. Use a Latin-script prompt when the script is in Latin letters. Do not use text from the same script as the prompt, because that makes the match circular; a different beat, or generic Hinglish, is fair.
2. Prepare the script as plain text. Put `[Pn]` at the start of a line to mark paragraph n. Other non-empty lines are paragraphs in order. Lines starting with `#` or `---` are skipped.
3. Run:

```
node "<home>\.claude\skills\script-audio-align\scripts\align.mjs" <script.txt> <transcript.json> <outDir> [--sim 0.6]
```

4. Read `<outDir>\alignment.md` for the paragraph table and the word table, and `<outDir>\alignment.json` for the machine-readable version.

## What the outputs mean

- `source: matched`: the script word matched a heard word with similarity at or above `--sim` (default 0.6). `sim` and `heard` show the match.
- `source: interpolated`: the script word was not heard. Its time is spread evenly between the neighbouring matched words, weighted by length. It is an estimate.
- `extra`: words the transcript heard that the script does not contain. These are ad-libs, mishearings, or real deviations from the script. Check them before assuming the recording is wrong.
- Coverage is `matched / script words`. A low score means mishearing or a bad transcript, not necessarily a bad recording.

## How matching works

- Devanagari in the transcript is transliterated to Latin first (`deva2latin`), so mixed-script Whisper output still aligns.
- Words are compared on a normalised spelling: lowercase, no punctuation, and common Hinglish variants collapsed (`toh`/`to`, `oo`/`u`, `ee`/`i`, `ph`/`f`, double letters).
- Global alignment (Needleman-Wunsch) keeps the order of the script and the transcript, so repeated words cannot match out of place.

## Known results

- B0 hook (315 script words, 6 paragraphs): with the Latin prompt and Devanagari transliteration, 288 of 315 script words matched (91.4%), mean similarity 0.95. Before transliteration the coverage was 77.8%, because the Devanagari half of the transcript was being dropped.
- The lowest coverage is P5 and P6 (80%), where the transcript itself is garbled ("eek", "kuyo", "Yee"). Those times come from interpolation and should not be quoted as measured.
- The Latin-prompt transcript used the script's own sentences as the prompt, so the 91% is optimistic. A fair test needs a prompt from other text.
- Word timestamps were not checked against the audio by ear.