paces 0.0.1__tar.gz → 0.0.2__tar.gz

paces-0.0.2/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Claude Code session droppings (dev skills et al. stay tracked)
+.claude/.system/
+.claude/handoffs/
+
+# Media and evidence stores never live in the repo
+media/
+*.annot
+*.annot.sqlite
+scrap/

paces-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paces-0.0.2/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: paces
+Version: 0.0.2
+Summary: Turn instructional media into structured, interactive learning material
+Project-URL: Homepage, https://github.com/thorwhalen/paces
+Project-URL: Repository, https://github.com/thorwhalen/paces
+Project-URL: Documentation, https://thorwhalen.github.io/paces
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dance,instructional-video,learning-material,practice,segmentation,steps,tutorial
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.6
+Provides-Extra: cli
+Requires-Dist: argcomplete>=3; extra == 'cli'
+Requires-Dist: argh>=0.30; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: argh>=0.30; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# paces
+
+Turn instructional media into structured, interactive learning material.
+*Put it through its paces.*
+
+Take a video of someone teaching something — a dance routine, a kata, a
+recipe — plus, optionally, notes and a steering prompt. `paces` segments it
+into named steps, builds a structured **step document** (an AST for
+step-by-step instruction), and renders that into learning material: a
+practice page with counts and deep links today, other guides later.
+
+```bash
+pip install paces
+```
+
+## Quick example
+
+```python
+from paces import segment, to_document, render_html
+
+seg = segment(
+    "https://youtu.be/q_TUyxUhoEw",
+    steps=[
+        ("Mise en place", 2),
+        ("Pas pieds pointe et ronde", 6),
+        ("Soleil avec les bras", 4),
+        ("Déhanchés", 8),
+    ],
+    grid={"unit": "eight", "subdivisions": 8, "tempoBpm": "129.2", "origin": "51.2"},
+)
+doc = to_document(
+    seg,
+    doc_id="que-calor",
+    title="Chorégraphie Que Calor",
+    source="https://youtu.be/q_TUyxUhoEw",
+)
+open("page.html", "w").write(render_html(doc))
+```
+
+The page lists every step with its counts, links each one back into the video
+(both the at-tempo run-through and the slow breakdown, when both are known),
+and — because the document carries a metric grid — includes a count-along
+transport that paces you through the routine at the measured tempo.
+
+Same thing from the shell:
+
+```bash
+paces segment VIDEO_URL --steps steps.json --grid grid.json --output seg.json
+paces to-document seg.json --source VIDEO_URL --title "My routine" --output document.json
+paces render document.json --output page.html
+```
+
+## How it thinks
+
+**Analysis and rendering are separate phases** with a serialisable document
+between them — like a parser emitting an AST and a backend interpreting it.
+Renderers depend on the document, never on the analyser.
+
+**Segmentation is a seam, not a stage.** `segment(media, segmenter=...)` —
+segmenters are registered capabilities, the default follows from what is
+present, and "the user typed the boundaries" is a first-class segmenter, not
+a fallback. A segmenter that cannot *name* steps returns honest unnamed
+boundaries (`flags: ['naming-abstained']`) rather than inventing names.
+
+**The document keeps what the learner actually counts.** A dance step lasts
+"4 eights", not "14.86 seconds" — seconds are derived from the metric grid
+(tempo + origin), never stored. A step can have *several* source spans (the
+run-through and the breakdown are the same step seen twice). Uncertainty is
+content (`OpenQuestion`), and human edits are protected from regeneration
+(`Lock`).
+
+## The pieces
+
+| you want | reach for |
+|---|---|
+| cut media into steps | `segment(media, steps=..., grid=...)` → `Segmentation` |
+| explicit/human boundaries | `segment(media, boundaries=[...], steps=[names])` |
+| the committed artifact | `to_document(seg, ...)` → `StepDocument` |
+| a practice page | `render_html(doc)` |
+| wall-clock times from counts | `resolve(doc)` |
+| sanity checks | `validate_document(doc)` |
+| what segmenters exist | `capabilities()` / `paces list-segmenters` |
+| add a segmenter | `register(Capability(name=..., gives="segmentation", target="mymod:fn", needs={...}))` — a new file, nothing edited |
+
+## Status
+
+Young and moving. The document schema is validated by round-tripping a real
+proof of concept ([an interactive dance-practice
+page](https://thorwhalen.com/que_calor_dance/)) through it — see
+`tests/test_roundtrip_poc.py`. Media derivation (auto-cropped looping clips),
+intrinsic segmenters (scene/beat/speech detection), and the evidence layer
+are designed (see `docs/`) and arrive next.

paces-0.0.2/README.md

@@ -0,0 +1,92 @@
+# paces
+
+Turn instructional media into structured, interactive learning material.
+*Put it through its paces.*
+
+Take a video of someone teaching something — a dance routine, a kata, a
+recipe — plus, optionally, notes and a steering prompt. `paces` segments it
+into named steps, builds a structured **step document** (an AST for
+step-by-step instruction), and renders that into learning material: a
+practice page with counts and deep links today, other guides later.
+
+```bash
+pip install paces
+```
+
+## Quick example
+
+```python
+from paces import segment, to_document, render_html
+
+seg = segment(
+    "https://youtu.be/q_TUyxUhoEw",
+    steps=[
+        ("Mise en place", 2),
+        ("Pas pieds pointe et ronde", 6),
+        ("Soleil avec les bras", 4),
+        ("Déhanchés", 8),
+    ],
+    grid={"unit": "eight", "subdivisions": 8, "tempoBpm": "129.2", "origin": "51.2"},
+)
+doc = to_document(
+    seg,
+    doc_id="que-calor",
+    title="Chorégraphie Que Calor",
+    source="https://youtu.be/q_TUyxUhoEw",
+)
+open("page.html", "w").write(render_html(doc))
+```
+
+The page lists every step with its counts, links each one back into the video
+(both the at-tempo run-through and the slow breakdown, when both are known),
+and — because the document carries a metric grid — includes a count-along
+transport that paces you through the routine at the measured tempo.
+
+Same thing from the shell:
+
+```bash
+paces segment VIDEO_URL --steps steps.json --grid grid.json --output seg.json
+paces to-document seg.json --source VIDEO_URL --title "My routine" --output document.json
+paces render document.json --output page.html
+```
+
+## How it thinks
+
+**Analysis and rendering are separate phases** with a serialisable document
+between them — like a parser emitting an AST and a backend interpreting it.
+Renderers depend on the document, never on the analyser.
+
+**Segmentation is a seam, not a stage.** `segment(media, segmenter=...)` —
+segmenters are registered capabilities, the default follows from what is
+present, and "the user typed the boundaries" is a first-class segmenter, not
+a fallback. A segmenter that cannot *name* steps returns honest unnamed
+boundaries (`flags: ['naming-abstained']`) rather than inventing names.
+
+**The document keeps what the learner actually counts.** A dance step lasts
+"4 eights", not "14.86 seconds" — seconds are derived from the metric grid
+(tempo + origin), never stored. A step can have *several* source spans (the
+run-through and the breakdown are the same step seen twice). Uncertainty is
+content (`OpenQuestion`), and human edits are protected from regeneration
+(`Lock`).
+
+## The pieces
+
+| you want | reach for |
+|---|---|
+| cut media into steps | `segment(media, steps=..., grid=...)` → `Segmentation` |
+| explicit/human boundaries | `segment(media, boundaries=[...], steps=[names])` |
+| the committed artifact | `to_document(seg, ...)` → `StepDocument` |
+| a practice page | `render_html(doc)` |
+| wall-clock times from counts | `resolve(doc)` |
+| sanity checks | `validate_document(doc)` |
+| what segmenters exist | `capabilities()` / `paces list-segmenters` |
+| add a segmenter | `register(Capability(name=..., gives="segmentation", target="mymod:fn", needs={...}))` — a new file, nothing edited |
+
+## Status
+
+Young and moving. The document schema is validated by round-tripping a real
+proof of concept ([an interactive dance-practice
+page](https://thorwhalen.com/que_calor_dance/)) through it — see
+`tests/test_roundtrip_poc.py`. Media derivation (auto-cropped looping clips),
+intrinsic segmenters (scene/beat/speech detection), and the evidence layer
+are designed (see `docs/`) and arrive next.

paces-0.0.2/docs/README.md

@@ -0,0 +1,143 @@
+# `paces` — a library for turning instructional video into learning material
+
+*Put it through its paces.* The name is settled (`adr/0002`); so is the core abstraction
+(`adr/0003`). These docs were written while the package was still called `stepped` — where the
+prose says "stepped", read `paces`.
+
+---
+
+## What this is
+
+A working proof-of-concept exists. In one session, a YouTube video of a choreographer teaching
+a dance, plus a hand-written HTML aide-mémoire, plus a paragraph of steering prompt, became a
+deployed interactive practice page: <https://thorwhalen.com/que_calor_dance/>.
+
+The user now wants that generalised into a library, integrated with the **reelee** /
+`video_gen` fleet. Your job is to research, design and build it. **This folder exists so you
+do not start from scratch.** It records what was built, the parameters that were expensive to
+find, the failures and what each one teaches, the user's own framing of the generalisation,
+and an inventory of what already exists in the fleet.
+
+Nothing here is a design you must follow. It is evidence and framing. Argue with it.
+
+## Read in this order
+
+| | file | why |
+|---|---|---|
+| 1 | **`01-what-was-built.md`** | The POC, factually. Includes the incident list — every failure is a requirement in disguise. |
+| 2 | **`03-design-brief.md`** | The user's own framing: the parse→AST→render metaphor they explicitly asked to have recorded, the three generalisation axes, and the constraints the POC discovered. |
+| 3 | **`04-reelee-core.md`** | What reelee is, what a reelee "genre" is, and what to reuse. **This determines the package boundary**, so read it before deciding anything structural. |
+| 4 | **`07-annotation-model.md`** | The proposed shape of the AST — the contract between analysis and rendering. |
+| 5 | **`05-fleet-inventory.md`** | What already exists across `video_gen`, and honestly which parts are stubs. |
+| 6 | **`02-technical-recipes.md`** | Every technique with working parameters. Reference, not narrative — come back to it when implementing. |
+| 7 | **`06-surfaces-and-conventions.md`** | House style: architecture-first seams, qh, py2mcp, storage, frontend, deploy. |
+| 8 | **`08-naming-candidates.md`** | PyPI-verified name options, and a better word for the "subject" axis. |
+| 9 | **`09-subgenre-candidates.md`** | What to build after dance, and what each choice would force the core to get right. |
+| 10 | **`10-session-archaeology.md`** | The 27 MB session transcript, and how to query it when these docs fall short. |
+| — | **`adr/`** | The decisions. **`0003` `video + segmenter`** — read it before designing the analysis phase. `0002` the name. `0001` the alignment engine (intent) — note that much of what you'd otherwise build already exists in `muvid`, `mixing` and `kodokan`. |
+| — | **`alignment/`** | The research behind that ADR: one file per method family, prepared so you don't start from a literature search. |
+| — | **`KICKOFF.md`** | A paste-ready prompt to start a fresh session on this. |
+| — | **`REGISTRATION.md`** | **One command still pending** to register `paces` in the `video_gen` group, and why `priv pkg add-package` is deliberately deferred. |
+| — | **`poc-reference/`** | The actual scripts and data. Read `poc-reference/README.md` first — several of those files are recorded dead ends. |
+
+## The one-paragraph version
+
+Take instructional media (a video of someone teaching something) plus optional notes and a
+steering prompt. **Analyse**: extract signals (audio structure, transcript, beat grid, subject
+tracking), segment into named steps, align against the notes, and emit a structured step
+document — an *AST*. **Render**: consume that AST to produce learning material — an
+interactive practice page today, other guides later. The AST is the contract; the analyser and
+the renderers depend on it and not on each other. A shared core handles step-by-step
+instructional content in general (reelee's word: **genre**); *subgenres* — dance, kata,
+recipe, repair — specialise the segmentation signals, the duration unit, and the rendering.
+
+## Four findings from the research that change the starting position
+
+These came out of `04`–`07` and are worth knowing before you read anything else, because each
+one removes work you might otherwise plan for.
+
+1. **"Genre" is an `nw` concept, not a reelee one.** `nw` (`$PP/t/nw`) owns `Project`,
+   `Transform`, `Genre`, freshness and jobs, with a real registry
+   (`register_genre`, `register_genre_resolver`, `register_genre_initializer`,
+   `register_genre_project_factory`). If you want a "step-by-step" genre with a "dance"
+   subgenre, that machinery already exists and reelee is a *consumer* of it. `04-reelee-core.md`.
+2. **reelee is deliberately small.** Its own `__init__` says the substance lives in the focused
+   packages below it — `lacing`, `falaw`, `nw`, `artful` — and reelee's surface is
+   orchestration. That strongly suggests this library is **another focused package below
+   reelee**, not a fork of it and not a plugin inside it. Confirm with the user, but start from
+   that hypothesis.
+3. **`lacing` is already the annotation substrate**, and reelee already ships
+   regenerate-without-losing-human-edits machinery on top of it. That is constraint §5 of
+   `03-design-brief.md` — the one that looked hardest — already solved. `07-annotation-model.md`
+   recommends owning only a small *document* type and delegating everything below it.
+4. **The step structure was never in `clips.json`.** It was in the page's own
+   `const ROUTINE = [...]`; `clips.json` is the *span* table. Reading the POC as a two-layer
+   model (steps ↕ spans) rather than one flat list is the single most useful reframe in these
+   docs.
+5. **Most of the analysis phase already exists in the fleet, unwired.** `muvid/align.py` is an
+   aligner registry with dispatch and a `lacing` writeback; `muvid.footage.select_score` is a
+   constrained sequence solver; `mixing.audio` has beat grids, speech/music segmentation and
+   cross-correlation offset alignment; `kodokan` has a complete, tested, Apple-Silicon-native
+   **pose front-end that has never been pointed at an alignment problem**. `adr/0001` and
+   `alignment/00-existing-in-fleet.md` have the map. Do not write a second one of any of these.
+
+## What the POC actually proves
+
+- Separating analysis from rendering is real, not architectural decoration: the media was
+  re-rendered three times and the page a dozen times from unchanged manifests.
+- A step legitimately has **several source spans** (at-tempo run-through *and* slow
+  explanation). Six of nine blocks shipped both. A one-span model is wrong on day one.
+- Cheap signals go a long way: a sub-bass energy ratio separates speech from music in five
+  lines and did more work than anything else in the session.
+- An LLM looking at timestamped contact sheets makes genuinely good editorial calls about
+  which few seconds show a move — and is slow and expensive doing it.
+
+## What the POC does *not* prove
+
+- **Nothing here segmented a video cold.** The nine steps came from the input document; the
+  analysis confirmed, corrected and timed them. Cold segmentation is a different, harder
+  problem and the POC has no evidence about it.
+- Everything assumed **one subject**. Two people breaks the crop envelope, the face-slot logic
+  and the privacy mask simultaneously.
+- The renderer was a patched copy of the input document. There is no template contract yet.
+
+## Suggested first moves
+
+1. Read `04-reelee-core.md`, then settle the **integration shape** with the user. The research
+   points at "a focused package below reelee, registering an `nw` genre" — test that
+   hypothesis rather than assuming it. Boundaries are the expensive thing to move later.
+2. ~~Settle the name~~ — **done, `paces`** (`adr/0002`). Still open: the better word for the
+   "subject" axis. Leading candidates in `08-naming-candidates.md §6`: `discipline`, `craft`,
+   `grammar`, `idiom`. **Do not run another availability sweep** — 684 names are already
+   checked, and that file is now also the name pool for sub-packages this work spawns.
+3. ~~The v1 scope fork~~ — **dissolved by `adr/0003`.** Segmentation is a seam, not a stage:
+   `video + segmenter=`, kept open-closed by a strategy pattern. A segmenter's information can
+   be **intrinsic** (features of the media), **external-explicit** (coordinates handed over),
+   **external-derived** (computed from the surrounding annotations), or **mixed** — and mixed is
+   the normal case. Many *intrinsic* segmenters share one shape — featurize → reduce → threshold
+   → regularize — which the package should ship as composable stages so common cases are
+   assembled rather than authored. "Ask the user" is first-class. Read that ADR, then
+   `alignment/07-segmenter-strategies.md` **with its correction preamble**, then decide which
+   two segmenters v1 ships.
+4. Write the AST schema and validate it by **re-expressing the POC's `clips.json` in it**
+   (`poc-reference/artifacts/clips.json`). If the dance case does not round-trip, the schema is
+   wrong. That is a cheap, real test available on day one.
+5. Only then pick seams and build (`03-design-brief.md §6`, `06-surfaces-and-conventions.md`).
+
+## Open questions for the user
+
+Collected from across these docs; raise them early rather than guessing.
+
+1. ~~Notes required in v1, or cold segmentation?~~ Answered by `adr/0003`.
+2. Integration shape with reelee? (decides the package boundary — the live one)
+3. Is the renderer part of this library or a sibling package?
+4. How much of the analysis may be LLM-driven — what is the acceptable cost per project?
+5. What is the editing story? Human edits must survive re-analysis.
+6. ~~The name~~ (`paces`, `adr/0002`) — but still the word for the "subject/genre" axis.
+
+## Provenance
+
+Built from session `0f75703c-6761-4aa0-b796-aafe02c94155` (2026-08-27/28). The full transcript
+is on disk and queryable — `10-session-archaeology.md`. Docs `01`, `02`, `03`, `10` and
+`poc-reference/README.md` were written from direct session context; `04`–`09` were researched
+by subagents and each carries its own "verified vs inferred" notes.

paces-0.0.2/docs/alignment/README.md

@@ -0,0 +1,47 @@
+# Alignment research
+
+*What this folder is for: preparation for a possible dedicated **alignment tool** in the
+`video_gen` / reelee fleet — the thing that answers "given some artifacts and some media,
+which span of the media does each artifact correspond to?". The decision to build it is
+recorded as an intent in `../adr/0001-alignment-engine-as-a-fleet-package.md`; **read that
+first**, then come here for the method-by-method detail.*
+
+The user's framing of the problem and of the top surface:
+
+> *"This is a very common task in our reelee work: being able to match and align things. More
+> specifically … being able to align annotations/artifacts to segments of audio and/or video."*
+>
+> *"I'm imagining that the highest surface would be an agent that can study the context, what
+> is available, and have a list of possible methods/algorithms/tools it could use. It could use
+> beats. It could use the transcribed words (and transcribe if they're not available). It could
+> use some knowledge of the order of the artifacts to be matched. It could use gestures."*
+
+## The files
+
+| file | what it covers |
+|---|---|
+| **`00-existing-in-fleet.md`** | **Start here.** What the fleet already has. Verdict: the capability doesn't exist as a capability, but nearly every part does — `muvid/align.py` is the v0 registry, `muvid.footage.select_score` is the order-prior solver, `mixing.audio` is the signal layer, `kodokan` is a complete but dormant pose front-end, `lacing` is the settled output substrate. Also argues *separate package vs a module in `lacing`* (§4.3) and concludes separate. |
+| `01-text-to-audio-alignment.md` | ASR with word timings, true forced alignment (CTC, MFA, aeneas), **fuzzy paraphrase→transcript matching** (the common reelee case, and the hard one), VAD, diarization. |
+| `02-music-rhythm-and-structure.md` | Beats, downbeats, tempo and its octave errors, **phase/offset** (tempo gives spacing, not where bar 1 starts), music structure segmentation, music-vs-speech discrimination, audio-to-audio alignment and fingerprinting. |
+| `03-visual-signals.md` | Scene cuts, motion energy and optical flow, **pose estimation and pose→segmentation**, repetition/periodicity detection, gesture and action recognition, hand/object interaction, OCR. This is the file that closes the "we never used gestures" gap. |
+| `04-semantic-and-llm-matching.md` | CLIP/SigLIP frame–text scoring, CLAP for audio, video-text retrieval, the **LLM-over-timestamped-contact-sheets** pattern written up as a reusable technique, transcript structure extraction, and confidence calibration. |
+| `05-sequence-alignment-algorithms.md` | The algorithm layer under everything else: DTW and subsequence DTW, gapped Needleman–Wunsch, CTC segmentation, Viterbi, **change-point detection with a known segment count**, grid fitting for `(offset, period)`, evidence fusion, and how to evaluate an aligner at all. |
+| `06-the-planner-surface.md` | The top surface. Proposes collapsing all five sibling method Protocols into one `Capability(needs, gives, …)` record, a measured ~1.4 s/min context probe, and a deterministic ranked graph walk — with the LLM deliberately outside the control loop. |
+| **`07-segmenter-strategies.md`** | **The `video + segmenter` seam** the user settled on. A catalogue of ~16 video-only segmentation families plus six richer input tiers (step list, structured document, steering prompt, chapters/subtitles/**re-watch heatmap**, ask-the-user, escalation), organised by *what input is present* because that is what picks the default. Then the `Segmenter` protocol — reusing `06`'s `Capability` with **two** new products and **seven** new facts and no new fields — the generated default-selection table, and the recommendation: three segmenters in v1, `novelty-k` as the video-only default, **and it deliberately does not name the steps**. |
+| `04-evidence/` | Real experiment scripts the semantic agent wrote and ran (SigLIP SO400M, CLAP, VLM scoring, calibration, ASR cue extraction). Kept because the numbers in `04-…md` came from them. Scratch quality — read them as evidence, not as library code. |
+
+## How to use this
+
+These files are a **menu with prices**, not a plan. Each method entry states what signal it
+needs, what it produces, its cost per minute of media, its licence, and the failure mode that
+will bite. The planner file is what turns the menu into a selection procedure.
+
+Two things worth internalising before reading in depth, both from the POC that motivated all of
+this (`../01-what-was-built.md`):
+
+- **The cheapest signal did the most work.** A five-line sub-bass energy ratio separated
+  talking-head from music-with-dancing and made everything downstream tractable. Any design that
+  reaches for pose or a VLM first will be slower *and* worse.
+- **No single method was sufficient.** The answer came from combining a cheap audio feature, a
+  beat model, ASR, a vision-language judgement, and the order prior. Fusion and confidence are
+  not optional extras — they're the point.

paces-0.0.2/docs/poc-reference/README.md

@@ -0,0 +1,46 @@
+# POC reference code and artifacts
+
+*What this is: the actual scripts and data from the session that produced
+<https://thorwhalen.com/que_calor_dance/>. **This is not a library and must not be treated as
+one** — it is a pile of session tooling, written to be thrown away, kept because the
+parameters in it were expensive to find. Read it for the recipes, not the structure.
+`../02-technical-recipes.md` explains every one of them.*
+
+Everything ran under `~/.pyenv/versions/3.12.12/envs/p12/bin/python`, from a working directory
+containing `source.mp4`.
+
+## `tools/` — the pipeline
+
+| file | what it does | worth keeping? |
+|---|---|---|
+| `sheet.py` | Labelled contact sheet over a time window — `sheet.py START END STEP OUT.jpg [COLS]`. Every tile stamped with its absolute timestamp. | **Yes.** This is how an LLM looks at video. The timestamps are the whole point. |
+| `zsheet.py`, `sheet_crop.py` | Same, cropped to the subject. Written by subagents mid-session to judge a wide shot. | Merge into one tool. |
+| `mkclip.py` | Cut + auto-crop + encode one clip as gif/mp4/webp. Holds `crop_box()`: YOLO person boxes → robust percentile envelope → forced aspect → clamp. | **Yes** — `crop_box()` especially. |
+| `track.py` | Whole-video person tracking at 5 fps into `boxes.npz`. | **No.** Abandoned: far too slow (>45 min on CPU). Kept as a record of the dead end. |
+| `bg.py` | Empty-room plate as an 88th-percentile-per-pixel composite. | Only for *compositing*. Do not use it to *find* the subject — see `../02-technical-recipes.md §7`. |
+| `stylize.py` | The anonymisation pipeline, adapted from kodokan and made streaming. Contains the narrowed head-band fix. | **Yes**, with the licensing caveat. |
+| `build_media.py` / `build_media_styl.py` / `restyle_clips.py` | Batch drivers: manifest → mp4 + gif + poster for every clip. Three generations of the same script. | As a spec for what the render stage does. |
+| `build_page.py` | Renderer. Splices a `MEDIA` map into the source document's own JS and patches its HTML by string surgery. | **Read it, then do the opposite.** It is the clearest possible argument for a real template contract. |
+| `shot.py` | Playwright screenshot + console/HTTP error capture. | **Yes.** Verification, and image generation from the page's own CSS. |
+| `ship.sh` | Rebuild page → refresh the deploy app dir. | Trivial, illustrative. |
+
+## `artifacts/` — the intermediate representation
+
+| file | what it is |
+|---|---|
+| `clips.json` | **The POC's entire AST.** 15 entries. `src: "RT" \| "BD"` is run-through vs breakdown — the two-passes-over-the-same-material idea in its crudest form. Analysed in `../07-annotation-model.md`. |
+| `crops.json` | `{clip_id: [x, y, w, h]}` — a derived cache, correctly kept out of the semantic model. |
+| `transcript.json` | mlx-whisper output for the whole 651 s. Note how it degrades over the music section (hundreds of near-empty segments, invented numbers) and is excellent over the spoken breakdown. |
+| `source-video-metadata.json` | Trimmed `yt-dlp --write-info-json`. `availability: "unlisted"` drove a real publishing decision. |
+
+## `render/` — the output side
+
+| file | what it is |
+|---|---|
+| `rendered-page.html` | The deployed page, self-contained apart from `media/`. The transport/metronome, the per-card clip tabs, and the IntersectionObserver playback are all in here. |
+| `og.html`, `icon.html` | Social image and favicon, as HTML screenshotted at DSF 2 by Playwright — so the type and gradient match the page exactly, for free. |
+| `howto.html` | The annotated-card infographic. Generated: it takes a screenshot of a real card, reads the real bounding boxes of the annotated elements out of the DOM, and lays the connectors onto those measured anchors. |
+| `annotated-card.jpg` | The rendered result of `howto.html`. |
+
+The media itself (mp4/gif/jpg, ~17 MB) is not copied here; it lives in
+`~/Dropbox/py/proj/tt/tw_platform/apps/que_calor_dance/frontend/media/`.