Animated map documentaries

---
name: faceless-map-doc
description: Build narrated animated map documentaries with geographic camera moves, dated overlays, routes, relief or parchment maps, thumbnails and a verified video render.
---

## Public package setup

Export `KIT` to your extracted kit directory and `SKILL` to this extracted style directory.
Read README.md for dependencies, missing assets and setup. Example media and private review
material mentioned below are not bundled; create your own input/output paths.

Build from the script and a geographic storyboard, using the shared kit at `$KIT`. Read [SPEC.md](SPEC.md) before designing shots, and [CREDITS.md](CREDITS.md) before delivery. The renderer is data driven: change the timeline or project data rather than hard-coding a new topic into scene.js.

## One-command workflow

```sh
./build.sh --script examples/test/script.txt --project examples/test/project.json \
  --out examples/test --quality max --speed 1.08
```

`--quality draft|standard|max` defaults to standard. Optional `--speed 1.0`. Voice and Scribe outputs and the music bed are reused if present; remove the affected files when changing script, voice or music prompt. `build.sh` regenerates the plan, stills, render, mix and thumbnail, ending with the kit's full `qc.py` gate. It exits nonzero on open findings.

For a first draft without a storyboard: `--topic "Country name"` replaces `--project`. This resolves a Natural Earth country and makes four geographical framings. It does not invent historic boundaries or events. Refine its project/timeline with sourced dates, coordinates and narrative beats before production.

## Authoring

The title formula is “The Entire History of [region] on a Map in [N] Minutes”. Open on a geographical tension and its consequence, then establish the first era/action. Third-person documentary voice at 155–175 words/minute, concrete verbs and short clauses. A short test may be an opening excerpt of a longer proposed documentary; label that in its notes.

Use `examples/test/project.json` as the working schema. Each shot has a narration phrase in `start` (or explicit seconds), `size`, `angle`, `move`, `transition`, and camera `from`/`to` with `center:[longitude,latitude]`, horizontal `span` in degrees, and `bearing` in degrees. `continuous` begins from the preceding camera endpoint; `hard` is recorded in cuts. Keyframes ease deterministically. Keep map coordinates shared through a match move. A cut must reveal a new era, location, or meaningful scale.

The measured references sustain ~11.7-second shots, but the first 15 seconds often traverse several map scales without cutting. Use wide geography → close coast/chokepoint → match pull-out to the territory → historic route. A close geographic pass in the opening creates the scale contrast seen in the strongest references. Default to ~0.6–2.0 visible shot changes/10s, never one static wide. Map closeups serve the role that object/hand closeups serve in other genres. Match camera direction and territory position at a continuous transition. Avoid unrelated wipes and full-screen branding.

Supported layers:

- `labels`: text, geographic coord, size, priority, offset, optional serif/pin; their times may be narration phrases. The layout solver measures glyphs and tries alternate positions around the anchor. Low-priority labels fade near the frame edge and are omitted when no safe space exists. For a two-continent hook, anchor both continent names inland so they remain readable through the spoken phrase. Captions and HUD receive space first.
- `routes`: geographic coords, start/end, draw duration, color, optional ship and scale. Set `preview:true` when the date/era or a footer announces the route before the moving line starts; a faint dotted schematic then appears with the shot, while the bright line and ship stay tied to the narrated action. `frontlines` use the same progressive line layer without a ship. The solid trail ends at the moving vessel; its progress must share the vessel position, never outrun it. Only the dotted preview may show future travel. Use `ports:true` to mark coastal endpoints; snap them to supplied geographic coastline geometry when the narration describes departure or arrival. Use enough coastal/ocean waypoints; check every segment at full size. Schematic sailing paths should be called schematic in source notes.
- `units`: geographic coord, color, start/end; small navy/ochre markers fade rather than pop.
- `territories`: GeoJSON feature, year, source, color, start/end. Year/source are required. Supply a polygon per historical state; modern atlas data is geographic context, not historical evidence. Never stretch a modern country into an ancient empire.
- `year`, `era`, `palette:'parchment'`: a dated historical scene and warm grade. Dates are categorical labels; no fictitious smooth border morphs between unlike political states.
- `preview_times`: optional six explicit moments in seconds; choose readable emphasis and distinct camera framings rather than transition midpoints.
- `captions`: selective emphasis, start/end anchors, text (newlines supported), position as screen fractions, size/color. Maximum two short lines. Do not transcribe every spoken word.
- `map`: image and its geographic bbox `[west,south,east,north]`. Default Mediterranean relief. The bundled NASA global texture provides a satellite fallback for other regions. Custom regional relief should have a manifest and explicit licensing.

No reference logos or characters. An optional mascot should be original and relevant; the supplied ship is an original connected illustration. Relief contains artistic detail, not precise elevations. See [ASSETS.md](ASSETS.md).

## Individual stages and inspection

```sh
PY=$KIT/.venv/bin/python
KIT=$KIT
$PY $KIT/py/voice.py examples/test/script.txt examples/test/vo.mp3 --voice English_CaptivatingStoryteller --emotion calm
$PY $KIT/py/scribe.py examples/test/vo.mp3 examples/test/words.json --lang en
$PY scripts/plan.py examples/test/script.txt examples/test/words.json --project examples/test/project.json --quality max --out examples/test/timeline.json
$PY scripts/previews.py examples/test/timeline.json --out examples/test/stills --ss 2
node $KIT/js/render.mjs --root . --page scene.html --data examples/test/timeline.json --ss 2 --out examples/test/silent.mp4
$PY scripts/thumbnail.py examples/test/timeline.json --out examples/test/thumbnail.png
```

After editing src files, bundle with `node_modules/.bin/esbuild src/scene.js --bundle --outfile=dist/scene.js`. `scripts/prepare.mjs` extracts the atlas; `scripts/terrain.py --width 6144` rebuilds the regional relief. Dependencies are locked in package-lock.json; install only within this skill using `npm ci --ignore-scripts`. Read generated texture and stills with the image viewing tool.

The renderer crops each map plate to the visible geographic viewport before scaling. `scripts/render.py` invokes the unmodified kit renderer with at most three foreground attempts for transient Chrome screenshot failures. Draft uses SS1. Standard/max use SS2; the cached 6144px relief is shared so all levels keep geographic correctness. Max adds six-moment reference comparison and full-size flagged-frame review. Standard/max run a 2-second vision preflight before the full render. For timing benchmarks use `scripts/benchmark.py` (a short same-content sample at each quality).

Continuous instrumental underscore: restrained strings, low pulse, distant woodwind, no vocals or trailer hits. Keep the bed near -16dB before kit ducking. Use 2–4 earshot effects for major camera/era/route beats, normally -18 to -22dB. The planner writes cues.json and music-prompt.txt; build mixes to -14 LUFS.

## QC and delivery

Preview six moments beside reference frames; view the sheet and fix the largest craft gap. Render → music → mix → QC. Every canvas text element is measured and reported through `window.__qc`; reserve safe margins. Object movement is a function of time and all entrances/exits fade. No wall-clock animation or external network in the scene.

```sh
$PY $KIT/py/qc.py examples/test/final.mp4 --out examples/test/qc \
  --qc examples/test/silent.qc.jsonl --timeline examples/test/timeline.json \
  --words examples/test/words.json --style 'Animated map documentary'
```

Read report.md and flagged.jpg. View every medium/high frame at full size, fix the cause in the renderer/planner, render again and rerun QC until exit 0. A disputed finding is still open. Give QC the actual cinematography conventions: close geographic framing and pull-out reveals deliberately crop geography, while all text must remain safe; vessel symbols are not literal scale. Do not use those intentions to excuse broken labels, disconnected routes or a real framing error. The audited test intentions are in examples/test/qc/intentions.md. Ignore files are only for truly intentional content and must explain it; never ignore a bug to obtain a pass. Inspect 12 final full-size frames and the thumbnail yourself. Keep script, VO, words, timeline, cues, music, final, thumbnail and qc in the output folder. Notes should identify approximation, remaining stylistic differences and measured render cost.