# What to build

> The tools behind the films, specified so that you or an agent can build them: what each takes and returns, the check that says it is done, and how far ours has got.

The tools are written while LATENCY is made. Each row has its spec, and the scripts in [the kit](../../kit/) that do it now. Download them all as `kit/hal-kit.zip`.

| Tool | Takes | Returns | Done when | In the kit | Status |
| --- | --- | --- | --- | --- | --- |
| `lyric` | a lyric draft | syllables per line, hook and verse lengths | every hook is 6–7 syllables and every verse line 10–13 | `lyric.py` | done |
| `songmap` | the picked take and its stems | the beat and bar map, the line table read off the lead stem's level | each line's start lands within 30 ms of its onset in the stem | `analyze.mjs`, `bars.py`, `lines.py` | done |
| `shotbook` | the board and the line table | windows, prompts and jobs for every shot | `shotbook lint` passes the audit | `lines.py`, `windows.py`, `shotbook.py lint` | done |
| `run` | the jobs and a spend cap | one take per job, re-rolls only for failures | the total stays under the cap | `takes.mjs` | in use |
| `sync` | the takes and the windows | an alignment path per take (DTW) | lips stay on the words after every pause | `check.py`, `lips.py` | measures the path and the lag; does not warp yet |
| `cut` | the paths and the song | the film at −14 LUFS, a 9:16 cut, the flash check | no word clipped, no seam heard | `cut.py` | the cut on the bars; LUFS, 9:16 and the flash check to come |
| `cut sheets` | the cut | one sheet of eight frames per shot | two reviewers can read the film shot by shot | `check.py` (one sheet per take) | to come |

## lyric

`python kit/lyric.py <film>` checks the lyric in the film's data, and `python kit/lyric.py --file draft.txt` checks any draft with `[Section]` tags. It prints every line with its syllables and writes `<film>/song/lyric.json`. A chorus line has to be 6–7 syllables and a verse line 10–13. A verse line of 5–8 reads as a chopped fragment and is flagged. A pre-chorus outside 8–14 is a warning. Spoken sections are not checked. Numbers are counted as spoken: "300" is "three hundred". Syllables are counted by rule, with a short dictionary for the words the rule gets wrong. It is right on almost every word and off by one on a few, so read the flagged lines aloud before changing them.

LATENCY's lyric, approved at checkpoint 2, has three lines outside the rule. Verse 2 ends on 14 syllables ("I laugh back at a joke you don't remember anymore"). The first two lines of the final chorus are 8 each ("Wait for me, I'm already here"). They stay as they are: a line the director approved is not touched.

## shotbook lint

`python kit/shotbook.py lint <film>` runs the board audit from the recipe on `book.json` and writes `<film>/book.lint.json`. It checks these rules:

- no gaps or overlaps along the song;
- every cut within 0.03 s of a beat;
- every sung word inside a shot that lists its line;
- his share of the screen at least 70%;
- never more than two bars without him (a warning);
- sung windows of 4–15 whole seconds, with a 0.7 s lead-in;
- no two shots from one first frame;
- no banned words in any prompt;
- every shot names its size;
- no TODO.

LATENCY passes. The one warning is the two shots without him: the board insert that opens the film (4 bars) and the train in the server field (5 bars). Both are in the board as approved at checkpoint 4.
