# Data formats

> The files every tool reads and writes: the project folder, the timed words, the bar map, the line table, the board, the take registry, the ledger, the edit list and the review notes. Written before the first film, so the tools and the site agree from day one.

Every tool in [What to build](../toolkit/) reads and writes plain files in one project folder. Nothing lives only in a tool's memory: if a step is lost, the files say where the film is. This page is the contract; the site's own data (`data/*.json`) follows it too.

## The project folder

```
latency/
  book.json            the shot book: the one file every tool reads
  song/
    take.wav           the take a person picked, untouched
    stems/             vocals.wav, drums.wav, bass.wav, other.wav (Demucs)
    words.json         the timed words (from the lead stem)
    bars.json          the beat and bar map
    lines.json         the line table
  plates/              empty worlds from Midjourney, one file per plate
  frames/              first frames with him in them, one per shot
  windows/             the audio window of every sung shot
  takes/               every video take that came back, never deleted
  cut/                 edit.json, the renders, the review sheets
  ledger.jsonl         every paid call, one line each
  log.md               what happened, in the order it happened
```

## Timed words · song/words.json

Read off the lead-vocal stem, not the mix: the mix smears onsets.

```
[
  { "w": "Your", "t0": 12.48, "t1": 12.71, "line": 1 },
  { "w": "message", "t0": 12.71, "t1": 13.20, "line": 1 }
]
```

Times are seconds from the first sample of `take.wav`, to the hundredth.

## The bar map · song/bars.json

```
{ "bpm": 96, "beats_per_bar": 4, "first_downbeat": 0.42,
  "bars": [ { "n": 1, "t": 0.42 }, { "n": 2, "t": 2.92 } ],
  "sections": [ { "name": "Intro", "from_bar": 1, "to_bar": 4 } ] }
```

A cut is allowed only within 0.03 s of a bar line in this file.

## The line table · song/lines.json

One row per sung line, built from the lead stem's level (a line starts where the level rises above the floor and ends where it falls back), then named from the timed words.

```
[ { "n": 1, "text": "Your message came at midnight", "t0": 12.48, "t1": 14.90,
    "section": "Verse 1", "bars": "5–6", "held": false } ]
```

## The shot book · book.json

The board, the windows and the jobs in one file. Each shot:

```
{ "id": "S06", "bars": "17–19", "section": "Chorus 1", "look": "night-coat",
  "kind": "sung",                       // sung | silent | no-face | code
  "lines": [7, 8],                      // rows of lines.json it sings
  "plate": "plates/train-window-2.png",
  "frame": "frames/S06.png",
  "window": { "file": "windows/S06.wav", "seconds": 6, "lead_in": 0.7 },
  "prompt": "…",                        // written from the canon, checked by lint
  "takes": ["S06-a", "S06-b"],
  "pick": "S06-b" }
```

Rules the lint checks: the identity text appears once and word for word; a sung window is a whole number of seconds and opens on about 0.7 s of silence; every segment of the timeline has one clause of movement; no mood words.

## The take registry · takes/takes.json

```
[ { "id": "S06-b", "shot": "S06", "model": "seedance-2.5", "where": "higgsfield-api",
    "inputs": { "image1": "frames/S06.png", "image2": "kit/hal-face-sheet.png", "audio1": "windows/S06.wav" },
    "seconds": 6, "usd_list": 2.40, "file": "takes/S06-b.mp4",
    "verdict": "keep", "usable": [0.7, 5.6], "note": "lips late on 'way', fixed by sync" } ]
```

Verdicts: `keep`, `maybe`, `drop`. A dropped take stays on disk: the failure is data.

## The ledger · ledger.jsonl

One line per paid call, written before the call returns. The spend cap reads the sum.

```
{"t":"2026-11-20T21:04:11Z","what":"seedance","shot":"S06","usd":2.40,"job":"…"}
```

## The edit list · cut/edit.json

```
[ { "shot": "S06", "take": "S06-b", "in": 0.70, "out": 5.60,
    "at": 41.92, "path": "cut/paths/S06-b.json" } ]
```

`at` is the time in the song where the clip starts; `path` is the sync alignment of the take to its window.

## Review notes · cut/review.md

One heading per version (`## v1`, `## v2`), one bullet per note, each with the shot id and what to do. The film's making-of quotes these notes; the site renders them in the record.

## The image record · data/images.json

What the site shows for every generated image: id (`<batch>.<name>.<variant>`), film, batch, title, model, aspect, refs, match (face similarity to his sheet, 0–1, or `null`), look, shot, note, and the prompt exactly as it ran.
