# cinematic-film

Adopt this skill: https://proskills.md/skills/other/moh4696-cinematic-skill-skills-cinematic-film

Page: https://proskills.md/skills/other/moh4696-cinematic-skill-skills-cinematic-film
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/cinematic-film/SKILL.md
size: 9607
sha: 132766ea60a84bfc16aee3ee7e492f9ec74f6f20
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/SKILL.md

````text
---
name: cinematic-film
description: Makes narrated cinematic films entirely from code, on any subject. One continuous camera glides over one designed world of photos, documents, cards, maps with routes and big numbers, with every stamp, highlight and number landing on the narrator's word, then sound effects, an optional score and burned-in captions. For documentaries and history, product launches, brand and founder stories, science and tech explainers, biographies and true crime. Covers the script, voiceover from any TTS split into timed lines, images (archives with their licences, your own photos, AI stills), a beat table, the scene, self-review stills and a memory-safe parallel render. Use for "make a cinematic video about", "documentary about", "explainer video", "launch film", "Vox-style video", "evidence board animation", or turning a story into a video for X, YouTube or TikTok.
---

# Cinematic film

A film made this way is one camera move over one world. Every photo, card, clipping, map and number lives on one big board, and the camera travels between them along string, routes and arrows as the story moves. Every visual hit is timed to the word the narrator says. It is all code (Skia in Python), so it renders the same every time, any topic fits, and a new voice re-times the whole film by itself.

Built from a 5:22 documentary about Al Capone, then opened up to any subject. The rules here were written from what broke while making it.

## Tools

| File | What it does |
| --- | --- |
| `scripts/check_setup.py` | Checks Python, skia-python, ffmpeg, fonts and memory; says what to install |
| `scripts/get_fonts.py` | Fetches open-licensed fonts (Bebas Neue, Homemade Apple) for any text role this machine lacks |
| `scripts/new_project.py` | Starts a project from `assets/template/` (a runnable explainer), or the documentary example with `--example` |
| `scripts/make_beats.py` | Writes `beats.md`, the table you approve; lints chronology, line length, digits in spoken text |
| `scripts/tts_say.py` | Free scratch voice (macOS `say`, espeak-ng, or any TTS command) to time the film before the final voice |
| `scripts/split_takes.py` | Cuts whole-section takes into one clip per line and flags suspect cuts |
| `scripts/build_narration.py` | Joins the lines into `audio/narration.m4a` and `audio/timing.json`, which the film is built on |
| `scripts/fetch_commons.py` | Searches Wikimedia Commons, downloads with licence and credit, refuses non-free files, writes `credits.md` |
| `scripts/make_map.py` | Projects public-domain boundaries (any country or region) for the map |
| `scripts/prep_assets.py` | Grades every image into one look (black and white, sepia or natural colour); generates the board textures |
| `scripts/engine.py` | The film engine: camera, spotlight, items, maps, looks, film finish |
| `scripts/render.py` | Stills, contact strips, the cue list, and the parallel MP4 render |
| `scripts/build_sfx.py` | Synthesises every sound effect from the cue list (no samples, nothing to license) |
| `scripts/mix_soundtrack.py` | Voice, effects and optional music, ducked and loudness-normalised |
| `scripts/burn_captions.py` | Burns one of four caption styles into the finished film and writes an SRT |

Needs Python 3.9+, `pip install skia-python numpy pillow` (scipy optional) and ffmpeg. Run `scripts/check_setup.py` first; on Linux or Windows, also run `scripts/get_fonts.py` per project. All commands take `--project <folder>`.

## Pick the film

| Kind | Look | Images | Typical items |
| --- | --- | --- | --- |
| History, true crime, investigation | `wall`, `slate` | Archive photos and documents, graded `bw` | Prints, torn clippings, stamps, red string, map routes |
| Product launch, brand or founder story | `studio`, `charcoal` | Your product shots and team photos, graded `natural` | Cards, big numbers, counters, arrows |
| Science, engineering, how it works | `blueprint`, `paper` | Diagrams, archive or AI stills | Cards, counters, pen marks, maps |
| Tech, space, trailers | `night` | Screenshots, renders, AI stills | Big type, counters, routes, cards |

Mix freely: the looks are a board and a finish, and every item works on every look. `references/story.md` has a story shape for each kind.

## The rules

1. **One hero per line.** Each narration line has exactly one thing the camera is on. The spotlight dims everything else.
2. **Hits land on the spoken word.** A stamp slams on "charged", not on the line start. Time everything with `doc.W(line, "word")`.
3. **Show a phrase one way.** Either type it on screen or show it on a real document, never both. Body copy on documents is grey rows, never filler words.
4. **Time only moves forward after the opening.** A cold open may jump ahead. After one bridge line ("Four years earlier..."), story time only goes forward.
5. **Type you can read on a phone in one second.** Big condensed caps. A typed label on screen should be about 3% or more of frame height.
6. **Less is more.** Strings fade after their beat, and old items dim. The final pull-back should look composed, not cluttered.
7. **Nothing invented that looks real.** Real photos and documents get credits. A document drawn in code is labelled a recreation and quotes only words that were really written. AI images are fine for illustration, but never as evidence of a real event or a real person.

## Workflow

Stop for the user's approval at the four gates (marked **Gate**).

1. **Story.** Research, then write `script.json`: takes (sections) of lines, each with `text`, `spoken` (numbers as words), `hero` and `typed`. Keep fact notes alongside. 60 to 90 seconds is about 150 to 230 words. Details are in `references/story.md`.
2. **Beat table.** Run `scripts/make_beats.py` and fix every lint warning. **Gate:** the user approves `beats.md`, including the facts.
3. **Images.** List every image in `photos.json`: its id, kind and where it comes from.
   - Archive images: `fetch_commons.py search`, `category` and `get`.
   - The user's own files: drop them in `<project>/assets/photos/`.
   - AI stills: generate them in one style (the `motion-assets` skill plans and prices them).
   - `references/archive.md` covers other archives and the rights rules.
4. **Scratch voice.** Run `tts_say.py`, then `split_takes.py`, then `build_narration.py`. Listen to every line `split_takes.py` flags. Now the timings are real.
5. **Assets.** Run `make_map.py` if the story travels, then `prep_assets.py`.
6. **Scene.** Write `scene.py`: lay out the board in clusters per section, add items on `doc.L`/`doc.W` times, then camera and spotlight keys (`film.shot`). Read `references/film.md`. Both shipped projects show the patterns: `assets/template/scene.py` (explainer, studio look) and `assets/wright-flyer/scene.py` (documentary, every item type).
7. **Look test.** Run `render.py --probe` on one still per line at 1280x720 and look at all of them, then `--strip` on every big camera move. **Gate:** show the user stills of the opening and the look.
8. **Draft.** Render the first 30 seconds at 1280x720 with the scratch voice. **Gate:** the user watches it.
9. **Final voice.** Record it with any TTS or a person (`references/voice.md`). Run split, build, and probes again; nothing in the scene changes.
10. **Sound.** Run `render.py --cues`, then `build_sfx.py`, then `mix_soundtrack.py`, adding a score if wanted. Read `references/sound.md`.
11. **Finish.** Do the full render, then `burn_captions.py` and the SRT. Read `references/performance.md` before rendering at 1440p or 4K. Hand over `credits.md` with the film.

## Self-review, every time

Look at the stills before you claim anything works. These are the mistakes that showed up, every one in a real render:

- Dark ink on a dark board: invisible. Use light type on dark looks, or `bar_h=0.92` for a full label block behind dark type.
- The camera moved on but the spotlight stayed behind, leaving a dark frame. Use `film.shot()` unless they should part.
- Map scale too small: a whole coast smaller than one photo. Pick `K` so each place with prints gets its own room (`references/film.md`).
- Map labels colliding. Put the label on the side away from its neighbour.
- A cluster straddling the map's edge. Keep clusters either on the map or clearly off it.
- Highlights a few pixels off their words. Use `PaperDoc.phrase_spans`, and `doc.on(print, fx, fy)` with fractions read off a grid overlay of the image.

## Shipped projects

- `assets/template/`: "From Cherry to Cup", a 25 second explainer in the studio look, made of cards, arrows and a counter, with no images. `new_project.py my-film` copies it. Give it a scratch voice and it renders.
- `assets/wright-flyer/`: "Twelve Seconds", a 90 second documentary about the first flight and the $50,000 rival who crashed twice. It uses seven public-domain photos, the US map, two typeset documents and every item type.

```bash
python3 scripts/new_project.py wright --example
python3 scripts/fetch_commons.py get --project wright
python3 scripts/make_map.py --project wright && python3 scripts/prep_assets.py --project wright
python3 scripts/tts_say.py --project wright && python3 scripts/split_takes.py --project wright && python3 scripts/build_narration.py --project wright
python3 scripts/render.py --project wright --size 1280x720 --out out/draft.mp4 --audio audio/narration.m4a
```

## Related skills

From [Open 3D Skills](https://github.com/Moh4696/open-3d-skills): `motion-assets` plans and prices AI stills when a film needs illustration, and `frame-capture` records web pages instead of code-drawn films.
````

## File: skills/cinematic-film/scripts/build_narration.py
size: 4988
sha: 302c6f0685589c6b906fd53ae4cfa2fdb671af94
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/build_narration.py

```text
#!/usr/bin/env python3
"""Assemble the per-line clips into one narration track and the timing file the film is built on.

  python3 build_narration.py --project my-film                 # natural read (tempo 1.0)
  python3 build_narration.py --project my-film --target 75     # fit the whole film to 75 s

Trims the silence off both ends of every clip, so pacing is set here (each line's gap_after from
split_takes.py) and not by whatever padding the voice engine added. --target solves for the one
tempo change (pitch kept) that lands the film on that length, and refuses anything outside
0.90-1.15x: beyond that the read sounds wrong, and the fix is a shorter or longer script.

Reads   audio/segments.json, audio/lines/segNN.wav
Writes  audio/narration.m4a (-16 LUFS), audio/timing.json
"""
import argparse
import json
import pathlib
import subprocess
import sys

TEMPO_LIMITS = (0.90, 1.15)
TRIM = ("silenceremove=start_periods=1:start_silence=0:start_threshold=-50dB,areverse,"
        "silenceremove=start_periods=1:start_silence=0:start_threshold=-50dB,areverse")

def run(cmd):
    r = subprocess.run(cmd, capture_output=True, text=True)
    if r.returncode != 0:
        sys.exit(f"FAILED: {' '.join(map(str, cmd))}\n{r.stderr[-2000:]}")
    return r.stdout

def duration(path):
    return float(run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(path)]).strip())

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--target", type=float, default=0.0, help="finished length in seconds; 0 keeps the natural read")
    ap.add_argument("--lead", type=float, default=0.9, help="silence before the first word (s)")
    ap.add_argument("--tail", type=float, default=3.0, help="hold after the last word, for the final pull-back (s)")
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    adir = proj / "audio"
    segments = json.loads((adir / "segments.json").read_text())["segments"]
    work = adir / "trimmed"; work.mkdir(exist_ok=True)

    for seg in segments:
        src = adir / "lines" / f"seg{seg['id']:02d}.wav"
        if not src.exists():
            sys.exit(f"missing line clip: {src} (run split_takes.py)")
        run(["ffmpeg", "-y", "-v", "error", "-i", str(src), "-af", TRIM, "-ar", "48000", "-ac", "1", str(work / f"raw{seg['id']:02d}.wav")])

    raw_speech = sum(duration(work / f"raw{s['id']:02d}.wav") for s in segments)
    fixed = a.lead + a.tail + sum(s["gap_after"] for s in segments[:-1])
    tempo = 1.0 if a.target <= 0 else raw_speech / (a.target - fixed)
    if not TEMPO_LIMITS[0] <= tempo <= TEMPO_LIMITS[1]:
        sys.exit(f"tempo {tempo:.3f} is outside {TEMPO_LIMITS} for a {a.target}s film ({raw_speech:.1f}s of speech + "
                 f"{fixed:.1f}s of pauses). Rewrite the script shorter or longer instead of distorting the read.")
    print(f"speech {raw_speech:.2f}s + pauses {fixed:.2f}s, tempo {tempo:.4f}")

    timeline, parts, cursor = [], [], a.lead
    pdir = work / "parts"; pdir.mkdir(exist_ok=True)

    def silence(sec, tag):
        p = pdir / f"sil_{tag}.wav"
        run(["ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "anullsrc=r=48000:cl=mono", "-t", f"{sec:.3f}", str(p)])
        return p
    parts.append(silence(a.lead, "lead"))
    for i, seg in enumerate(segments):
        dst = work / f"seg{seg['id']:02d}.wav"
        run(["ffmpeg", "-y", "-v", "error", "-i", str(work / f"raw{seg['id']:02d}.wav"), "-af", f"atempo={tempo:.6f}",
             "-ar", "48000", "-ac", "1", str(dst)])
        d = duration(dst)
        timeline.append({"id": seg["id"], "scene": seg["scene"], "caption": seg["caption"], "vo": seg["vo"],
                         "start": round(cursor, 3), "end": round(cursor + d, 3), "duration": round(d, 3)})
        parts.append(dst)
        cursor += d
        if i < len(segments) - 1:
            parts.append(silence(seg["gap_after"], f"g{seg['id']}")); cursor += seg["gap_after"]
    parts.append(silence(a.tail, "tail"))
    total = round(cursor + a.tail, 3)

    lst = pdir / "concat.txt"
    lst.write_text("".join(f"file '{p.resolve()}'\n" for p in parts))
    track = adir / "narration.m4a"
    # loudnorm resamples to 96 kHz internally; force 48 kHz back out (some players choke on 96 kHz AAC)
    run(["ffmpeg", "-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", str(lst),
         "-af", "loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000", "-ar", "48000", "-c:a", "aac", "-b:a", "192k", str(track)])
    (adir / "timing.json").write_text(json.dumps({"total_duration": total, "lead_in": a.lead, "tail_out": a.tail,
                                                  "tempo": round(tempo, 4), "segments": timeline}, indent=2))
    print(f"narration {track} ({duration(track):.2f}s), timeline {total:.2f}s, {len(timeline)} lines -> audio/timing.json")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/build_sfx.py
size: 12218
sha: c0b1b474b1cfcebd0c898493ff801a8c3a7e9f86
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/build_sfx.py

```text
#!/usr/bin/env python3
"""Synthesise the sound-effects track from the film's cue list. No samples: every sound is built from
noise and partials with numpy, so there is nothing to license.

  python3 render.py --project my-film --cues      # writes sfx_cues.json (items cue themselves)
  python3 build_sfx.py --project my-film          # writes audio/sfx.wav (full level; mix_soundtrack.py sets levels)

Cue kinds (film.cue(kind, t, gain, dur=...); items add most of these on their own):
  pop       print or card landing             slide     newspaper or string sliding in
  whoosh    camera move, route drawing on     marker    highlighter stroke
  pencil    pen circle or underline ("dur")   tick      pencil tick (tally marks)
  snip      tiny cut, a hole punched          click     shutter or film-frame clamp
  stamp     rubber stamp slam                 impact    title or number landing, low thump
  boom      big reveal, sub drop              ticks     a counter rolling up
  shimmer   cluster of small blips (dots)     drop      falling swoop
  riser     noise and tone crescendo into a section change ("dur"; peaks at t + dur)
  heartbeat low lub-dub thump (repeat once a second for a tension bed)
  clock     dry clock ticks, one a second ("dur")
film.room_tone = [[start, end], ...] lays a quiet room tone under those spans (silence elsewhere is
a deliberate beat).
"""
from __future__ import annotations

import argparse
import inspect
import json
import pathlib
import subprocess
import sys

import numpy as np

SR = 48000
BLOCK = 4096
HOP = BLOCK // 2

# ---------------------------------------------------------------- primitives
def n_of(sec):
    return int(sec * SR)

def envelope(points, n):
    """Piecewise-linear envelope over n samples; points are (fraction 0..1, gain)."""
    return np.interp(np.linspace(0.0, 1.0, n), [p[0] for p in points], [p[1] for p in points])

def sweep(a, b, n, curve=1.0):
    return a + (b - a) * np.linspace(0.0, 1.0, n) ** curve

def _band_mask(freqs, lo, hi, tilt):
    mask = np.zeros_like(freqs)
    mask[(freqs >= lo) & (freqs <= hi)] = 1.0
    lower = (freqs < lo) & (freqs > lo / 2)
    if lower.any():
        mask[lower] = 0.5 - 0.5 * np.cos(np.pi * (freqs[lower] - lo / 2) / (lo / 2))
    upper = (freqs > hi) & (freqs < hi * 2)
    if upper.any():
        mask[upper] = 0.5 + 0.5 * np.cos(np.pi * (freqs[upper] - hi) / hi)
    if tilt:
        with np.errstate(divide="ignore"):
            mask *= np.where(freqs > 0, (np.maximum(freqs, 1.0) / 1000.0) ** tilt, 0.0)
    return mask

def band_noise(n, lo, hi, amp, seed, tilt=0.0):
    """Noise confined to a band whose corners may move over time (overlap-add spectral masking)."""
    rng = np.random.default_rng(seed)
    source = rng.standard_normal(n + BLOCK)
    out = np.zeros(n + BLOCK)
    window = np.hanning(BLOCK)
    freqs = np.fft.rfftfreq(BLOCK, 1.0 / SR)
    lo_arr = np.full(n, lo, np.float64) if np.isscalar(lo) else np.asarray(lo, np.float64)
    hi_arr = np.full(n, hi, np.float64) if np.isscalar(hi) else np.asarray(hi, np.float64)
    for start in range(0, n, HOP):
        c = min(start + HOP, n - 1)
        spec = np.fft.rfft(source[start:start + BLOCK] * window)
        spec *= _band_mask(freqs, max(lo_arr[c], 1.0), max(hi_arr[c], 2.0), tilt)
        out[start:start + BLOCK] += np.fft.irfft(spec, BLOCK)
    out = out[:n]
    peak = np.max(np.abs(out))
    return (out / peak if peak > 0 else out) * amp

def tone(n, freq, decay, partials=(1.0, 2.01, 3.03)):
    t = np.arange(n) / SR
    return sum((0.6 ** i) * np.sin(2 * np.pi * freq * r * t) for i, r in enumerate(partials)) * np.exp(-t / decay)

def hit(n, lo, hi, decay, seed):
    return band_noise(n, lo, hi, np.exp(-(np.arange(n) / SR) / decay), seed=seed)

def fade(x, a, b):
    """De-click: short linear fades at both ends (a truncated tail would otherwise be a step, and a step is a click)."""
    out = x.copy()
    na, nb = min(int(a * SR), len(out)), min(int(b * SR), len(out))
    if na > 0:
        out[:na] *= np.linspace(0, 1, na)
    if nb > 0:
        out[-nb:] *= np.linspace(1, 0, nb)
    return out

class Bed:
    def __init__(self, duration):
        self.n = int(duration * SR)
        self.buf = np.zeros((2, self.n))

    def add(self, sig, at, gain=1.0, pan=0.0):
        s = int(at * SR)
        if s >= self.n or len(sig) == 0:
            return
        sig = fade(sig[: self.n - s], 0.02, 0.02)
        e = s + len(sig)
        self.buf[0, s:e] += sig * gain * np.sqrt((1.0 - pan) / 2.0) * np.sqrt(2.0)
        self.buf[1, s:e] += sig * gain * np.sqrt((1.0 + pan) / 2.0) * np.sqrt(2.0)

    def render(self, path, headroom_db=-1.0):
        a = self.buf
        b, a_ = _hp_coeffs(28.0)
        for ch in range(2):
            a[ch] = _iir(a[ch], b, a_)
        peak = np.max(np.abs(a))
        if peak > 0:
            a = a / peak * (10 ** (headroom_db / 20))
        pcm = (a.T.reshape(-1) * 32767).astype(np.int16)
        path.parent.mkdir(parents=True, exist_ok=True)
        subprocess.run(["ffmpeg", "-y", "-v", "error", "-f", "s16le", "-ar", str(SR), "-ac", "2", "-i", "pipe:0",
                        "-c:a", "pcm_s24le", str(path)], input=pcm.tobytes(), check=True)

def _hp_coeffs(fc):
    alpha = 1.0 / (1.0 + 2 * np.pi * fc / SR)
    return (alpha, -alpha), alpha

def _iir(x, b, a):
    """y[n] = a*y[n-1] + b0*x[n] + b1*x[n-1]  (one-pole high-pass), via scipy if present, else a loop."""
    try:
        from scipy.signal import lfilter
        return lfilter([b[0], b[1]], [1.0, -a], x)
    except ImportError:
        y = np.empty_like(x); yp = xp = 0.0
        for i, s in enumerate(x):
            yp = a * yp + b[0] * s + b[1] * xp; xp = s; y[i] = yp
        return y

_LEAD = n_of(.025)

def _lead(x):
    return np.concatenate([np.zeros(_LEAD), x])

# ---------------------------------------------------------------- sounds
def whoosh(seed):
    n = n_of(.55)
    return band_noise(n, sweep(300, 1400, n), sweep(1800, 6000, n), envelope([(0, 0), (.45, 1), (1, 0)], n) ** 1.5, seed=seed, tilt=-.4)

def pop(seed):
    n = n_of(.18); t = np.arange(n) / SR
    return np.sin(2 * np.pi * sweep(260, 150, n) * t) * np.exp(-t / .035) * .8 + hit(n, 1200, 5000, .01, seed) * .25

def slide(seed):
    n = n_of(1.4)
    return band_noise(n, 250, 1800, envelope([(0, 0), (.15, .8), (.85, .8), (1, 0)], n), seed=seed, tilt=-.6) * .8

def marker(seed):
    n = n_of(.45)
    amp = envelope([(0, 0), (.1, .9), (.8, .8), (1, 0)], n) * (1 + .25 * np.sin(2 * np.pi * 23 * np.arange(n) / SR))
    return band_noise(n, 1800, 5200, amp, seed=seed, tilt=.3) * .7

def pencil(seed, dur=1.6):
    n = n_of(dur); t = np.arange(n) / SR
    rng = np.random.default_rng(seed)
    stroke = np.abs(np.sin(np.pi * (7 + rng.uniform(-1.5, 1.5)) * t + rng.uniform(0, 3))) ** .6
    amp = stroke * (1 + .3 * np.sin(2 * np.pi * rng.uniform(13, 19) * t)) * envelope([(0, 0), (.06, 1), (.9, .85), (1, 0)], n)
    return band_noise(n, 2400, 8500, amp, seed=seed, tilt=.2) * .55 + band_noise(n, 600, 1800, amp * .3, seed=seed + 1) * .3

def tick(seed):
    n = n_of(.16)
    return _lead(band_noise(n, 2500, 9000, envelope([(0, 0), (.1, 1), (.35, .3), (.45, .9), (1, 0)], n), seed=seed, tilt=.2) * .7)

def snip(seed):
    rng = np.random.default_rng(seed); n = n_of(.07)
    return _lead(tone(n, rng.uniform(2600, 3600), .006, (1.0, 1.52)) * .5 + hit(n, 3000, 10000, .004, seed) * .8)

def click(seed):
    n = n_of(.11); out = np.zeros(n)
    a = hit(n_of(.012), 2500, 9000, .0018, seed) + tone(n_of(.012), 3400, .0015, (1.0,)) * .4
    out[:len(a)] += a
    b = hit(n_of(.01), 2000, 7000, .0015, seed + 1) * .6
    out[n_of(.075):n_of(.075) + len(b)] += b
    return _lead(out)

def stamp(seed):
    n = n_of(.4); t = np.arange(n) / SR
    return np.sin(2 * np.pi * sweep(120, 55, n) * t) * np.exp(-t / .07) + hit(n, 400, 3500, .025, seed) * .8

def impact(seed):
    n = n_of(1.2); t = np.arange(n) / SR
    return np.sin(2 * np.pi * sweep(90, 42, n, .6) * t) * np.exp(-t / .35) + band_noise(n, 200, 2500, np.exp(-t / .12), seed=seed) * .35

def boom(seed):
    n = n_of(2.4); t = np.arange(n) / SR
    sub = np.sin(2 * np.pi * sweep(70, 30, n, .5) * t) * np.exp(-t / .8)
    return sub * 1.1 + hit(n, 500, 7000, .05, seed) * .5 + band_noise(n, 60, 400, np.exp(-t / .9), seed=seed + 3) * .4

def ticks(seed):
    n = n_of(1.4); out = np.zeros(n); rng = np.random.default_rng(seed)
    for at in np.cumsum(np.linspace(.04, .11, 18)):      # decelerating, like a counter settling
        s = n_of(at)
        if s >= n:
            break
        c = tone(n_of(.03), 2400 + rng.uniform(-150, 150), .004, (1.0, 2.3))
        out[s:s + len(c)] += c[: n - s]
    return out * .8

def shimmer(seed):
    n = n_of(1.0); out = np.zeros(n); rng = np.random.default_rng(seed)
    for i in range(14):
        s = n_of(i * .05 + rng.uniform(0, .02)); c = tone(n_of(.12), rng.uniform(1600, 3400), .03, (1.0, 2.0))
        out[s:s + len(c)] += c[: n - s] * .5
    return out

def drop(seed):
    n = n_of(.6)
    whistle = np.sin(2 * np.pi * np.cumsum(sweep(900, 120, n, .7)) / SR) * envelope([(0, .2), (.3, 1), (1, 0)], n)
    w = whoosh(seed); out = np.zeros(max(n, len(w)))
    out[:n] += whistle * .5; out[:len(w)] += w * .5
    return out

def riser(seed, dur=2.0):
    """Noise band sweeping up plus a climbing low tone; starts at the cue, peaks at t + dur."""
    n = n_of(dur); t = np.arange(n) / SR
    env = (t / dur) ** 2.4
    out = band_noise(n, sweep(250, 1800, n), sweep(1200, 9000, n), env, seed=seed) * .7 + np.sin(2 * np.pi * np.cumsum(sweep(70, 260, n, 1.4)) / SR) * env * .5
    out[-n_of(.02):] *= np.linspace(1, 0, n_of(.02))
    return out

def heartbeat(seed):
    n = n_of(.75); t = np.arange(n) / SR

    def thump(at, f0, amp):
        tt = np.clip(t - at, 0, None)
        return np.sin(2 * np.pi * sweep(f0, f0 * .55, n, .6) * tt) * np.exp(-tt / .09) * (t >= at) * amp
    return thump(.02, 62, 1.0) + thump(.24, 55, .7)

def clock(seed, dur=4.0):
    n = n_of(dur); out = np.zeros(n)
    for k, at in enumerate(np.arange(.02, dur - .05, 1.0)):
        s = n_of(at); seg = hit(n_of(.05), 1800 if k % 2 == 0 else 1300, 5200, .012, seed + k)
        out[s:s + len(seg)] += seg[: n - s] * .8
    return out

SOUNDS = dict(whoosh=whoosh, pop=pop, slide=slide, marker=marker, pencil=pencil, tick=tick, snip=snip, click=click,
              stamp=stamp, impact=impact, boom=boom, ticks=ticks, shimmer=shimmer, drop=drop, riser=riser,
              heartbeat=heartbeat, clock=clock)

def room_tone(total, spans):
    """Quiet room: low filtered noise, faded in and out over each span."""
    n = n_of(total); gate = np.zeros(n)
    for a, b in spans:
        ia, ib = n_of(a), min(n_of(b), n)
        if ib <= ia:
            continue
        g = np.ones(ib - ia); fi, fo = min(n_of(1.2), len(g) // 3), min(n_of(.4), len(g) // 3)
        g[:fi] = np.linspace(0, 1, fi); g[len(g) - fo:] = np.linspace(1, 0, fo)
        gate[ia:ib] = g
    return band_noise(n, 70, 420, np.ones(n), seed=77) * .3 * gate

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    cp = proj / "sfx_cues.json"
    if not cp.exists():
        sys.exit(f"{cp} not found: run render.py --project {proj} --cues first")
    cues = json.loads(cp.read_text())
    total = cues["duration"]
    unknown = sorted({c["type"] for c in cues["cues"]} - SOUNDS.keys())
    if unknown:
        sys.exit(f"unknown cue kinds: {unknown} (have {sorted(SOUNDS)})")
    bed = Bed(total)
    for i, c in enumerate(cues["cues"]):
        fn = SOUNDS[c["type"]]
        kw = {"dur": c["dur"]} if "dur" in c and "dur" in inspect.signature(fn).parameters else {}
        bed.add(fn(seed=100 + i, **kw), max(c["t"], 0), gain=c.get("gain", 1.0), pan=((i * 37) % 11 - 5) / 20)
    if cues.get("room_tone"):
        bed.add(room_tone(total, cues["room_tone"]), 0, gain=.22)
    out = proj / "audio" / "sfx.wav"
    bed.render(out)
    print(f"sfx: {out}  ({len(cues['cues'])} cues, {total:.1f}s)")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/burn_captions.py
size: 5755
sha: 897ab120e679699cc8e8e2722bc9980a9064cae4
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/burn_captions.py

```text
#!/usr/bin/env python3
"""Burn a caption style into a finished render (a second pass, no re-render) and write an SRT.

  python3 burn_captions.py --project my-film --video out/final.mp4 --audio audio/mix.m4a --style highlighter --out out/final_captions.mp4
  python3 burn_captions.py --project my-film --srt-only --out out/captions.srt

N workers each decode a time slice of the video, composite the caption layer onto the bottom
quarter of each frame and encode; the slices are joined losslessly and the audio is muxed.
Captions sit in the bottom 26% of the frame: keep big on-screen numbers out of that band.
Styles: highlighter, clean, paper, redbar (see captions.py). The SRT uses sentence-sized chunks
for players (upload it to YouTube with the clean, caption-free render).
"""
import argparse
import json
import multiprocessing as mp
import os
import pathlib
import subprocess
import sys
import time

HERE = pathlib.Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

def probe(video):
    out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,r_frame_rate,nb_frames",
                          "-of", "json", str(video)], capture_output=True, text=True).stdout
    s = json.loads(out)["streams"][0]
    num, den = map(int, s["r_frame_rate"].split("/"))
    nb = int(s.get("nb_frames") or 0)
    if not nb:
        dur = float(subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(video)],
                                   capture_output=True, text=True).stdout)
        nb = int(round(dur * num / den))
    return s["width"], s["height"], num / den, nb

def worker(args):
    video, style, f0, f1, fps, w, h, out, crf, timing, fonts = args
    import numpy as np
    from captions import Captions
    cap = Captions(style, w, h, timing, fonts)
    y0 = int(h * 0.74)
    dec = subprocess.Popen(["ffmpeg", "-v", "error", "-ss", f"{f0 / fps:.4f}", "-i", str(video), "-frames:v", str(f1 - f0),
                            "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], stdout=subprocess.PIPE)
    enc = subprocess.Popen(["ffmpeg", "-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24", "-s", f"{w}x{h}", "-r", str(fps), "-i", "-",
                            "-c:v", "libx264", "-preset", "medium", "-crf", str(crf), *(["-rc-lookahead", "10", "-threads", "2"] if w >= 2000 else []),
                            "-pix_fmt", "yuv420p", str(out)], stdin=subprocess.PIPE)
    size = w * h * 3
    t0 = time.time()
    for n in range(f0, f1):
        buf = dec.stdout.read(size)
        if len(buf) < size:
            break
        frame = np.frombuffer(buf, np.uint8).reshape(h, w, 3)
        layer = cap.layer(n / fps)
        if layer is not None:
            frame = frame.copy()
            a = layer[y0:, :, 3:4].astype(np.float32) * (1 / 255.0)
            frame[y0:] = np.clip(frame[y0:].astype(np.float32) * (1 - a) + layer[y0:, :, :3], 0, 255).astype(np.uint8)
        enc.stdin.write(frame.tobytes())
    enc.stdin.close(); enc.wait(); dec.wait()
    return f0, f1, time.time() - t0

def srt(timing, out):
    from captions import chunks_for
    total = timing["total_duration"]

    def ts(x):
        ms = int(round(x * 1000)); return f"{ms // 3600000:02d}:{ms // 60000 % 60:02d}:{ms // 1000 % 60:02d},{ms % 1000:03d}"
    rows = chunks_for(timing, "clean")
    lines = []
    for i, c in enumerate(rows, 1):
        lines += [str(i), f"{ts(c['t0'])} --> {ts(min(c['t1'], total))}", " ".join(w for w, _ in c["words"]), ""]
    pathlib.Path(out).write_text("\n".join(lines))
    print(f"srt: {out} ({len(rows)} cues)")

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--video")
    ap.add_argument("--audio")
    ap.add_argument("--style", default="highlighter", choices=["highlighter", "clean", "paper", "redbar"])
    ap.add_argument("--out", required=True)
    ap.add_argument("--workers", type=int, default=max(1, min(6, (os.cpu_count() or 4) - 1)))
    ap.add_argument("--crf", type=int, default=18)
    ap.add_argument("--srt-only", action="store_true")
    a = ap.parse_args()
    proj = pathlib.Path(a.project).resolve()
    rel = lambda p: p if pathlib.Path(p).is_absolute() else proj / p
    timing = json.loads((proj / "audio" / "timing.json").read_text())
    out = rel(a.out); out.parent.mkdir(parents=True, exist_ok=True)
    if a.srt_only:
        srt(timing, out); return
    if not a.video:
        sys.exit("--video is required (or --srt-only)")
    video = rel(a.video)
    w, h, fps, nb = probe(video)
    work = proj / "out" / "burn"; work.mkdir(parents=True, exist_ok=True)
    for old in work.glob("*.mp4"):
        old.unlink()
    k = a.workers
    b = [nb * i // k for i in range(k + 1)]
    fonts = str(proj / "fonts")
    jobs = [(str(video), a.style, b[i], b[i + 1], fps, w, h, work / f"b{i:02d}.mp4", a.crf, timing, fonts) for i in range(k)]
    t0 = time.time()
    with mp.get_context("spawn").Pool(k) as pool:
        for f0, f1, dt in pool.imap_unordered(worker, jobs):
            print(f"  frames {f0}-{f1}: {dt:.0f}s", flush=True)
    lst = work / "list.txt"; lst.write_text("".join(f"file '{j[7].resolve()}'\n" for j in jobs))
    cmd = ["ffmpeg", "-v", "error", "-y", "-f", "concat", "-safe", "0", "-i", str(lst)]
    if a.audio:
        cmd += ["-i", str(rel(a.audio)), "-map", "0:v", "-map", "1:a", "-c:a", "aac", "-b:a", "192k", "-shortest"]
    cmd += ["-c:v", "copy", "-movflags", "+faststart", str(out)]
    subprocess.run(cmd, check=True)
    print(f"wrote {out} in {time.time() - t0:.0f}s")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/captions.py
size: 7843
sha: be7cdc7da088cfbb706ccf406f4842a5e69e73ee
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/captions.py

```text
"""Burned-in caption styles, chunked from the voiceover timing. Used by burn_captions.py.

Captions are drawn in screen space on their own layer after the film finish, so they stay crisp.
Word times come from each line's letter share (the same estimate the scene uses for hits).

Styles:
  highlighter  condensed caps on a dark band, the current word swiped in yellow (grunge newsprint)
  clean        sentence case with a soft shadow over a bottom gradient (classic documentary subtitle)
  paper        typewriter text typing onto a torn paper strip
  redbar       white condensed caps on a red bar (matches name labels)
"""
import re

import numpy as np
import skia

from engine import HILITE, Res, ease_out_cubic, paint, ramp, text_width, draw_text

MAX_WORDS = {"highlighter": 6, "clean": 9, "paper": 8, "redbar": 5}

def words_with_times(seg):
    """[(word as displayed, start time)] for one line: display text, spoken-text timing."""
    disp = seg["caption"].replace('"', "").split()
    lens = []
    for w in disp:
        letters = len(re.sub(r"[^A-Za-z]", "", w))
        if re.search(r"\d", w):                      # 1929 is long when spoken ("nineteen twenty-nine")
            letters = max(letters, 6 * len(re.sub(r"[^0-9]", "", w)) // 2 + 4)
        lens.append(max(1, letters))
    s = sum(lens); acc = 0; out = []
    dur = seg["end"] - seg["start"]
    for w, l in zip(disp, lens):
        out.append((w, seg["start"] + dur * acc / s)); acc += l
    return out

def chunks_for(timing, style):
    """[{'words': [(w, t)], 't0', 't1'}], breaking at punctuation where possible."""
    mx = MAX_WORDS[style]
    out = []
    for seg in timing["segments"]:
        ws = words_with_times(seg)
        cur, line = [], []
        for i, (w, t) in enumerate(ws):
            cur.append((w, t))
            if len(cur) >= mx or (w[-1] in ".,?!;:" and len(cur) >= max(2, mx // 2)) or i == len(ws) - 1:
                line.append({"words": cur, "t0": cur[0][1]}); cur = []
        for a, b in zip(line, line[1:]):
            a["t1"] = b["t0"]
        line[-1]["t1"] = seg["end"] + 0.25
        out += line
    return out

class Captions:
    def __init__(self, style, width, height, timing, fonts_dir=None):
        self.style, self.W, self.H = style, width, height
        self.k = width / 1920.0
        self.res = Res(width / 3840.0, None, fonts_dir)
        self.chunks = chunks_for(timing, style)
        self.surface = skia.Surface.MakeRaster(skia.ImageInfo.Make(width, height, skia.ColorType.kRGBA_8888_ColorType, skia.AlphaType.kPremul_AlphaType))

    def active(self, t):
        for c in self.chunks:
            if c["t0"] - 0.05 <= t < c["t1"]:
                return c
        return None

    def layer(self, t):
        """Premultiplied RGBA caption layer for time t, or None."""
        c = self.active(t)
        if c is None:
            return None
        with self.surface as cv:
            cv.clear(skia.Color(0, 0, 0, 0))
            getattr(self, "_" + self.style)(cv, c, t)
        return self.surface.makeImageSnapshot().toarray(colorType=skia.ColorType.kRGBA_8888_ColorType)

    def _text(self, c, upper=False):
        txt = " ".join(w for w, _ in c["words"])
        return txt.upper() if upper else txt

    def _highlighter(self, cv, c, t):
        k = self.k; size = 66 * k; y = self.H * 0.897; f = "cond"
        words = [w.upper() for w, _ in c["words"]]
        gap = size * 0.28
        widths = [text_width(self.res, w, size, f, 0.03) for w in words]
        total = sum(widths) + gap * (len(words) - 1)
        x = self.W / 2 - total / 2
        a = ramp(t, c["t0"] - 0.05, 0.12)
        cur = max(i for i, (_, wt) in enumerate(c["words"]) if wt <= t + 0.02) if t >= c["words"][0][1] else 0
        pad = 26 * k
        cv.drawRoundRect(skia.Rect.MakeXYWH(x - pad, y - size * 0.95, total + 2 * pad, size * 1.25), 6 * k, 6 * k, paint((10, 9, 8), 0.62 * a))
        for i, (w, wd) in enumerate(zip(words, widths)):
            if i == cur:
                # white word underneath; the yellow swipe reveals it in black only where the swipe has reached
                u = ease_out_cubic(ramp(t, c["words"][i][1], 0.12))
                box = skia.Rect.MakeXYWH(x - 10 * k, y - size * 0.78, (wd + 20 * k) * u, size * 0.92)
                draw_text(cv, self.res, w, x, y, size, f, (250, 247, 240), a, 0.03)
                cv.drawRect(box, paint(HILITE, 0.95 * a))
                cv.save(); cv.clipRect(box)
                draw_text(cv, self.res, w, x, y, size, f, (18, 16, 14), a, 0.03)
                cv.restore()
            else:
                cv.save(); cv.translate(3 * k, 4 * k)
                draw_text(cv, self.res, w, x, y, size, f, (0, 0, 0), 0.6 * a, 0.03)
                cv.restore()
                draw_text(cv, self.res, w, x, y, size, f, (250, 247, 240), a, 0.03)
            x += wd + gap

    def _clean(self, cv, c, t):
        k = self.k; size = 52 * k; f = "labelm"
        txt = self._text(c)
        a = ramp(t, c["t0"] - 0.05, 0.15) * (1 - ramp(t, c["t1"] - 0.12, 0.12))
        g = skia.GradientShader.MakeLinear([skia.Point(0, self.H * 0.68), skia.Point(0, self.H)], [skia.Color(0, 0, 0, 0), skia.Color(0, 0, 0, int(190 * a))])
        gp = skia.Paint(); gp.setShader(g); cv.drawRect(skia.Rect.MakeXYWH(0, self.H * 0.68, self.W, self.H * 0.32), gp)
        lines = [txt]
        if text_width(self.res, txt, size, f) > self.W * 0.7:
            ws = txt.split(); half = len(ws) // 2 + (len(ws) % 2)
            lines = [" ".join(ws[:half]), " ".join(ws[half:])]
        y0 = self.H * 0.885 - (len(lines) - 1) * size * 1.25
        for i, ln in enumerate(lines):
            y = y0 + i * size * 1.25
            cv.save(); cv.translate(0, 3 * k)
            tw = text_width(self.res, ln, size, f)
            cv.drawString(ln, self.W / 2 - tw / 2, y, self.res.font(f, size), paint((0, 0, 0), 0.85 * a, blur=6 * k))
            cv.restore()
            draw_text(cv, self.res, ln, self.W / 2, y, size, f, (252, 250, 245), a, 0.0, "center")

    def _paper(self, cv, c, t):
        k = self.k; size = 42 * k; f = "mono"
        txt = self._text(c)
        tw = text_width(self.res, txt, size, f, 0.02)
        a = ramp(t, c["t0"] - 0.05, 0.12)
        W, H = tw + 64 * k, size * 1.75
        cv.save(); cv.translate(self.W / 2, self.H * 0.865); cv.rotate(-0.8)
        rng = np.random.default_rng(int(c["t0"] * 10))
        p = skia.Path(); n = 28
        p.moveTo(-W / 2, -H / 2)
        for i in range(1, n + 1):
            p.lineTo(-W / 2 + W * i / n, -H / 2 + rng.uniform(-3, 3) * k)
        for i in range(n + 1):
            p.lineTo(W / 2 - W * i / n, H / 2 + rng.uniform(-3, 3) * k)
        p.close()
        cv.save(); cv.translate(6 * k, 8 * k); cv.drawPath(p, paint((0, 0, 0), 0.5 * a, blur=8 * k)); cv.restore()
        cv.drawPath(p, paint((240, 236, 226), 0.97 * a))
        n_chars = len(txt) * ramp(t, c["t0"], 0.035 * len(txt) + 0.05)
        draw_text(cv, self.res, txt, -tw / 2, size * 0.32, size, f, (24, 22, 20), a, 0.02, reveal=n_chars + 0.999)
        cv.restore()

    def _redbar(self, cv, c, t):
        k = self.k; size = 60 * k; f = "cond"
        txt = self._text(c, upper=True)
        tw = text_width(self.res, txt, size, f, 0.04)
        u = ease_out_cubic(ramp(t, c["t0"] - 0.05, 0.22)); a = ramp(t, c["t0"] - 0.05, 0.08)
        W, H = tw + 50 * k, size * 1.22
        x0, y0 = self.W / 2 - W / 2, self.H * 0.865 - H * 0.72
        cv.drawRect(skia.Rect.MakeXYWH(x0 + 6 * k, y0 + 8 * k, W * u, H), paint((0, 0, 0), 0.45 * a, blur=8 * k))
        cv.drawRect(skia.Rect.MakeXYWH(x0, y0, W * u, H), paint((176, 24, 20), 0.97 * a))
        cv.save(); cv.clipRect(skia.Rect.MakeXYWH(x0, y0, W * u, H))
        draw_text(cv, self.res, txt, self.W / 2, y0 + H * 0.8, size, f, (252, 249, 242), a, 0.04, "center")
        cv.restore()
```

## File: skills/cinematic-film/scripts/check_setup.py
size: 3228
sha: baa1581dc37ade1b15de37c269a75abc724debb0
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/check_setup.py

```text
#!/usr/bin/env python3
"""Check that this machine can build a cinematic-film project, and say exactly what to install if not.

  python3 check_setup.py

Checks Python, numpy, Pillow, skia-python, ffmpeg and ffprobe (with libx264), the fonts each text
role will use, a local voice for scratch tracks, and how many render workers fit in memory.
Exit code 1 when something required is missing.
"""
import importlib
import pathlib
import shutil
import subprocess
import sys

HERE = pathlib.Path(__file__).resolve().parent
ok = True

def line(status, what, detail=""):
    print(f"  [{status}] {what}" + (f"  {detail}" if detail else ""))

def need(cond, what, fix):
    global ok
    line("ok" if cond else "MISSING", what, "" if cond else fix)
    ok &= bool(cond)

print("cinematic-film setup check")
need(sys.version_info >= (3, 9), f"Python {sys.version.split()[0]}", "needs Python 3.9 or newer")
mods = {}
for mod, pip in (("numpy", "numpy"), ("PIL", "pillow"), ("skia", "skia-python")):
    try:
        mods[mod] = importlib.import_module(mod)
        line("ok", f"{pip} {getattr(mods[mod], '__version__', '')}")
    except Exception as e:
        need(False, pip, f"pip install {pip}   ({type(e).__name__})")
try:
    import scipy  # noqa: F401
    line("ok", "scipy (optional: faster sound-effects render)")
except Exception:
    line("--", "scipy not installed (optional; build_sfx.py falls back to a slower filter)")

for tool in ("ffmpeg", "ffprobe"):
    need(shutil.which(tool), tool, "install ffmpeg: brew install ffmpeg / apt install ffmpeg / winget install ffmpeg")
if shutil.which("ffmpeg"):
    enc = subprocess.run(["ffmpeg", "-hide_banner", "-encoders"], capture_output=True, text=True).stdout
    need("libx264" in enc, "ffmpeg has libx264", "your ffmpeg build lacks libx264; install a full build")
    filt = subprocess.run(["ffmpeg", "-hide_banner", "-filters"], capture_output=True, text=True).stdout
    need("loudnorm" in filt and "sidechaincompress" in filt, "ffmpeg has loudnorm and sidechaincompress", "install a full ffmpeg build")

if "skia" in mods:
    sys.path.insert(0, str(HERE))
    from engine import FONT_ROLES, resolve_typeface
    print("  fonts (drop <project>/fonts/<role>.ttf to override any of them):")
    for role in FONT_ROLES:
        tf, desc = resolve_typeface(role)
        print(f"     {role:<7} {desc}")
    if any(resolve_typeface(r)[1].startswith("system default") for r in FONT_ROLES):
        print("     -> run get_fonts.py --project <folder> to fetch open-licensed replacements")

voice = "say" if shutil.which("say") else "espeak-ng" if shutil.which("espeak-ng") else None
line("ok" if voice else "--", f"scratch voice: {voice}" if voice else "no local voice for scratch tracks",
     "" if voice else "optional: apt install espeak-ng, or use any TTS and save takes as WAV")

sys.path.insert(0, str(HERE))
try:
    from render import auto_workers, total_ram_gb
    print(f"  memory {total_ram_gb():.0f} GB: {auto_workers(1920, 1080)} workers at 1080p, "
          f"{auto_workers(2560, 1440)} at 1440p, {auto_workers(3840, 2160)} at 4K")
except Exception:
    pass
print("ready" if ok else "fix the MISSING items above, then run this again")
sys.exit(0 if ok else 1)
```

## File: skills/cinematic-film/scripts/engine.py
size: 74656
sha: a8ac47ef4ea26f12f3d0a395a94bc9ba0d445701
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/engine.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/engine.py

## File: skills/cinematic-film/scripts/fetch_commons.py
size: 8834
sha: 8082cc6ce2d084bff0ecc4d9cb9d19e7eca1359e
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/fetch_commons.py

```text
#!/usr/bin/env python3
"""Find and download archival images from Wikimedia Commons with their licence, and keep the credits.

  python3 fetch_commons.py search "wright brothers first flight 1903" --limit 12
  python3 fetch_commons.py category "Category:Wright Flyer" --limit 40
  python3 fetch_commons.py get --project my-film          # download every photos.json entry that has no file yet
  python3 fetch_commons.py credits --project my-film      # write credits.md from photos.json

photos.json entries name their source one of two ways:
  {"id": "P01", "kind": "photo", "commons": "File:Wright First Flight 1903Dec17.jpg"}
  {"id": "P07", "kind": "doc", "url": "https://.../full.jpg", "credit": "...", "license": "Public domain", "source": "..."}

For "commons" entries, `get` fills file, source, credit, license and license_ok from the file page's
metadata. It refuses a licence that is not public domain, CC0, CC BY or CC BY-SA unless you pass
--allow-nonfree (and then you own the rights question). "url" entries download as given: fill in
credit and licence yourself from the archive's record page (Library of Congress, National Archives).

Search tips: Commons search matches file names and descriptions, so search the archive's words
("first flight", "Kitty Hawk 1903"), then open the category of a good hit to see its siblings.
Large originals are fetched as 3200 px renders, which is more than a print on screen ever needs.
"""
import argparse
import html
import json
import pathlib
import re
import sys
import time
import urllib.parse
import urllib.request

API = "https://commons.wikimedia.org/w/api.php"
UA = "cinematic-film/1.0 (+https://github.com/Moh4696/open-3d-skills)"
FREE = re.compile(r"public domain|^pd\b|^pd-|cc0|cc[- ]by(?!.*\bnc\b)(?!.*\bnd\b)", re.I)

def api(**params):
    params.update(format="json", formatversion="2")
    req = urllib.request.Request(API + "?" + urllib.parse.urlencode(params), headers={"User-Agent": UA})
    for attempt in range(4):
        try:
            with urllib.request.urlopen(req, timeout=40) as r:
                return json.loads(r.read())
        except urllib.error.HTTPError as e:
            if e.code in (429, 503) and attempt < 3:
                time.sleep(3 * (attempt + 1)); continue
            raise

def text(v):
    return html.unescape(re.sub(r"<[^>]+>", "", v or "")).strip()

def info(page):
    ii = (page.get("imageinfo") or [{}])[0]
    md = ii.get("extmetadata", {})
    g = lambda k: text(md.get(k, {}).get("value", ""))
    return {"title": page.get("title"), "w": ii.get("width"), "h": ii.get("height"), "mime": ii.get("mime"),
            "url": ii.get("url"), "thumb": ii.get("thumburl"), "source": ii.get("descriptionurl"),
            "license": g("LicenseShortName") or g("UsageTerms"), "license_url": g("LicenseUrl"),
            "credit": g("Artist") or g("Credit"), "date": g("DateTimeOriginal") or g("DateTime"),
            "desc": g("ImageDescription")[:160]}

IIPROP = dict(prop="imageinfo", iiprop="url|size|mime|extmetadata", iiurlwidth=3200)

def show(pages):
    for p in pages:
        d = info(p)
        ok = "free " if FREE.search(d["license"] or "") else "CHECK"
        print(f"[{ok}] {d['title']}\n        {d['w']}x{d['h']}  {d['license'] or 'no licence field'}  {d['credit'][:60]}  {d['date'][:20]}\n        {d['desc'][:120]}")

def cmd_search(a):
    r = api(action="query", generator="search", gsrsearch=a.query, gsrnamespace=6, gsrlimit=a.limit, **IIPROP)
    show(sorted((r.get("query") or {}).get("pages", []), key=lambda p: p.get("index", 0)))

def cmd_category(a):
    cat = a.category if a.category.startswith("Category:") else "Category:" + a.category
    r = api(action="query", generator="categorymembers", gcmtitle=cat, gcmtype="file", gcmlimit=a.limit, **IIPROP)
    show((r.get("query") or {}).get("pages", []))

def download(url, dst):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    for attempt in range(4):
        try:
            with urllib.request.urlopen(req, timeout=120) as r:
                dst.write_bytes(r.read()); return
        except urllib.error.HTTPError as e:
            if e.code in (429, 503) and attempt < 3:
                time.sleep(5 * (attempt + 1)); continue
            raise

def cmd_get(a):
    proj = pathlib.Path(a.project)
    spec = json.loads((proj / "photos.json").read_text())
    dst_dir = proj / "assets" / "photos"; dst_dir.mkdir(parents=True, exist_ok=True)
    refused = 0
    for p in spec["photos"]:
        have = bool(p.get("file")) and (dst_dir / p["file"]).exists()
        if have and not a.force and (p.get("license") or not p.get("commons")):
            continue                     # downloaded and credited (or a local/url file the user credits by hand)
        if p.get("commons"):
            title = p["commons"] if p["commons"].startswith("File:") else "File:" + p["commons"]
            pages = (api(action="query", titles=title, **IIPROP).get("query") or {}).get("pages", [])
            if not pages or pages[0].get("missing"):
                print(f"{p['id']}: {title} not found on Commons"); refused += 1; continue
            d = info(pages[0])
            ok = bool(FREE.search(d["license"] or ""))
            if not ok and not a.allow_nonfree:
                print(f"{p['id']}: REFUSED, licence {d['license']!r} is not free ({d['source']})"); refused += 1; continue
            url = d["thumb"] if d["thumb"] and (d["w"] or 0) > 3200 and "svg" not in (d["mime"] or "") else d["url"]
            if "svg" in (d["mime"] or ""):
                url = d["thumb"]
            ext = pathlib.Path(urllib.parse.urlparse(url).path).suffix.lower() or ".jpg"
            fname = p["file"] if have and not a.force else f"{p['id']}_{re.sub(r'[^A-Za-z0-9]+', '_', title[5:].rsplit('.', 1)[0])[:48]}{ext}"
            if not have or a.force:
                download(url, dst_dir / fname)   # an existing file only gets its credit and licence filled in
            p.update(file=fname, source=d["source"], credit=p.get("credit") or d["credit"], license=d["license"],
                     license_url=d["license_url"], date=d["date"], license_ok=ok)
            print(f"{p['id']}: {fname}  [{d['license']}]  {p['credit'][:50]}")
            time.sleep(0.5)
        elif p.get("url"):
            ext = pathlib.Path(urllib.parse.urlparse(p["url"]).path).suffix.lower() or ".jpg"
            fname = f"{p['id']}{ext}"
            download(p["url"], dst_dir / fname)
            p["file"] = fname
            p.setdefault("license_ok", bool(FREE.search(p.get("license", ""))))
            print(f"{p['id']}: {fname}  [{p.get('license') or 'LICENCE NOT RECORDED'}]")
        else:
            print(f"{p['id']}: no 'commons' or 'url' and no file in assets/photos/; add one")
    (proj / "photos.json").write_text(json.dumps(spec, indent=1, ensure_ascii=False) + "\n")
    if refused:
        sys.exit(f"{refused} image(s) not downloaded; replace them or decide on the rights yourself")

def cmd_credits(a):
    proj = pathlib.Path(a.project)
    spec = json.loads((proj / "photos.json").read_text())
    rows, unclear = [], []
    for p in spec["photos"]:
        lic = p.get("license") or "NOT RECORDED"
        if not p.get("license_ok", bool(FREE.search(lic))):
            unclear.append(p["id"])
        rows.append(f"| {p['id']} | {p.get('what', '')} | {p.get('credit', '')} | {lic} | {p.get('source', '')} |")
    md = ("# Image credits\n\n| ID | What | Credit | Licence | Source |\n|---|---|---|---|---|\n" + "\n".join(rows) + "\n")
    recs = [l for l in spec.get("recreations", [])]
    if recs:
        md += "\n## Recreations drawn in code\n\n" + "\n".join(f"- {r}" for r in recs) + "\n"
    if unclear:
        md += f"\n**Rights unclear:** {', '.join(unclear)}. Verify or replace before publishing anything monetised.\n"
    (proj / "credits.md").write_text(md)
    print(f"credits.md: {len(rows)} images" + (f", rights unclear for {', '.join(unclear)}" if unclear else ", all free"))

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = ap.add_subparsers(dest="cmd", required=True)
    s = sub.add_parser("search"); s.add_argument("query"); s.add_argument("--limit", type=int, default=12)
    c = sub.add_parser("category"); c.add_argument("category"); c.add_argument("--limit", type=int, default=40)
    g = sub.add_parser("get"); g.add_argument("--project", required=True); g.add_argument("--force", action="store_true")
    g.add_argument("--allow-nonfree", action="store_true")
    k = sub.add_parser("credits"); k.add_argument("--project", required=True)
    a = ap.parse_args()
    {"search": cmd_search, "category": cmd_category, "get": cmd_get, "credits": cmd_credits}[a.cmd](a)

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/get_fonts.py
size: 2293
sha: 0542cb0544fd2c2af111f45337f65d9e24e149da
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/get_fonts.py

```text
#!/usr/bin/env python3
"""Fetch open-licensed fonts for any text role this machine cannot match (Linux and Windows lack the
Mac faces the looks were designed with), into <project>/fonts/<role>.ttf where the engine finds them.

  python3 get_fonts.py --project my-film            # only roles that would fall back to the system default
  python3 get_fonts.py --project my-film --force    # replace them all

  cond -> Bebas Neue (SIL Open Font License): condensed caps for labels, numbers, stamps, captions
  hand -> Homemade Apple (Apache 2.0): handwriting for ledger entries

Both come from the Google Fonts repository on GitHub. Keep the licence notes with the project if
you share it.
"""
import argparse
import pathlib
import sys
import urllib.request

HERE = pathlib.Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))
UA = "cinematic-film/1.0 (+https://github.com/Moh4696/cinematic-skill)"
FONTS = {
    "cond": ("https://raw.githubusercontent.com/google/fonts/main/ofl/bebasneue/BebasNeue-Regular.ttf", "Bebas Neue", "SIL Open Font License 1.1"),
    "hand": ("https://raw.githubusercontent.com/google/fonts/main/apache/homemadeapple/HomemadeApple-Regular.ttf", "Homemade Apple", "Apache License 2.0"),
}

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--force", action="store_true")
    a = ap.parse_args()
    from engine import resolve_typeface
    fdir = pathlib.Path(a.project) / "fonts"; fdir.mkdir(parents=True, exist_ok=True)
    notes = []
    for role, (url, name, lic) in FONTS.items():
        _, desc = resolve_typeface(role, fdir)
        if not a.force and not desc.startswith("system default"):
            print(f"{role:<5} already {desc}"); continue
        req = urllib.request.Request(url, headers={"User-Agent": UA})
        with urllib.request.urlopen(req, timeout=60) as r:
            (fdir / f"{role}.ttf").write_bytes(r.read())
        print(f"{role:<5} -> fonts/{role}.ttf  ({name}, {lic})")
        notes.append(f"{role}.ttf: {name}, {lic}, from {url}")
    if notes:
        with open(fdir / "LICENSES.txt", "a") as f:
            f.write("\n".join(notes) + "\n")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/make_beats.py
size: 4144
sha: 04533b60bb91adbb6c060c14c64fcdb8a804a5ab
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/make_beats.py

```text
#!/usr/bin/env python3
"""Write beats.md, the beat table you approve before building: one row per narration line with its
start, length, the one hero on screen and any typed text. Also lints the script.

  python3 make_beats.py --project my-film

Uses audio/timing.json when there is one; before any voice exists it estimates times from the
letters (about 14.5 letters per second plus pauses), so the table can be reviewed first.

Lint (warnings, not errors):
  * chronology: after the cold open (the first take), a year lower than one already reached
  * a line over 22 words (one idea per line; long lines get cut in half by the camera anyway)
  * a line with no hero
  * a phrase typed on screen that is also spoken word for word in the same line
  * digits left in the spoken text (voices misread "1903"; write "nineteen oh three")
"""
import argparse
import json
import pathlib
import re

LPS = 14.5

def mmss(s):
    return f"{int(s // 60)}:{s % 60:04.1f}"

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    script = json.loads((proj / "script.json").read_text())
    tp = proj / "audio" / "timing.json"
    timing = {s["id"]: s for s in json.loads(tp.read_text())["segments"]} if tp.exists() else {}
    lines = [(t["take"], l) for t in script["takes"] for l in t["lines"]]

    warn, rows, cursor, max_year = [], [], 0.9, None
    first_take = script["takes"][0]["take"]
    for take, l in lines:
        i = l["id"]
        if i in timing:
            start, dur = timing[i]["start"], timing[i]["duration"]
        else:
            dur = len(re.sub(r"[^A-Za-z]", "", l["spoken"])) / LPS
            start = cursor
            cursor += dur + l.get("gap_after", 0.45)
        typed = l.get("typed", "") or "--"
        hero = l.get("hero", "")
        rows.append(f"| {i} | {mmss(start)} | {dur:.1f}s | {l['text']} | {hero or '(previous hero holds)'} | {typed} |")
        words = len(l["text"].split())
        if words > 22:
            warn.append(f"line {i}: {words} words; split it (one idea per line)")
        if not hero:
            warn.append(f"line {i}: no hero (say what the camera is on, even if the previous one holds)")
        if re.search(r"\d", l["spoken"]):
            warn.append(f"line {i}: digits in the spoken text {l['spoken']!r}; write numbers as words")
        for ph in [p.strip() for p in re.split(r"[+·,;]", typed) if len(p.strip().split()) >= 3]:   # name bars are fine
            if ph.lower() in l["text"].lower():
                warn.append(f"line {i}: {ph!r} is typed AND spoken word for word; show it one way")
        years = [int(y) for y in re.findall(r"\b(1[0-9]{3}|20[0-9]{2})\b", l["text"])]
        if take != first_take:
            for y in years:
                if max_year is not None and y < max_year:
                    warn.append(f"line {i}: {y} steps back in time after {max_year}; after the cold open, story time only moves forward")
                max_year = y if max_year is None else max(max_year, y)
    total = json.loads(tp.read_text())["total_duration"] if tp.exists() else cursor + 3.0
    src = "timed to audio/timing.json" if timing else "ESTIMATED from letter counts (no voice yet)"
    head = (f"# {script.get('title', proj.name)}: beat table\n\n"
            f"{len(lines)} lines, {mmss(total)} total, {src}.\n\n"
            "Hero = the one thing the camera is on (everything else dims). Typed = text drawn in code; "
            "a phrase is either typed or shown on a real document, never both.\n\n"
            "| # | Start | Len | Narration | Hero on screen | Typed |\n|---|---|---|---|---|---|\n")
    body = "\n".join(rows) + "\n"
    if warn:
        body += "\n## Lint\n\n" + "\n".join(f"- {w}" for w in warn) + "\n"
    (proj / "beats.md").write_text(head + body)
    print(f"beats.md: {len(lines)} beats, {mmss(total)} ({'timed' if timing else 'estimated'}), {len(warn)} warning(s)")
    for w in warn:
        print("  " + w)

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/make_map.py
size: 9142
sha: 37018d6be0ac7f8c3e20e3c5f384fc51ad851775
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/make_map.py

```text
#!/usr/bin/env python3
"""Build the projected map data for GeoMap from public-domain boundaries (TopoJSON or GeoJSON).

  python3 make_map.py --project my-film

Reads map.json in the project:
  {"maps": [{
     "name": "us",
     "source": "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json",   # TopoJSON or GeoJSON, URL or path
     "object": "states",                                                     # TopoJSON object (ignored for GeoJSON)
     "projection": {"type": "albers", "lon0": -96, "lat0": 37.5, "p1": 29.5, "p2": 45.5},
     "drop": ["Alaska", "Hawaii", "Puerto Rico"],          # or "keep": [...]
     "neighbors": {"source": "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-50m.json", "object": "countries",
                   "keep": ["Canada", "Mexico", "Cuba"], "dark": ["Canada", "Mexico"], "clip": [-140, 12, -55, 62]},
     "frame": [-125, 24, -66, 50],                         # optional sheet bounds: lon_min, lat_min, lon_max, lat_max
     "places": {"Dayton": [39.76, -84.19], "Kitty Hawk": [36.06, -75.70]}       # [lat, lon]
  }]}

Projections: albers (equal-area conic; good for one country), equirect (lon0, lat0; fine for a region),
mercator (lon0). Units are earth radii, so GeoMap(K=24000) gives a country about 20,000 world px wide.
Boundaries are kept at full detail: thinning them opened slivers between neighbouring regions.

Good free sources (Natural Earth data is public domain; the atlas packages are ISC-licensed):
  us-atlas@3/states-10m.json (objects: states, nation)   world-atlas@2/countries-50m.json (object: countries)
  both on https://cdn.jsdelivr.net/npm/   Natural Earth GeoJSON: github.com/nvkelso/natural-earth-vector

Downloads are cached in assets/data/. Writes assets/prep/map_<name>.json.
"""
import argparse
import json
import math
import pathlib
import sys
import urllib.request

UA = "cinematic-film/1.0 (+https://github.com/Moh4696/open-3d-skills)"

def load(src, cache):
    if str(src).startswith(("http://", "https://")):
        p = cache / pathlib.Path(src.split("?")[0]).name
        if not p.exists():
            cache.mkdir(parents=True, exist_ok=True)
            req = urllib.request.Request(src, headers={"User-Agent": UA})
            with urllib.request.urlopen(req, timeout=60) as r:
                p.write_bytes(r.read())
            print(f"downloaded {src} -> {p}")
        return json.loads(p.read_text())
    return json.loads(pathlib.Path(src).read_text())

def name_of(props):
    props = props or {}
    for k in ("name", "NAME", "ADMIN", "name_en", "NAME_EN"):
        if props.get(k):
            return props[k]
    return None

def features(data, obj=None):
    """[(name, [ring lon/lat lists])] from TopoJSON or GeoJSON."""
    out = []
    if data.get("type") == "Topology":
        tr = data.get("transform")
        arcs = []
        for arc in data["arcs"]:
            x = y = 0; pts = []
            for p in arc:
                if tr:
                    x += p[0]; y += p[1]
                    pts.append((x * tr["scale"][0] + tr["translate"][0], y * tr["scale"][1] + tr["translate"][1]))
                else:
                    pts.append((p[0], p[1]))
            arcs.append(pts)

        def ring(idx):
            pts = []
            for i in idx:
                a = arcs[i] if i >= 0 else arcs[~i][::-1]
                pts.extend(a if not pts else a[1:])
            return pts
        if obj not in data["objects"]:
            sys.exit(f"object {obj!r} not in TopoJSON; have {list(data['objects'])}")
        for g in data["objects"][obj]["geometries"]:
            polys = g["arcs"] if g["type"] == "MultiPolygon" else [g["arcs"]] if g["type"] == "Polygon" else []
            out.append((name_of(g.get("properties")) or str(g.get("id")), [ring(r) for poly in polys for r in poly]))
    else:
        feats = data["features"] if data.get("type") == "FeatureCollection" else [data]
        for f in feats:
            geo = f.get("geometry") or {}
            polys = geo.get("coordinates", []) if geo.get("type") == "MultiPolygon" else [geo.get("coordinates", [])] if geo.get("type") == "Polygon" else []
            out.append((name_of(f.get("properties")) or str(f.get("id")), [r for poly in polys for r in poly]))
    return out

def projector(spec):
    t = spec.get("type", "albers")
    r = math.radians
    if t == "albers":
        lon0, lat0, p1, p2 = spec.get("lon0", -96.0), spec.get("lat0", 37.5), spec.get("p1", 29.5), spec.get("p2", 45.5)
        n = (math.sin(r(p1)) + math.sin(r(p2))) / 2
        c = math.cos(r(p1)) ** 2 + 2 * n * math.sin(r(p1))
        rho0 = math.sqrt(c - 2 * n * math.sin(r(lat0))) / n

        def f(lon, lat):
            rho = math.sqrt(max(0.0, c - 2 * n * math.sin(r(lat)))) / n
            th = n * r(lon - lon0)
            return rho * math.sin(th), -(rho0 - rho * math.cos(th))      # y down
        return f
    if t == "equirect":
        lon0, lat0 = spec.get("lon0", 0.0), spec.get("lat0", 0.0)
        k = math.cos(r(lat0))
        return lambda lon, lat: (r(lon - lon0) * k, -r(lat - lat0))
    if t == "mercator":
        lon0 = spec.get("lon0", 0.0)
        return lambda lon, lat: (r(lon - lon0), -math.log(math.tan(math.pi / 4 + r(max(-85, min(85, lat))) / 2)))
    sys.exit(f"unknown projection {t!r} (albers, equirect, mercator)")

def clip_ring(ring, box):
    """Sutherland-Hodgman clip of a lon/lat ring to [lon0, lat0, lon1, lat1]."""
    x0, y0, x1, y1 = box
    def clip(pts, inside, cross):
        out = []
        for i, cur in enumerate(pts):
            prev = pts[i - 1]
            if inside(cur):
                if not inside(prev):
                    out.append(cross(prev, cur))
                out.append(cur)
            elif inside(prev):
                out.append(cross(prev, cur))
        return out
    def lerp_x(a, b, x):
        u = (x - a[0]) / (b[0] - a[0]); return (x, a[1] + (b[1] - a[1]) * u)
    def lerp_y(a, b, y):
        u = (y - a[1]) / (b[1] - a[1]); return (a[0] + (b[0] - a[0]) * u, y)
    pts = [tuple(p[:2]) for p in ring]
    for inside, cross in ((lambda p: p[0] >= x0, lambda a, b: lerp_x(a, b, x0)), (lambda p: p[0] <= x1, lambda a, b: lerp_x(a, b, x1)),
                          (lambda p: p[1] >= y0, lambda a, b: lerp_y(a, b, y0)), (lambda p: p[1] <= y1, lambda a, b: lerp_y(a, b, y1))):
        if not pts:
            break
        pts = clip(pts, inside, cross)
    return pts

def project_rings(rings, proj, box=None):
    out = []
    for rg in rings:
        pts = clip_ring(rg, box) if box else [tuple(p[:2]) for p in rg]
        if len(pts) > 2:
            out.append([[round(x, 5), round(y, 5)] for x, y in (proj(lon, lat) for lon, lat in pts)])
    return out

def build(m, cache):
    proj = projector(m.get("projection", {}))
    feats = features(load(m["source"], cache), m.get("object"))
    names = [n for n, _ in feats]
    keep, drop = set(m.get("keep") or []), set(m.get("drop") or [])
    for n in keep | drop:
        if n not in names:
            print(f"  warning: {n!r} not found in {m['source']} (names look like {names[:6]})")
    regions = {}
    for n, rings in feats:
        if (keep and n not in keep) or n in drop:
            continue
        pr = project_rings(rings, proj, m.get("clip"))
        if pr:
            regions.setdefault(n, []).extend(pr)
    out = {"regions": regions, "neighbors": {}, "dark": [], "places": {}, "projection": m.get("projection", {})}
    nb = m.get("neighbors")
    if nb:
        nfeats = features(load(nb["source"], cache), nb.get("object"))
        want = set(nb.get("keep") or [])
        found = set()
        for n, rings in nfeats:
            if want and n not in want:
                continue
            pr = project_rings(rings, proj, nb.get("clip"))
            if pr:
                out["neighbors"].setdefault(n, []).extend(pr); found.add(n)
        for n in want - found:
            print(f"  warning: neighbour {n!r} not found")
        out["dark"] = nb.get("dark", [])
    for name, (lat, lon) in (m.get("places") or {}).items():
        x, y = proj(lon, lat); out["places"][name] = [round(x, 6), round(y, 6)]
    if m.get("frame"):
        a, b, c, d = m["frame"]
        corners = [proj(a, b), proj(a, d), proj(c, b), proj(c, d), proj((a + c) / 2, b), proj((a + c) / 2, d)]
        out["frame"] = [min(p[0] for p in corners), min(p[1] for p in corners), max(p[0] for p in corners), max(p[1] for p in corners)]
    return out

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    spec = json.loads((proj / "map.json").read_text())
    prep = proj / "assets" / "prep"; prep.mkdir(parents=True, exist_ok=True)
    for m in spec["maps"]:
        out = build(m, proj / "assets" / "data")
        (prep / f"map_{m['name']}.json").write_text(json.dumps(out))
        print(f"map_{m['name']}.json: {len(out['regions'])} regions, {len(out['neighbors'])} neighbours, {len(out['places'])} places")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/mix_soundtrack.py
size: 5167
sha: 824c866d17e83ad92ec2e9833c07fa8ba3c16faa
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/mix_soundtrack.py

```text
#!/usr/bin/env python3
"""Mix narration, sound effects and an optional music bed into the film's soundtrack.

  python3 mix_soundtrack.py --project my-film                                   # voice + sfx
  python3 mix_soundtrack.py --project my-film --music audio/score.mp3           # + score, ducked under the voice
  python3 mix_soundtrack.py --project my-film --music audio/score.mp3 --music-db -4 --music-level 0.07 --music-eq-dip 4

The music is side-chain compressed by the narration (it dips while the narrator speaks and swells in
the gaps); the effects ride on top; the whole mix is normalised in two passes (measure, then apply)
to the target loudness with a -1.5 dBTP ceiling, so nothing pumps.

Levels that worked for a tense documentary where the music should be felt, not followed:
  --music-db -4 --sfx-db -3 --duck-ratio 3 --duck-threshold 0.03 --music-level 0.07 --music-eq-dip 4
(music lands near -30 LUFS under a -15 LUFS mix). Writes audio/mix.m4a; --stems also writes the
ducked music alone so you can check its level.
"""
import argparse
import json
import pathlib
import re
import subprocess
import sys

def run(cmd):
    r = subprocess.run(cmd, capture_output=True, text=True)
    if r.returncode != 0:
        sys.exit(f"FAILED: {' '.join(map(str, cmd))}\n{r.stderr[-2500:]}")
    return r

def resolve(proj, p):
    p = pathlib.Path(p)
    return p if p.is_absolute() else proj / p

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--voice", default="audio/narration.m4a")
    ap.add_argument("--sfx", default="audio/sfx.wav")
    ap.add_argument("--music", default=None)
    ap.add_argument("--out", default="audio/mix.m4a")
    ap.add_argument("--music-db", type=float, default=-6.0, help="music gain before ducking")
    ap.add_argument("--sfx-db", type=float, default=-7.0, help="effects bus gain")
    ap.add_argument("--lufs", type=float, default=-15.0)
    ap.add_argument("--fade-in", type=float, default=1.2)
    ap.add_argument("--fade-out", type=float, default=3.5)
    ap.add_argument("--duck-threshold", type=float, default=0.025)
    ap.add_argument("--duck-ratio", type=float, default=4.0)
    ap.add_argument("--music-level", type=float, default=None, help="slow leveller threshold for a score that builds (0.1 = -20 dBFS)")
    ap.add_argument("--music-eq-dip", type=float, default=0.0, help="dB cut in the music around 2.4 kHz, where the voice lives")
    ap.add_argument("--stems", action="store_true")
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    dur = json.loads((proj / "audio" / "timing.json").read_text())["total_duration"]
    voice, sfx = resolve(proj, a.voice), resolve(proj, a.sfx)
    inputs = ["-i", str(voice)]
    graph = "[0:a]aformat=sample_rates=48000:channel_layouts=stereo,asplit=2[v][vk];"
    mix = ["[v]"]
    if sfx.exists():
        inputs += ["-i", str(sfx)]
        graph += f"[1:a]aformat=sample_rates=48000:channel_layouts=stereo,volume={a.sfx_db}dB[s];"
        mix.append("[s]")
    else:
        print(f"no {sfx}: mixing without effects")
    if a.music:
        mi = len(inputs) // 2
        inputs += ["-i", str(resolve(proj, a.music))]
        lev = f"acompressor=threshold={a.music_level}:ratio=3:attack=1500:release=3500:makeup=1," if a.music_level else ""
        lev += f"equalizer=f=2400:t=q:w=1.1:g={-abs(a.music_eq_dip)}," if a.music_eq_dip else ""
        graph += (f"[{mi}:a]atrim=0:{dur:.3f},asetpts=PTS-STARTPTS,aformat=sample_rates=48000:channel_layouts=stereo,{lev}"
                  f"afade=t=in:d={a.fade_in},afade=t=out:st={dur - a.fade_out:.3f}:d={a.fade_out},volume={a.music_db}dB[m];"
                  f"[m][vk]sidechaincompress=threshold={a.duck_threshold}:ratio={a.duck_ratio}:attack=35:release=550:makeup=1:knee=4[md];")
        mix.append("[md]")
    else:
        graph += "[vk]anullsink;"
    premix = graph + "".join(mix) + f"amix=inputs={len(mix)}:duration=first:normalize=0,alimiter=limit=0.9:level=disabled"

    r = run(["ffmpeg", "-v", "info", "-y", *inputs, "-filter_complex", premix + f",loudnorm=I={a.lufs}:TP=-1.5:LRA=11:print_format=json", "-f", "null", "-"])
    m = json.loads(re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", r.stderr, re.S).group(0))
    ln = (f"loudnorm=I={a.lufs}:TP=-1.5:LRA=11:measured_I={m['input_i']}:measured_TP={m['input_tp']}:"
          f"measured_LRA={m['input_lra']}:measured_thresh={m['input_thresh']}:offset={m['target_offset']}:linear=true")
    out = resolve(proj, a.out)
    run(["ffmpeg", "-v", "error", "-y", *inputs, "-filter_complex", premix + "," + ln + ",aresample=48000", "-c:a", "aac", "-b:a", "256k", str(out)])
    print(f"mix: {out}  (measured {m['input_i']} LUFS -> {a.lufs})")
    if a.stems and a.music:
        stem = out.with_name(out.stem + "_music.wav")
        sinks = "[v]anullsink;" + ("[s]anullsink;" if "[s]" in mix else "")
        run(["ffmpeg", "-v", "error", "-y", *inputs, "-filter_complex", graph + sinks.rstrip(";"), "-map", "[md]", str(stem)])
        print(f"ducked music stem: {stem}")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/new_project.py
size: 1938
sha: a36a7b40275386b1b1e254dfcc98c6e2a7670bf3
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/new_project.py

```text
#!/usr/bin/env python3
"""Start a cinematic-film project folder from the template (or copy the worked example).

  python3 new_project.py my-film --title "The Great Molasses Flood"
  python3 new_project.py wright-demo --example        # the Wright Flyer film, ready to fetch, voice and render

Layout:
  script.json   narration, one entry per line (text, spoken, hero, typed), grouped into takes
  photos.json   every image: id, kind, crop, source, credit, licence
  map.json      optional maps (make_map.py)
  scene.py      the film: build_film(doc) places items and camera keys on the voiceover timing
  assets/photos (downloads)  assets/prep (graded, generated)  audio/  out/  fonts/ (optional overrides)
"""
import argparse
import json
import pathlib
import shutil
import sys

SKILL = pathlib.Path(__file__).resolve().parent.parent

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("folder")
    ap.add_argument("--title", default=None)
    ap.add_argument("--example", action="store_true", help="copy the Wright Flyer example instead of the blank template")
    a = ap.parse_args()
    dst = pathlib.Path(a.folder)
    if dst.exists() and any(dst.iterdir()):
        sys.exit(f"{dst} exists and is not empty")
    src = SKILL / "assets" / ("wright-flyer" if a.example else "template")
    shutil.copytree(src, dst, dirs_exist_ok=True)
    for sub in ("assets/photos", "assets/prep", "audio/takes", "out"):
        (dst / sub).mkdir(parents=True, exist_ok=True)
    if a.title:
        sp = dst / "script.json"
        s = json.loads(sp.read_text()); s["title"] = a.title
        sp.write_text(json.dumps(s, indent=1, ensure_ascii=False) + "\n")
    print(f"created {dst} from {src.name}")
    print("next: write script.json, then  make_beats.py -> tts_say.py -> split_takes.py -> build_narration.py")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/prep_assets.py
size: 9720
sha: d7890a8d9bf3353886a36fa82f5367e2cf4f40c3
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/prep_assets.py

```text
#!/usr/bin/env python3
"""Grade the project's images into one look and generate the board textures (no downloaded textures).

  python3 prep_assets.py --project my-film
  python3 prep_assets.py --project my-film --grade natural  # override photos.json "grade"

photos.json:
  {"grade": "bw",
   "photos": [{"id": "P01", "file": "first_flight.jpg", "kind": "photo", "crop": [0.1, 0, 0.9, 1], ...}]}

grade: bw = neutral high-contrast black and white (archive), sepia = warm monochrome,
       natural = keep colour with one shared balance (your own photos, product shots, AI stills)
kind:  photo  -> one duotone (or natural colour)
       paper  -> newsprint: blacks lifted a little so it reads as ink on paper
       doc    -> records and forms: most colour removed, a hint of the paper kept
       color  -> kept in colour, only warmed (magazine covers)
crop:  optional [left, top, right, bottom] as fractions, to cut to the part that matters

Writes assets/prep/photos/<id>.jpg, assets/prep/photos/meta.json and, if missing, the textures
cork.png, cork_dark.png, slate.png, charcoal.png, paper.png, studio.png, night.png, blueprint.png
and relief.png (the boards behind the looks in engine.LOOKS).
"""
import argparse
import json
import math
import pathlib
import sys

import numpy as np
from PIL import Image, ImageFilter, ImageOps

MAX_SIDE = 3200
GRADES = {
    "bw": ((15, 15, 16), (238, 236, 231), (234, 231, 224)),
    "sepia": ((28, 20, 14), (240, 226, 200), (236, 226, 204)),
    "natural": None,          # keep colour: product shots, brand photos, AI stills, modern stories
}

def duotone(gray, shadow, light):
    g = np.asarray(gray, np.float32)[..., None] / 255.0
    shadow = np.array(shadow, np.float32); light = np.array(light, np.float32)
    return (shadow + (light - shadow) * g).clip(0, 255).astype(np.uint8)

def grade(im, kind, look):
    if GRADES[look] is None:              # natural: gentle contrast and a shared, slightly warm balance
        a = np.asarray(ImageOps.autocontrast(im.convert("RGB"), cutoff=0.5), np.float32)
        lum = a.mean(axis=2, keepdims=True)
        a = (lum + (a - lum) * 0.92) * np.array([1.01, 1.0, 0.98])
        return Image.fromarray(a.clip(0, 255).astype(np.uint8))
    shadow, light, paper_light = GRADES[look]
    if kind == "color":
        a = np.asarray(im.convert("RGB"), np.float32) * np.array([1.0, 0.97, 0.9]) + np.array([4, 2, 0])
        return Image.fromarray(a.clip(0, 255).astype(np.uint8))
    g = ImageOps.grayscale(im)
    if kind == "photo":
        a = np.asarray(ImageOps.autocontrast(g, cutoff=1.0), np.float32) / 255.0
        a = np.clip((a - 0.5) * 1.12 + 0.5, 0, 1)
        return Image.fromarray(duotone((a * 255).astype(np.uint8), shadow, light))
    if kind == "paper":
        return Image.fromarray(duotone(ImageOps.autocontrast(g, cutoff=0.4), shadow, paper_light))
    a = np.asarray(im.convert("RGB"), np.float32)
    lum = a.mean(axis=2, keepdims=True)
    a = (lum + (a - lum) * 0.45) * np.array([1.0, 0.99, 0.97])
    return Image.fromarray(a.clip(0, 255).astype(np.uint8))

def prep_photos(proj, look):
    spec = json.loads((proj / "photos.json").read_text())
    look = look or spec.get("grade", "bw")
    out = proj / "assets" / "prep" / "photos"; out.mkdir(parents=True, exist_ok=True)
    meta, missing = {}, []
    for p in spec["photos"]:
        src = proj / "assets" / "photos" / p["file"] if p.get("file") else None
        if not src or not src.exists():
            missing.append(f"{p['id']} ({p.get('file') or 'no file yet'})"); continue
        im = Image.open(src)
        im = im.convert("RGBA") if im.mode in ("P", "LA", "PA") else im
        if im.mode == "RGBA":
            bg = Image.new("RGB", im.size, (235, 228, 214)); bg.paste(im, mask=im.split()[3]); im = bg
        if p.get("crop"):
            w, h = im.size; c = p["crop"]
            im = im.crop((int(c[0] * w), int(c[1] * h), int(c[2] * w), int(c[3] * h)))
        if max(im.size) > MAX_SIDE:
            im.thumbnail((MAX_SIDE, MAX_SIDE), Image.LANCZOS)
        g = grade(im, p.get("kind", "photo"), look)
        g.save(out / f"{p['id']}.jpg", quality=93)
        meta[p["id"]] = {"w": g.width, "h": g.height, "kind": p.get("kind", "photo")}
    (out / "meta.json").write_text(json.dumps(meta, indent=1))
    print(f"photos: {len(meta)} graded ({look})" + (f"; missing {', '.join(missing)}" if missing else ""))
    return not missing

def tile_noise(size, scale, seed):
    """Tileable value noise from FFT-filtered white noise."""
    rng = np.random.default_rng(seed)
    n = rng.standard_normal((size, size))
    fx = np.fft.fftfreq(size)[:, None]; fy = np.fft.fftfreq(size)[None, :]
    f = np.sqrt(fx ** 2 + fy ** 2) * size / scale
    out = np.real(np.fft.ifft2(np.fft.fft2(n) * np.exp(-f ** 2)))
    return (out - out.mean()) / (out.std() + 1e-9)

def make_cork(size=1024):
    base = np.array([92, 62, 38], np.float32)
    n = 0.55 * tile_noise(size, 40, 1) + 0.35 * tile_noise(size, 12, 2) + 0.25 * tile_noise(size, 3, 3)
    speck = np.random.default_rng(4).random((size, size))
    dark = (speck > 0.985).astype(np.float32) * -0.9 + (speck < 0.012).astype(np.float32) * 0.5
    dark = np.asarray(Image.fromarray(((dark + 1) * 127).astype(np.uint8)).filter(ImageFilter.GaussianBlur(0.7)), np.float32) / 127 - 1
    v = n * 0.16 + dark * 0.35
    return (base[None, None, :] * (1 + v[..., None])).clip(0, 255)

def make_paper(size=1024):
    base = np.array([232, 229, 222], np.float32)
    n = 0.5 * tile_noise(size, 60, 11) + 0.3 * tile_noise(size, 8, 12) + 0.2 * tile_noise(size, 2, 13)
    rng = np.random.default_rng(14)
    fib = np.zeros((size, size), np.float32)
    for _ in range(900):                          # short paper fibres
        x, y = rng.integers(0, size, 2); ang = rng.random() * math.pi; ln = rng.integers(6, 22)
        for k in range(ln):
            fib[int(y + k * math.sin(ang)) % size, int(x + k * math.cos(ang)) % size] += 1
    fib = np.asarray(Image.fromarray((fib.clip(0, 1) * 255).astype(np.uint8)).filter(ImageFilter.GaussianBlur(0.6)), np.float32) / 255
    v = n * 0.035 - fib * 0.05
    return (base[None, None, :] * (1 + v[..., None])).clip(0, 255)

def make_flat(rgb, seed, size=1024, amount=0.08):
    n = 0.6 * tile_noise(size, 50, seed) + 0.3 * tile_noise(size, 10, seed + 1) + 0.2 * tile_noise(size, 2, seed + 2)
    return (np.array(rgb, np.float32)[None, None, :] * (1 + n[..., None] * amount)).clip(0, 255)

def make_blueprint(size=1024):
    """Deep blue drafting sheet with a fine grid every 64 px and a heavier line every 256 (tileable)."""
    a = make_flat((22, 52, 98), 71, size, amount=0.06)
    grid = np.zeros((size, size), np.float32)
    for k in range(0, size, 64):
        w = 0.5 if k % 256 == 0 else 0.22
        grid[:, k:k + 2] = np.maximum(grid[:, k:k + 2], w); grid[k:k + 2, :] = np.maximum(grid[k:k + 2, :], w)
    return (a + grid[..., None] * np.array([120, 160, 200], np.float32)).clip(0, 255)

def make_relief(size=1024):
    """Faux terrain relief for map land: tileable multi-octave noise, hill-shaded, soft."""
    n = 0.6 * tile_noise(size, 90, 41) + 0.3 * tile_noise(size, 30, 42) + 0.15 * tile_noise(size, 8, 43)
    gy = (np.roll(n, -1, 0) - np.roll(n, 1, 0)) / 2; gx = (np.roll(n, -1, 1) - np.roll(n, 1, 1)) / 2   # wraps, so it tiles
    shade = np.clip(0.5 + (gx * -1.0 + gy * -1.0) * 1.6, 0, 1)
    return Image.fromarray((shade * 255).astype(np.uint8))

def textures(prep, force=False):
    def save(name, arr):
        p = prep / name
        if force or not p.exists():
            (arr if isinstance(arr, Image.Image) else Image.fromarray(arr.astype(np.uint8))).save(p)
            return name
    made = []
    cork = make_cork() if force or not (prep / "cork.png").exists() or not (prep / "cork_dark.png").exists() else None
    if cork is not None:
        made.append(save("cork.png", cork))
        lum = cork.mean(axis=2, keepdims=True)
        dark = (lum + (cork - lum) * 0.55) * 0.45 + np.array([12, 10, 9]) * 0.55    # calmer cork so colour reads on top
        made.append(save("cork_dark.png", dark))
    if force or not (prep / "paper.png").exists():
        made.append(save("paper.png", make_paper()))
    if force or not (prep / "slate.png").exists():
        made.append(save("slate.png", make_flat((34, 40, 46), 21)))
    if force or not (prep / "charcoal.png").exists():
        made.append(save("charcoal.png", make_flat((30, 29, 28), 31, amount=0.12)))
    if force or not (prep / "relief.png").exists():
        made.append(save("relief.png", make_relief()))
    if force or not (prep / "studio.png").exists():
        made.append(save("studio.png", make_flat((222, 220, 216), 51, amount=0.025)))
    if force or not (prep / "night.png").exists():
        made.append(save("night.png", make_flat((16, 20, 32), 61, amount=0.1)))
    if force or not (prep / "blueprint.png").exists():
        made.append(save("blueprint.png", make_blueprint()))
    made = [m for m in made if m]
    print("textures:", ", ".join(made) if made else "up to date")

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--grade", choices=sorted(GRADES), default=None)
    ap.add_argument("--textures", action="store_true", help="regenerate textures even if present")
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    prep = proj / "assets" / "prep"; prep.mkdir(parents=True, exist_ok=True)
    textures(prep, a.textures)
    ok = prep_photos(proj, a.grade) if (proj / "photos.json").exists() else True
    if not ok:
        sys.exit(1)

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/render.py
size: 7667
sha: 6299e6a5883d9fc4b8dc6f324064cf036797ede0
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/render.py

```text
#!/usr/bin/env python3
"""Render a cinematic-film project (its scene.py) to stills, contact strips, a cue list or an MP4.

  python3 render.py --project my-film --probe 1.0,6.2,11.5 --size 1280x720     # stills -> out/probe/
  python3 render.py --project my-film --strip 17.9:21.6:12 --size 1280x720     # 12-frame contact sheet of a move
  python3 render.py --project my-film --cues                                   # sfx_cues.json for build_sfx.py
  python3 render.py --project my-film --t0 0 --t1 30 --size 1280x720 --out out/draft.mp4 --audio audio/narration.m4a
  python3 render.py --project my-film --size 1920x1080 --out out/final.mp4 --audio audio/mix.m4a

Each worker builds the film, renders a contiguous range of frames and pipes raw RGB into its own
ffmpeg; the chunks are joined losslessly, then the soundtrack is muxed. --workers defaults to what
fits in memory (a 4K worker plus its encoder needs about 2 GB; past that the machine swaps and
everything slows to a crawl).
"""
import argparse
import importlib.util
import json
import multiprocessing as mp
import os
import pathlib
import subprocess
import sys
import time

HERE = pathlib.Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

def load_scene(project):
    path = pathlib.Path(project) / "scene.py"
    if not path.exists():
        sys.exit(f"{path} not found (new_project.py makes one)")
    spec = importlib.util.spec_from_file_location("scene", path)
    mod = importlib.util.module_from_spec(spec)
    sys.path.insert(0, str(path.parent))
    spec.loader.exec_module(mod)
    return mod

def make(project, size):
    from engine import Doc, Renderer
    w, h = map(int, size.lower().split("x"))
    doc = Doc(project)
    film = load_scene(project).build_film(doc)
    return film, Renderer(film, w, h, doc), doc

def total_ram_gb():
    try:
        if sys.platform == "darwin":
            return int(subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True).stdout) / 2 ** 30
        with open("/proc/meminfo") as f:
            return int(f.readline().split()[1]) / 2 ** 20
    except Exception:
        return 8.0

def auto_workers(w, h):
    px = w * h
    per = 0.55 + 1.5 * px / (3840 * 2160)          # GB per worker + encoder, measured: ~0.9 at 1080p, ~2 at 4K
    by_ram = int(total_ram_gb() * 0.6 / per)
    by_cpu = max(1, (os.cpu_count() or 4) - 1)
    return max(1, min(by_ram, by_cpu, 8))

def encoder_args(w, crf):
    # x264 lookahead buffers ran ~2 GB per encoder at 4K; capping them keeps parallel workers in RAM
    lean = ["-rc-lookahead", "10", "-threads", "2"] if w >= 2000 else []
    return ["-c:v", "libx264", "-preset", "medium", "-crf", str(crf), *lean, "-pix_fmt", "yuv420p"]

def worker(args):
    project, size, f0, f1, out, crf = args
    film, r, _ = make(project, size)
    ff = subprocess.Popen(["ffmpeg", "-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24", "-s", f"{r.W}x{r.H}",
                           "-r", str(film.fps), "-i", "-", *encoder_args(r.W, crf), str(out)], stdin=subprocess.PIPE)
    t0 = time.time()
    for n in range(f0, f1):
        ff.stdin.write(r.frame(n).tobytes())
    ff.stdin.close()
    if ff.wait() != 0:
        raise RuntimeError(f"ffmpeg failed for chunk {out}")
    return f0, f1, time.time() - t0

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--size", default="1920x1080")
    ap.add_argument("--probe", default="", help="comma-separated times: one PNG still each")
    ap.add_argument("--strip", default="", help="t0:t1:n  contact sheet of n frames between t0 and t1")
    ap.add_argument("--t0", type=float, default=0.0)
    ap.add_argument("--t1", type=float, default=None)
    ap.add_argument("--out", default="")
    ap.add_argument("--audio", default="")
    ap.add_argument("--workers", type=int, default=0, help="0 = as many as fit in memory")
    ap.add_argument("--crf", type=int, default=16)
    ap.add_argument("--cues", action="store_true")
    a = ap.parse_args()
    proj = pathlib.Path(a.project).resolve()

    if a.cues:
        from engine import Doc
        film = load_scene(proj).build_film(Doc(proj))
        cues = film.all_cues()
        (proj / "sfx_cues.json").write_text(json.dumps({"duration": film.duration, "cues": cues, "room_tone": film.room_tone}, indent=1))
        kinds = {}
        for c in cues:
            kinds[c["type"]] = kinds.get(c["type"], 0) + 1
        print(f"sfx_cues.json: {len(cues)} cues  " + ", ".join(f"{k} {v}" for k, v in sorted(kinds.items())))
        return

    if a.probe or a.strip:
        from PIL import Image
        film, r, _ = make(proj, a.size)
        pdir = proj / "out" / "probe"; pdir.mkdir(parents=True, exist_ok=True)
        if a.probe:
            for ts in [float(x) for x in a.probe.split(",") if x.strip()]:
                t0 = time.time(); img = r.frame(round(ts * film.fps))
                p = pdir / f"t{ts:07.2f}.png"; Image.fromarray(img).save(p)
                print(f"{p}  ({time.time() - t0:.2f}s)")
        if a.strip:
            s0, s1, n = a.strip.split(":"); s0, s1, n = float(s0), float(s1), int(n)
            frames = [Image.fromarray(r.frame(round((s0 + (s1 - s0) * i / max(1, n - 1)) * film.fps))) for i in range(n)]
            cols = 4; rows = (n + cols - 1) // cols
            tw, th = frames[0].width // 2, frames[0].height // 2
            sheet = Image.new("RGB", (cols * tw, rows * th), "white")
            for i, f in enumerate(frames):
                sheet.paste(f.resize((tw, th)), ((i % cols) * tw, (i // cols) * th))
            p = pdir / f"strip_{s0:06.2f}_{s1:06.2f}.jpg"; sheet.save(p, quality=85); print(p)
        return

    if not a.out:
        sys.exit("--out is required for a video render (or use --probe, --strip, --cues)")
    from engine import Doc
    film = load_scene(proj).build_film(Doc(proj))
    fps = film.fps
    t1 = a.t1 if a.t1 is not None else film.duration
    f0, f1 = round(a.t0 * fps), round(t1 * fps)
    n = f1 - f0
    w, h = map(int, a.size.lower().split("x"))
    k = max(1, min(a.workers or auto_workers(w, h), n // 30 or 1))
    work = proj / "out" / "chunks"; work.mkdir(parents=True, exist_ok=True)
    for old in work.glob("*.mp4"):
        old.unlink()
    bounds = [f0 + n * i // k for i in range(k + 1)]
    jobs = [(str(proj), a.size, bounds[i], bounds[i + 1], work / f"c{i:03d}.mp4", a.crf) for i in range(k)]
    print(f"rendering {n} frames ({n / fps:.1f}s) at {a.size} on {k} workers")
    t0 = time.time()
    with mp.get_context("spawn").Pool(k) as pool:
        for b0, b1, dt in pool.imap_unordered(worker, jobs):
            print(f"  frames {b0}-{b1}: {dt:.0f}s ({(b1 - b0) / dt:.1f} fps/worker)", flush=True)
    lst = work / "list.txt"
    lst.write_text("".join(f"file '{j[4].resolve()}'\n" for j in jobs))
    out = pathlib.Path(a.out)
    out = (out if out.is_absolute() else proj / out).resolve()
    out.parent.mkdir(parents=True, exist_ok=True)
    cmd = ["ffmpeg", "-v", "error", "-y", "-f", "concat", "-safe", "0", "-i", str(lst)]
    if a.audio:
        audio = pathlib.Path(a.audio)
        audio = audio if audio.is_absolute() else proj / audio
        cmd += ["-ss", f"{a.t0:.3f}", "-t", f"{t1 - a.t0:.3f}", "-i", str(audio.resolve()),
                "-map", "0:v", "-map", "1:a", "-c:a", "aac", "-b:a", "192k", "-shortest"]
    cmd += ["-c:v", "copy", "-movflags", "+faststart", str(out)]
    subprocess.run(cmd, check=True)
    print(f"wrote {out}  ({n} frames in {time.time() - t0:.0f}s)")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/split_takes.py
size: 8023
sha: 5524b8396535e9469ccdc00280c2482358c7cea5
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/split_takes.py

```text
#!/usr/bin/env python3
"""Split whole-section voice takes into one clip per narration line.

Reading a whole section in one TTS call keeps the delivery consistent, but the film needs the
timing of every line. This finds the pauses in each take (ffmpeg silencedetect) and picks the ones
that best match where each line boundary should fall, by each line's share of the letters, with a
small dynamic program so the cuts stay in order and one bad guess cannot shift every later line.

  python3 split_takes.py --project my-film

Reads   script.json and audio/takes/<take>.wav
Writes  audio/lines/segNN.wav, audio/lines/split_report.json, audio/segments.json

Sanity check: speaking rate is measured in letters per second of actual speech. A line more than
35% off the median is flagged; that is nearly always a misplaced cut or a word the voice dropped.
Listen to every flagged line.

When a voice runs two lines together with no pause (or pauses dramatically inside a line), force
the boundary in audio/overrides.json:  {"cut_before": {"14": 26.80}}  (line id: seconds into its take).
A line can set "gap_after" (seconds of silence after it in the finished track) in script.json.
"""
import argparse
import json
import pathlib
import re
import subprocess
import sys

NOISE_DB = -40        # silence threshold
MIN_SIL = 0.16        # shortest pause considered a candidate cut (s)
LPS_TOL = 0.35        # flag a line whose letters/sec is more than 35% off the median

def run(cmd):
    r = subprocess.run(cmd, capture_output=True, text=True)
    if r.returncode != 0:
        sys.exit(f"FAILED: {' '.join(map(str, cmd))}\n{r.stderr[-1500:]}")
    return r

def duration(path):
    return float(run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(path)]).stdout.strip())

def silences(path):
    err = run(["ffmpeg", "-v", "info", "-i", str(path), "-af", f"silencedetect=noise={NOISE_DB}dB:d={MIN_SIL}", "-f", "null", "-"]).stderr
    starts = [float(x) for x in re.findall(r"silence_start: ([\d.]+)", err)]
    ends = [float(x) for x in re.findall(r"silence_end: ([\d.]+)", err)]
    total = duration(path)
    if len(ends) < len(starts):
        ends.append(total)
    return list(zip(starts, ends)), total

def weight(text):
    """Rough speaking-time weight: letters, plus allowances for commas and sentence breaks inside the line."""
    return len(re.sub(r"[^A-Za-z]", "", text)) + 6 * text.count(",") + 14 * len(re.findall(r"[.!?](?=\s+\S)", text.strip()))

def choose_cuts(cands, w, start, end, p0=0.55):
    """Pick len(w)-1 pauses so each line's length matches its expected length (segment-based DP).
    Longer pauses get a small bonus: sentence ends pause longer than commas."""
    k, n = len(w), len(cands)
    if k == 1:
        return []
    if n < k - 1:
        return None
    rate = max(1e-6, (end - start - k * p0)) / sum(w)
    exp = [wi * rate + p0 for wi in w]
    mids = [(s + e) / 2 for s, e in cands]

    def seg(i, a, b):
        return (((b - a) - exp[i]) / (0.22 * exp[i] + 0.3)) ** 2

    def bonus(j):
        return 1.2 * min(cands[j][1] - cands[j][0], 0.8)
    INF = float("inf")
    cost = [[INF] * n for _ in range(k - 1)]
    back = [[-1] * n for _ in range(k - 1)]
    for j in range(n):
        cost[0][j] = seg(0, start, mids[j]) - bonus(j)
    for i in range(1, k - 1):
        for j in range(n):
            best, arg = INF, -1
            for jp in range(j):
                if cost[i - 1][jp] < INF:
                    v = cost[i - 1][jp] + seg(i, mids[jp], mids[j])
                    if v < best:
                        best, arg = v, jp
            if arg >= 0:
                cost[i][j] = best - bonus(j); back[i][j] = arg
    final = [cost[k - 2][j] + seg(k - 1, mids[j], end) if cost[k - 2][j] < INF else INF for j in range(n)]
    j = min(range(n), key=lambda x: final[x])
    if final[j] == INF:
        return None
    picks = [j]
    for i in range(k - 2, 0, -1):
        j = back[i][j]; picks.append(j)
    return [cands[x] for x in reversed(picks)]

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--gap", type=float, default=0.45, help="default silence after a line in the finished track (s)")
    ap.add_argument("--take-gap", type=float, default=1.0, help="silence after the last line of a take (s)")
    a = ap.parse_args()
    proj = pathlib.Path(a.project)
    script = json.loads((proj / "script.json").read_text())
    tdir, odir = proj / "audio" / "takes", proj / "audio" / "lines"
    odir.mkdir(parents=True, exist_ok=True)
    ov = proj / "audio" / "overrides.json"
    cut_before = json.loads(ov.read_text()).get("cut_before", {}) if ov.exists() else {}

    report, segments = [], []
    for take in script["takes"]:
        wav = tdir / f"{take['take']}.wav"
        if not wav.exists():
            sys.exit(f"missing take: {wav}")
        sil, total = silences(wav)
        speech_start = sil[0][1] if sil and sil[0][0] < 0.05 else 0.0
        speech_end = sil[-1][0] if sil and sil[-1][1] >= total - 0.05 else total
        inner = [(s, e) for s, e in sil if s > speech_start + 0.05 and e < speech_end - 0.05]
        lines = take["lines"]
        w = [weight(l["spoken"]) for l in lines]
        forced = {i: float(cut_before[str(l["id"])]) for i, l in enumerate(lines) if i > 0 and str(l["id"]) in cut_before}
        edges = [0] + sorted(forced) + [len(lines)]
        bounds = [speech_start - 0.05]
        for a_i, b_i in zip(edges, edges[1:]):
            g0 = speech_start if a_i == 0 else forced[a_i]
            g1 = speech_end if b_i == len(lines) else forced[b_i]
            cands = [(s, e) for s, e in inner if s > g0 + 0.05 and e < g1 - 0.05]
            cuts = choose_cuts(cands, w[a_i:b_i], g0, g1)
            if cuts is None:
                sys.exit(f"{take['take']}: only {len(cands)} pauses for {b_i - a_i} lines; re-record with clearer pauses "
                         "or add a cut_before override in audio/overrides.json")
            bounds += [(s + e) / 2 for s, e in cuts]
            if b_i < len(lines):
                bounds.append(forced[b_i])
        bounds.append(speech_end + 0.05)
        for i, line in enumerate(lines):
            t0, t1 = max(0.0, bounds[i]), min(total, bounds[i + 1])
            run(["ffmpeg", "-y", "-v", "error", "-ss", f"{t0:.3f}", "-to", f"{t1:.3f}", "-i", str(wav),
                 "-ar", "48000", "-ac", "1", str(odir / f"seg{line['id']:02d}.wav")])
            pause = sum(min(e, t1) - max(s, t0) for s, e in sil if e > t0 and s < t1)
            speech = max(0.01, (t1 - t0) - pause)
            letters = len(re.sub(r"[^A-Za-z]", "", line["spoken"]))
            report.append({"id": line["id"], "take": take["take"], "start": round(t0, 3), "end": round(t1, 3),
                           "speech_s": round(speech, 2), "letters": letters, "lps": round(letters / speech, 2), "text": line["text"]})
            last = i == len(lines) - 1
            segments.append({"id": line["id"], "scene": take["take"], "caption": line["text"], "vo": line["spoken"],
                             "gap_after": line.get("gap_after", a.take_gap if last else a.gap)})
        print(f"{take['take']:<20} {len(lines)} lines, {len(inner)} pauses, {speech_end - speech_start:5.1f}s of speech")

    med = sorted(r["lps"] for r in report)[len(report) // 2]
    flagged = 0
    for r in report:
        r["flag"] = abs(r["lps"] / med - 1) > LPS_TOL
        flagged += r["flag"]
    (odir / "split_report.json").write_text(json.dumps(report, indent=1))
    (proj / "audio" / "segments.json").write_text(json.dumps({"segments": segments}, indent=1))
    for r in report:
        print(f"  {r['id']:>3} {r['lps']:5.2f} l/s {r['speech_s']:5.2f}s  {r['text'][:64]}{'  <-- CHECK' if r['flag'] else ''}")
    print(f"{len(report)} lines, median {med:.2f} letters/s, {flagged} flagged")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/scripts/tts_say.py
size: 4148
sha: 8889f8b876ca5e3930ccf126aa04eee11180f76b
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/tts_say.py

```text
#!/usr/bin/env python3
"""Record every take in script.json with a local voice: a free scratch track to time the film against.

The film is timed to the voiceover, so the picture cannot be built before there is a voice. A
scratch track from the system voice costs nothing, gives real timings, and is replaced later by
the final voice (any TTS or a human): the scene re-times itself because it asks for line starts
and spoken words, never fixed seconds.

  python3 tts_say.py --project my-film                       # macOS `say`, or espeak-ng on Linux
  python3 tts_say.py --project my-film --voice Daniel --rate 165
  python3 tts_say.py --project my-film --cmd 'piper -m en_US-lessac-medium.onnx -f {out} < {txt}'

--cmd runs any command-line TTS once per take: {txt} is a text file with the take's lines (one per
paragraph), {out} the WAV it must write. Each take is read in one go so the delivery stays even;
split_takes.py then cuts it into lines. Writes audio/takes/<take>.wav.
"""
import argparse
import json
import pathlib
import shutil
import subprocess
import sys
import tempfile

def run(cmd, shell=False):
    r = subprocess.run(cmd, capture_output=True, text=True, shell=shell)
    if r.returncode != 0:
        sys.exit(f"FAILED: {cmd if shell else ' '.join(map(str, cmd))}\n{r.stderr[-1500:]}")
    return r.stdout

def to_wav(src, dst):
    run(["ffmpeg", "-y", "-v", "error", "-i", str(src), "-ar", "48000", "-ac", "1", str(dst)])

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--voice", default=None, help="say / espeak-ng voice name")
    ap.add_argument("--rate", type=int, default=165, help="words per minute (documentary pace is 150-170)")
    ap.add_argument("--pause", type=int, default=650, help="pause between lines, ms (split_takes.py cuts there)")
    ap.add_argument("--cmd", default=None, help="any TTS command with {txt} and {out} placeholders")
    ap.add_argument("--only", default="", help="comma-separated take names to (re)record")
    a = ap.parse_args()

    proj = pathlib.Path(a.project)
    script = json.loads((proj / "script.json").read_text())
    tdir = proj / "audio" / "takes"; tdir.mkdir(parents=True, exist_ok=True)
    only = {x.strip() for x in a.only.split(",") if x.strip()}
    engine = "cmd" if a.cmd else "say" if shutil.which("say") else "espeak-ng" if shutil.which("espeak-ng") else None
    if engine is None:
        sys.exit("no local voice: install espeak-ng (apt install espeak-ng), or pass --cmd for your TTS, "
                 "or record takes elsewhere and save them as audio/takes/<take>.wav")
    with tempfile.TemporaryDirectory() as tmp:
        tmp = pathlib.Path(tmp)
        for take in script["takes"]:
            name = take["take"]
            if only and name not in only:
                continue
            lines = [l["spoken"].strip() for l in take["lines"]]
            out = tdir / f"{name}.wav"
            if engine == "say":
                text = f" [[slnc {a.pause}]] ".join(lines)
                raw = tmp / f"{name}.aiff"
                cmd = ["say", "-r", str(a.rate), "-o", str(raw)] + (["-v", a.voice] if a.voice else []) + [text]
                run(cmd); to_wav(raw, out)
            elif engine == "espeak-ng":
                ssml = "<speak>" + f"<break time='{a.pause}ms'/>".join(lines) + "</speak>"
                raw = tmp / f"{name}.wav"
                cmd = ["espeak-ng", "-m", "-s", str(a.rate), "-w", str(raw)] + (["-v", a.voice] if a.voice else []) + [ssml]
                run(cmd); to_wav(raw, out)
            else:
                txt = tmp / f"{name}.txt"; txt.write_text("\n\n".join(lines) + "\n")
                raw = tmp / f"{name}_raw.wav"
                run(a.cmd.format(txt=str(txt), out=str(raw)), shell=True)
                to_wav(raw, out)
            dur = float(run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(out)]))
            print(f"{name:<20} {len(lines)} lines  {dur:5.1f}s  -> {out}")

if __name__ == "__main__":
    main()
```

## File: skills/cinematic-film/references/archive.md
size: 5087
sha: 7ef0682e80f7b45669244957de1f2e30c9b59ee0
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/archive.md

````text
# Images: archives, your own, AI stills, and the rights

## Three sources

- **Archives** (history, real people, real events): the rest of this file.
- **Your own** (product shots, team photos, screenshots, renders): drop the files in `assets/photos/` and give them a `"file"` entry in `photos.json`. Grade them `natural` so they keep their colour under one shared balance. Anyone recognisable needs to have agreed to appear.
- **AI stills** (illustration, mood, things no camera saw): generate every still with one model and one style reference, so they read as a set. The `motion-assets` skill plans the prompts and the cost before spending anything. Never use AI images of real people, or as evidence of real events. Credit them in `credits.md` as AI-generated.

## What is free to use (archives)

- **Published in the US in 1930 or earlier**: public domain in the US (as of 2026; one more year enters each January).
- **Works of the US federal government** (Library of Congress staff photos, National Archives records made by federal agencies, NASA, military, FBI): public domain in the US.
- **CC0, CC BY, CC BY-SA**: free with credit. BY-SA asks that adaptations carry the same licence; credit it and say so in `credits.md`.
- **"No known copyright restrictions"** (Flickr Commons, LOC collections): usually fine. Record the institution's statement. `fetch_commons.py` marks these CHECK, and `get` refuses them unless you pass `--allow-nonfree` after checking.
- **Not free**: press agency photos after 1930 (AP, Getty, Corbis), film stills, most photos of living people, anything marked NC or ND, anything whose uploader is not the author with no source given.

A Commons page can be wrong. For anything that matters, check that the stated source (an LOC record, a museum page) really says so. Photos taken by the subjects themselves count as theirs: the Wright portraits are credited to the brothers.

## Where to look

| Archive | Good for | How |
| --- | --- | --- |
| Wikimedia Commons | Almost everything famous, with licence fields | `fetch_commons.py search` and `category`. Open the category of a good hit to see its siblings |
| Library of Congress (loc.gov) | US photos, newspapers (Chronicling America), maps | Add `?fo=json` to an item URL for its metadata and full-size image links |
| National Archives (catalog.archives.gov) | Federal records: court files, mugshots, letters, forms | Item JSON: `https://catalog.archives.gov/proxy/records/search?naId=<id>`. The page itself is a JavaScript app |
| State archives and memory projects | Regional history | Many sites load images by JavaScript: open the page in a headless browser and save the image responses |
| Internet Archive book images | Diagrams and engravings from old books | Usually "no known restrictions"; record the book |
| Smithsonian Open Access | Objects and portraits marked CC0 | Filter for CC0 |

Search with the archive's own words. Captions use period terms ("aeroplane", "liquor raid"), so try those as well as modern ones.

## photos.json

```json
{"grade": "bw",
 "photos": [
  {"id": "P01", "what": "First flight, Dec 17 1903", "kind": "photo", "commons": "File:First flight2.jpg"},
  {"id": "P07", "what": "Telegram", "kind": "doc", "url": "https://...", "credit": "...", "license": "Public domain", "source": "https://..."}
 ],
 "recreations": ["Wilbur Wright's 1899 letter: real sentence, page typeset in code."]}
```

- `kind` sets the grade: `photo` (one duotone across the film), `paper` (newsprint, used with `Print(paper=True)` torn edges), `doc` (records keep a hint of their paper colour), `color` (covers that must stay in colour).
- `crop` is `[left, top, right, bottom]` as fractions. Crop to the part that matters: a face on the top third, a headline block, without an uploader's border.
- `credit` overrides the Commons "Artist" field. That field is sometimes only the uploader.

## Rules that keep a film honest

- Never use a stand-in face. If no photo of a person exists, show a document with their name, a blank witness card, or a silhouette labelled as such.
- Never imply a photo shows something it does not. A photo of the machine being readied is not the crash; caption it with what it is.
- A recreated document says "recreation" in `credits.md` and quotes only real words. The narration may read them; the page must not add any.
- `fetch_commons.py credits` writes `credits.md`, ready to paste under a YouTube video or in a reply on X. It lists anything with unclear rights at the bottom. Clear those before anything monetised.

## Measuring positions on a photo

Highlights, circles and holes are placed by fractions of the image (`doc.on(print, fx, fy)`). To find them, draw a 10% grid over the graded image, view it, and read off the fractions:

```python
from PIL import Image, ImageDraw
im = Image.open("assets/prep/photos/P07.jpg"); d = ImageDraw.Draw(im)
for i in range(1, 10):
    x, y = im.width * i // 10, im.height * i // 10
    d.line([(x, 0), (x, im.height)], fill=(255, 0, 0)); d.line([(0, y), (im.width, y)], fill=(0, 0, 255))
im.save("grid.jpg")
```
````

## File: skills/cinematic-film/references/film.md
size: 8043
sha: 2664bef59a448d90ed4d5a1489f6f08180347ec1
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/film.md

````text
# Film: the wall, the camera, the items

## Units and the scene file

World units are 4K screen pixels at camera zoom 1. At zoom 1 the frame shows 3840 x 2160 world px; at zoom 0.5 it shows 7680 x 4320; at 0.13 a whole wall about 30,000 px wide.

```python
from engine import Film, GeoMap, Print, Stamp, StringLine, XMarker, RegionFill, RUST, MUSTARD

def build_film(doc):
    L, E, W = doc.L, doc.E, doc.W          # line start, line end, when a spoken word lands
    film = Film(doc.duration, fps=30, look="wall")
    us = film.add(GeoMap(doc.map("us"), 60000))
    pr = film.add(Print("P01", 27800, 300, 2600, rot=-1.2, t_in=L(2) + 0.1, label="PHOTO: JOHN T. DANIELS", label_t=W(4, "took")))
    film.add(Stamp("FAILED", 25150, -7250, size=330, t_in=W(11, "river") - 0.1))
    film.shot(L(2) + 0.9, 27800, 250, 1.12, rot=-0.6)
    return film
```

- `doc.W(i, "word")` searches the **spoken** text: ask for "nineteen", not "1903". Use `nth=1` for a word's second occurrence.
- `doc.on(print, fx, fy)` gives the world point at a fraction of a print's image, rotation included.
- `doc.res()` measures text while laying out (`PaperDoc.phrase_spans(doc.res(), "not a crank")`).
- `film.add()` returns the item, so later lines can point strings, circles and the camera at it.

## Laying out the wall

1. Give each section a **cluster**: an area of the wall with its prints, documents and numbers. Leave about one print's width between clusters.
2. Put a map in the middle if the story travels. Hang clusters near the places they belong, on the map or out on the cork beside it, and tie them to their place with a `StringLine`.
3. Travel between clusters along a string (evidence: this leads to that) or a `Route` (people moving). The camera follows the line as it draws on.
4. Make the final pull-back a composition: everything still visible should read as one designed board.

**Map scale.** `GeoMap(data, K)`: K is world px per earth radius. At K=24000 the lower 48 states are about 17,000 px wide, which suits a story spread across the country. When several places a few hundred km apart each need their own prints (Dayton, Washington, the Outer Banks), use K=50000 to 70000 so each gets its own room. Close up, the map draws live vectors, so it stays sharp at any K.

## Camera

- One `film.shot(t, x, y, zoom, rot)` (or `cam` plus `focus`) every 0.6 to 3 seconds. The spline is monotone and keeps drifting through keys, so a hold is two keys close together, slightly apart.
- **Push in** to land on a hero: zoom from about 0.5 to 0.9 to 1.2 as the line reaches its key word.
- **Pull back** to show a connection or a place: zoom 0.2 to 0.35.
- **Whip** between clusters in 0.8 to 1.2 s. Motion blur and a whoosh are added on their own.
- Lean the roll a degree or two (`rot`) and let it change between keys. The handheld drift is built in.
- Land the camera on a hero about 0.3 s **after** it appears. It reads as the camera noticing it.
- Shakes: `Stamp` and `Ledger` shake the camera by themselves; `film.shake(t, amp, dur)` for anything else.

## Spotlight

`film.focus(t, x, y, radius, strength)` dims everything outside the hero. The hero is clear within about 0.7 x radius, and fully dim (strength) past 2.4 x radius. Use `film.shot()` so the light moves with the camera. For wide shots use a large radius and a low strength (0.15 to 0.3).

## Items

| Item | Use | Key arguments |
| --- | --- | --- |
| `Print(key, x, y, w, rot, t_in)` | A photo or document. `paper=True` makes a torn clipping that tears in | `label`, `label_t` (red name bar), `t_out`, `exit_vec` (slides off), `dim` |
| `PaperDoc(x, y, w, h, ...)` | A typeset document (a recreation): header lines, grey rows, one real sentence | `header=((text, size, font),)`, `sentence`, `phrase_spans()` |
| `Card(x, y, w, h, t_in, title, lines)` | A clean rounded panel for explainers and product stories; rises into place | `accent`, `rgb`, `text_rgb`, `title_size`, `body_size` |
| `Ledger`, `OpenLedger` | A closed ledger or file that slams down; an open spread with one handwritten entry | `label`, `entry`, `entry_mark()` |
| `BigText(text, x, y, size, t_in)` | Years, titles, numbers. Distressed by default | `bar=HILITE`, `bar_h` (0.92 for a full block), `type_on`, `hit` |
| `Counter(x, y, size, value, t_in)` | A number rolling up | `prefix`, `suffix`, `caption`, `dur` |
| `Stamp(text, x, y, size, rot, t_in)` | A verdict slammed onto a print | `rgb`, `shake` |
| `PenMark(kind, x, y, w, h, t_in)` | ellipse, underline, strike, arrow, highlight | `dur`, `width`, `rot`, `rgb` |
| `StringLine(a, b, t_in)` | Red string, pin to pin | `persist=True` to keep it; it fades after `hold` by default |
| `Chalk(x, y, times)` | Tally marks, one per time | `strike_t` |
| `Holes(print, pts, times)` | Holes punched into a print (shots, a punch card) | fractional `pts` |
| `FilmFrame(print, t_in)` | Film-strip bands around a print | |
| `DotField(points, t0, t1)` | Dots popping up (bars, stores, outbreaks) | `rgb`, `r` |
| `GeoMap(data, K)` | The map sheet | `look="explainer"` or `"period"`, `place(name)` |
| `RegionFill(map, names, rgb, t_in)` | Fill states or countries; `to_rgb`/`t_change` turns active RUST into visited MUSTARD | |
| `XMarker(x, y, label, t_in)` | A map marker with a typed-on label | `side`, `size`, `label_size` |
| `MapPin(x, y, label, t_in)` | A pulsing red pin with a typewriter label | |
| `Route(a, b, t_in)` | A white travel arc drawing on | `bend`, `width` |

Every item takes `t_out` (fade out), `z` (stacking order) and `sfx=False` (mute its own sounds). Write a new item by subclassing `Item`: give it `bounds()` for culling, `draw(c, res, t)`, and optionally `cues()` and `shakes()`. A big static drawing (a city street map, a floor plan) subclasses `Cached` too, so it is drawn once and reused.

## Looks and type

`Film(look=...)`:

- `wall`: dark cork, warm. True stories.
- `slate`: blue-grey. Business, politics.
- `charcoal`: neutral black. Lets colour photos lead.
- `paper`: light desk.
- `studio`: light seamless. Products, brands, explainers with cards.
- `blueprint`: deep blue with a grid. Engineering, science.
- `night`: dark navy with strong glow. Tech, space, trailers.

Change the finish with `film.look["grain"]`, `["glow"]`, `["vignette"]`, `["grade"]` and `["dim"]` (the spotlight colour; light looks dim towards grey, not black).

On light looks, use dark type and `BigText(grunge=False, shadow=False)` for a clean finish. Use `Print(pin=False)` for photos that should sit like prints on a table, not pinned evidence.

Font roles are `cond` (labels, numbers, stamps), `label` and `labelm` (map labels, captions), `serif` (documents), `mono` (typewriter), `hand` (handwriting). Each falls back through common fonts. Put a file at `fonts/<role>.ttf` in the project to force one, for example Oswald Bold (OFL) as `cond` on Linux. `check_setup.py` prints what each role resolves to, and `get_fonts.py` fetches Bebas Neue (condensed) and Homemade Apple (handwriting) for any role that would fall back to the system default.

Colour on dark looks: white or cream type. Dark ink goes only on paper, cards or a full yellow block (`bar_h=0.92`).

Pick one accent per film and keep it for the things that matter. In the documentary kit that is yellow for highlights and dates and red for verdicts and names; teal is water, and RUST then MUSTARD marks map regions (active, then visited). A brand film uses its own brand colour as the accent.

## Review loop

```bash
python3 scripts/render.py --project my-film --probe 2,5.5,9,12.5 --size 1280x720   # one still per line
python3 scripts/render.py --project my-film --strip 16.8:21.7:12 --size 1280x720   # a camera move as a contact sheet
```

Put the probe stills on one contact sheet and look at all of them. Check:

- the hero is lit and readable
- nothing important is cut by the frame edge
- type is not dark on dark
- labels don't collide
- the spotlight follows the camera
- no frame is empty mid-move

Fix, then probe again. Use a strip for each move between clusters.
````

## File: skills/cinematic-film/references/performance.md
size: 2884
sha: 91a63ff377752b87106f5a71aad78f40c55cf793
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/performance.md

````text
# Performance and delivery

## Render speed

Skia draws on the CPU. These rules took a 38 second draft from 22 minutes to 3:

- **Never fill with a repeating image shader under rotation.** It was about 70x slower than tiling the same image with `drawImageRect`. `tile_image()` does the tiling; use it for any texture.
- **Give every item `bounds()`.** Off-screen items are skipped. An item without bounds draws every frame, wherever the camera is.
- **Cache big static vector art** (`Cached`). Maps and street sheets draw once into an image and switch to live vectors only when the camera is close.
- **Profile one frame, not the run.** Time `Renderer.frame(n)` for a slow frame and comment items out until it is fast. A single slow item usually costs most of the time.
- Motion blur draws up to 8 sub-frames during fast moves. Whips cost more than holds; that is expected.

## Memory

Each render worker builds its own copy of the film and runs its own encoder.

| Size | Per worker (with encoder) | Workers on 16 GB |
| --- | --- | --- |
| 1280x720 | about 0.6 GB | 7 |
| 1920x1080 | about 0.9 GB | 6 to 7 |
| 2560x1440 | about 1.3 GB | 4 to 5 |
| 3840x2160 | about 2 GB | 3 to 4 |

`render.py` picks the worker count from total memory unless you pass `--workers`. Going past it puts the machine into swap, and then everything crawls. A 4K run with 15 GB of swap had to be killed. The other settings that keep a worker small:

- photos are capped at 2200 px times the render scale
- cache images are capped at 8192 px
- x264 runs with `-rc-lookahead 10 -threads 2` at 2000 px wide and up (its lookahead alone took about 2 GB at 4K)
- grain is half resolution and changes every second frame (full-resolution grain every frame made a 38 s clip 625 MB)

## Choosing a resolution

- **Drafts**: 1280x720.
- **X**: 1920x1080. X serves 1080p at most.
- **YouTube**: 2560x1440 is the sweet spot. It gets YouTube's better encode, at about a third of the cost of 4K.
- **4K**: only if asked. About 3 hours for 5 minutes on a 16 GB laptop.

## Captions

```bash
python3 scripts/burn_captions.py --project my-film --video out/final.mp4 --audio audio/mix.m4a --style highlighter --out out/final_captions.mp4
python3 scripts/burn_captions.py --project my-film --srt-only --out out/captions.srt
```

- **Styles**: `highlighter` (condensed caps, the current word swiped yellow), `clean` (classic subtitle), `paper` (typewriter on a torn strip), `redbar` (caps on a red bar). Render a still of each over the busiest shot and let the user pick.
- Captions occupy the bottom 26% of the frame. Keep big numbers and labels above it in the scene.
- **Deliver**: a captioned file for X and Instagram (they autoplay muted), and a clean file plus the SRT for YouTube.
- Also make a small phone preview (`ffmpeg -i final.mp4 -vf scale=960:-2 -crf 28 preview.mp4`), to send for review before the big upload.
````

## File: skills/cinematic-film/references/sound.md
size: 2659
sha: 7fa19334739cef6695960c29396b11f0d6f0c752
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/sound.md

````text
# Sound

Three layers: the narration, synthesised effects, and an optional score. Effects should be felt, not noticed; the voice always wins.

## Effects

```bash
python3 scripts/render.py --project my-film --cues     # sfx_cues.json
python3 scripts/build_sfx.py --project my-film          # audio/sfx.wav
```

Items cue their own sounds:

| Item | Sound |
| --- | --- |
| `Print` | pop (slide for torn clippings) |
| `Stamp` | stamp |
| `PenMark` | pencil (marker for highlights, snip for quick strikes) |
| `Chalk` | tick per mark |
| `Counter` | ticks |
| `Route` | whoosh |
| `StringLine` | slide |
| `XMarker`, `MapPin` | pop |
| `Ledger` | impact |

Fast camera moves get a whoosh. A cue the scene places by hand within 0.15 s replaces the automatic one, and `sfx=False` mutes an item.

Add the score-like moments by hand:

- `film.cue("boom", title_t, 0.55)`: the title or the biggest reveal. Use it once or twice per film.
- `film.cue("riser", L(9) - 1.3, 0.5, dur=1.2)`: a crescendo into a new section. It peaks at `t + dur`, so end it on the line start.
- `film.cue("heartbeat", t)` once a second, 3 to 6 beats, under the tensest line. Or `film.cue("clock", t, dur=4)`.
- `film.cue("impact", t, 0.4)`: a number or year landing. Also available as `BigText(hit=0.4)`.
- `film.room_tone = [[0, film.duration]]`: a quiet room bed. Leave gaps in it for deliberate silence.

## Score

Optional. A documentary bed works best when it is sparse:

- a low pulse
- a few held notes
- silences that line up with section changes

Generate one (ElevenLabs Music, or any music model whose terms allow it), use a licensed track, or skip it. Most tense true stories play better on effects alone, with the score very low. Check where the score's own breaks fall, and move it (or cut lines) so they hit section starts.

## Mix

```bash
python3 scripts/mix_soundtrack.py --project my-film                                    # voice + effects
python3 scripts/mix_soundtrack.py --project my-film --music audio/score.mp3 \
    --music-db -4 --sfx-db -3 --duck-ratio 3 --duck-threshold 0.03 --music-level 0.07 --music-eq-dip 4
```

- The score ducks under the narration (sidechain), and a slow leveller stops a building score swamping the voice. A small dip at 2.4 kHz clears the voice's presence band.
- Two-pass loudness: -15 LUFS integrated, -1.5 dBTP. That suits X, YouTube and Instagram; YouTube turns louder files down anyway.
- Check the result by listening on phone speakers and on headphones. If you can follow the score's melody, it is too loud.
- `--stems` writes the ducked music alone, to measure it. Under -30 LUFS in a -15 mix reads as "felt, not followed".
````

## File: skills/cinematic-film/references/story.md
size: 4997
sha: 5c2c57e89c59dadac974af4deeadfdf263298587
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/story.md

````text
# Story: research, script, beat table

## Research

- Start from sources that would survive a fact-check: museum and archive pages (Smithsonian, Library of Congress, National Archives, national park sites), court records, contemporary newspapers, and good biographies. Use Wikipedia for leads only.
- Write `fact_notes` in `script.json` as you go: one line per claim, with the number, the date and where it came from. When sources disagree, say "about", "reported" or "commonly cited", or drop the claim.
- Quotes must be the person's real words. When you quote a document on screen, quote only what it says, and mark the page as a recreation in `photos.json` `recreations`.
- Check calendar facts: weekdays, intervals ("nine days later"), ages. The Wright example checks that Oct 9, 1903 was a Friday, because a typeset newspaper header shows it.

## Shapes

Every shape opens on a hook, moves forward, turns, and closes by paying off the hook while the camera pulls back to the whole board.

**Documentary, history, true crime**
- **Cold open** (2 to 5 lines): the most vivid moment, out of order. Then a title.
- **Bridge** (1 line): the only step back in time. "Four years earlier, ..." or "It started in Brooklyn, in 1899."
- **Sections** (3 to 6 lines each, one take each): strictly forward in time. Each section ends on a line that hands off to the next.
- **Turn**: the rival, the mistake, the price. Short punchy lines ("Same river. Same result.").
- **Close** (2 lines): pay off the cold open, then one line that lands the meaning.

**Product launch**
- **Problem** (2 lines): the pain, in the customer's words, with one number.
- **Reveal** (1 line): the product name, big. Then a title moment.
- **Three proofs** (2 or 3 lines each): what it does, shown, not claimed. Use one card or one product shot per proof, and a counter for each measurable claim.
- **Close**: the price or availability, and the line people will repeat.

**Brand or founder story**
- **Then**: where it started (a garage, a kitchen, a rejection letter).
- **The bet**: the risky decision.
- **The hard part**: what nearly ended it.
- **Now**: one number for scale.
- **Why**: the line that says what it was all for.

**Explainer (science, tech, how it works)**
- **The question** (1 line), asked the way a curious person would.
- **Steps** (one card or diagram each), in the order things happen. Arrows draw on between the steps.
- **The surprise**: the counter-intuitive fact.
- **Close**: the answer to the question in one sentence.

**Biography**: the same as a documentary. Open on the defining moment, bridge to childhood, then life in order.

Facts in a product or brand film are claims. Each still needs a source in `fact_notes` (a spec sheet, a press release, a dated report).

## Lines

- One idea per line, 4 to 18 words. A line is one hero on screen, so a 30-word line either holds one shot too long or crams in three heroes.
- Write for the ear: short words, concrete nouns, numbers people can picture ("less than a thousand dollars", not "under $1K").
- Put the key word last, so the visual hit lands near the end of the line where the pause follows.
- `spoken` is the same line in the form the voice reads. Write numbers as words ("nineteen oh three", "fifty thousand dollars", "fifty-nine seconds"). Spell names out phonetically if the voice stumbles on them. Leave abbreviations out. `make_beats.py` flags digits left in.
- `hero` says what the camera is on. `typed` lists any text drawn in code: labels, big numbers, stamps, document headers. Text on a document or photo is not typed.
- `gap_after` (seconds) adds room after a line: after the cold open, before a title, after a reveal. The default is 0.45, or 1.0 at the end of a take.

## script.json

```json
{"title": "Twelve Seconds",
 "takes": [{"take": "T01_cold_open", "lines": [
   {"id": 1, "text": "December 17th, 1903. A windy beach in North Carolina.",
    "spoken": "December seventeenth, nineteen oh three. A windy beach in North Carolina.",
    "hero": "the date, set big; then the map pin", "typed": "DECEMBER 17, 1903 · KILL DEVIL HILLS, N.C."}]}],
 "fact_notes": ["..."]}
```

Line ids are global and never reused. Takes are the units you record in one go, usually one per section.

## Length

| Length | Words | Lines | Takes |
| --- | --- | --- | --- |
| 60 s | about 150 | 12 to 15 | 3 to 4 |
| 90 s | about 230 | 18 to 20 | 4 to 5 |
| 5 min | about 750 | 70 | 10 |

A first film should be 60 to 90 seconds. The 5-minute version is the same method with more sections. Build and review it section by section, and look at a draft of each section before starting the next.

## Beat table

`make_beats.py` turns `script.json` (plus `audio/timing.json` when there is one) into `beats.md`. Show it to the user before any building. The lint catches:

- a year that steps back in time after the first take
- lines over 22 words
- lines with no hero
- a phrase that is typed and also spoken word for word
- digits in the spoken text
````

## File: skills/cinematic-film/references/voice.md
size: 2993
sha: df399a437daa8293cb2fffea6fc1502a6e806f81
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/voice.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/references/voice.md

## File: skills/cinematic-film/assets/template/map.json
size: 323
sha: 2717bc21a03b48ddf11de2869dc76ee53a01673c
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/map.json

```text
{
 "maps": [{
  "name": "world",
  "source": "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-50m.json",
  "object": "countries",
  "projection": {"type": "equirect", "lon0": 10, "lat0": 0},
  "drop": ["Antarctica"],
  "places": {"Addis Ababa": [9.03, 38.74], "Bogota": [4.71, -74.07], "Hanoi": [21.03, 105.85]}
 }]
}
```

## File: skills/cinematic-film/assets/template/photos.json
size: 59
sha: 5d16949966e268c4b17808c60943109787c94ba0
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/photos.json

```text
{
 "grade": "natural",
 "photos": [],
 "recreations": []
}
```

## File: skills/cinematic-film/assets/template/scene.py
size: 2574
sha: b451083b2990154d347abed685fe8e3557b22a03
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/scene.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/scene.py

## File: skills/cinematic-film/assets/template/script.json
size: 1524
sha: 60062efbe1b4d71e16e832594ab08b8fa461a76e
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/script.json

```text
{
 "title": "From Cherry to Cup",
 "takes": [
  {"take": "T01_open", "lines": [
   {"id": 1, "text": "Every cup of coffee starts as a cherry.",
    "spoken": "Every cup of coffee starts as a cherry.",
    "hero": "the title, set big", "typed": "FROM CHERRY TO CUP", "gap_after": 0.8}
  ]},
  {"take": "T02_journey", "lines": [
   {"id": 2, "text": "It grows on a shrub, in a band around the equator called the Coffee Belt.",
    "spoken": "It grows on a shrub, in a band around the equator called the Coffee Belt.",
    "hero": "card GROW", "typed": "GROW"},
   {"id": 3, "text": "Pickers take the ripe cherries, and the fruit is washed or dried away.",
    "spoken": "Pickers take the ripe cherries, and the fruit is washed or dried away.",
    "hero": "card PICK", "typed": "PICK"},
   {"id": 4, "text": "The green seed inside is roasted at around 200 degrees.",
    "spoken": "The green seed inside is roasted at around two hundred degrees.",
    "hero": "card ROAST; the number rolls up", "typed": "ROAST · 200°C"},
   {"id": 5, "text": "Then it is ground, brewed, and poured.",
    "spoken": "Then it is ground, brewed, and poured.",
    "hero": "card BREW", "typed": "BREW"}
  ]},
  {"take": "T03_close", "lines": [
   {"id": 6, "text": "Months of work, for a few minutes in a cup.",
    "spoken": "Months of work, for a few minutes in a cup.",
    "hero": "pull back: the whole journey", "typed": ""}
  ]}
 ],
 "fact_notes": ["Replace this template with your own story; keep one note per claim with its source."]
}
```

## File: skills/cinematic-film/assets/wright-flyer/map.json
size: 716
sha: 42cedf2b30e59fdbd3bf441698b0fe1056016dbc
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/map.json

```text
{
 "maps": [{
  "name": "us",
  "source": "https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json",
  "object": "states",
  "projection": {"type": "albers", "lon0": -96, "lat0": 37.5, "p1": 29.5, "p2": 45.5},
  "drop": ["Alaska", "Hawaii", "Puerto Rico", "Guam", "American Samoa", "United States Virgin Islands", "Commonwealth of the Northern Mariana Islands"],
  "neighbors": {"source": "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-50m.json", "object": "countries",
                "keep": ["Canada", "Mexico", "Cuba", "Bahamas"], "dark": ["Canada", "Mexico"], "clip": [-135, 14, -55, 58]},
  "places": {"Dayton": [39.76, -84.19], "Kill Devil Hills": [36.02, -75.67], "Washington": [38.90, -77.04]}
 }]
}
```

## File: skills/cinematic-film/assets/wright-flyer/photos.json
size: 1617
sha: d7a01b82289457f3176d9556555680e84d32d9e5
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/photos.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/photos.json

## File: skills/cinematic-film/assets/wright-flyer/scene.py
size: 11766
sha: 087172bd489145f655c0b91e43cb9fafcbf4afa6
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/scene.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/scene.py

## File: skills/cinematic-film/assets/wright-flyer/script.json
size: 6670
sha: c81e98fb8c5fe95aed15e6cf272206cff87eb3fb
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/script.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/wright-flyer/script.json

## File: skills/cinematic-film/agents/openai.yaml
size: 158
sha: 207b58ccb0b51759b0d0f7141407260b32ca8df6
upstream: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/agents/openai.yaml

Content is not inlined in the catalog. Read the upstream file: https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/agents/openai.yaml

## File: README.md
upstream: https://github.com/moh4696/cinematic-skill/blob/main/README.md

````text
<h1 align="center">Cinematic Skill</h1>

<p align="center">Narrated cinematic films, built entirely from code, by your coding agent.</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-24292f?style=flat" alt="MIT License" /></a>
  &nbsp;
  <img src="https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Cursor%20%C2%B7%20Gemini%20%C2%B7%20OpenCode-24292f?style=flat" alt="Works with Claude Code, Codex, Cursor, Gemini CLI and OpenCode" />
  &nbsp;
  <a href="https://github.com/Moh4696/cinematic-skill/actions/workflows/check.yml"><img src="https://github.com/Moh4696/cinematic-skill/actions/workflows/check.yml/badge.svg" alt="Checks" /></a>
</p>

<p align="center">
  <img src="examples/film-cold-open.webp" alt="The cold open of a code-built documentary about the first flight: the date set big on a yellow block, the camera pulls back to a map pin on the Outer Banks, then glides to the 1903 first-flight photograph pinned to a cork wall as counters roll up to 12 seconds and 120 feet." width="100%" />
</p>

Ask your agent for "a 90 second documentary about the Wright brothers" and it writes the script, records a voice, finds public-domain photos with their licences, and builds one continuous camera move over a single designed world. Stamps slam, highlighters swipe and numbers roll up on the exact word the narrator says. It finishes with sound effects, an optional score and burned-in captions.

Nothing is generated video. Every frame is drawn by code (Skia, in Python), so the film renders the same every time, changes are cheap, and a new voice re-times the whole film by itself.

<table>
  <tr>
    <td width="50%"><img src="examples/film-wall.webp" alt="The final pull-back of the documentary: a US map print with Ohio and North Carolina filled, a route from Dayton to Kill Devil Hills, portraits, a typeset letter, Langley's failed machine with two stamps, and the first-flight photo with its counters, all on one cork wall" /></td>
    <td width="50%"><img src="examples/film-explainer.webp" alt="The starter explainer in the light studio look: the title From Cherry to Cup over four cards, Grow, Pick, Roast and Brew, joined by arrows, with a 200 degree counter" /></td>
  </tr>
</table>

<sub>Left: the final frame of "Twelve Seconds", the 90 second documentary that ships as the worked example, made from seven public-domain photos. Right: the starter explainer that every new project begins as.</sub>

## Install

```bash
npx skills add Moh4696/cinematic-skill
```

That uses the [`npx skills`](https://github.com/vercel-labs/skills) CLI (Node 22.20+). It installs for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and dozens more. Start a new agent session afterwards.

<details>
<summary>Claude Code plugin</summary>

```
/plugin marketplace add Moh4696/cinematic-skill
/plugin install cinematic-skill@cinematic-skill
```

</details>

<details>
<summary>Codex plugin</summary>

```bash
codex plugin marketplace add Moh4696/cinematic-skill
codex plugin add cinematic-skill@cinematic-skill
```

</details>

<details>
<summary>Gemini CLI</summary>

```bash
gemini extensions install https://github.com/Moh4696/cinematic-skill
```

</details>

<details>
<summary>Without Node: the shell installer</summary>

```bash
curl -fsSL https://raw.githubusercontent.com/Moh4696/cinematic-skill/main/install.sh | bash
```

It clones to `~/.cinematic-skill` and links the skill into every coding agent it finds. Run it again to update. From a clone: `./install.sh --claude --codex`, `./install.sh --dir path/to/skills`, `./install.sh --copy`, `./install.sh --uninstall`.

</details>

Then install what the scripts use:

```bash
pip install -r requirements.txt      # skia-python, numpy, pillow (scipy optional)
```

ffmpeg must be on your PATH. The skill's `check_setup.py` checks everything and says what's missing.

## What it makes

| Kind | Look | Images |
| --- | --- | --- |
| Documentary, history, true crime | Cork evidence wall, slate | Archive photos and documents, black and white |
| Product launch, brand or founder story | Studio, charcoal | Your own product shots and photos, in colour |
| Science, engineering, how it works | Blueprint, paper | Diagrams, archive or AI stills |
| Tech, space, trailers | Night | Screenshots, renders, AI stills |

The items work on every look:

- photos and torn newspaper clippings
- typeset documents with real quotes
- clean cards
- big distressed type and rolling counters
- stamps, pen circles and highlighter swipes
- red string between prints
- maps of any country, with filled regions, routes and markers

A spotlight follows the camera so each line has one hero.

## How it works

1. **Story.** The agent researches, fact-checks and writes the script: one idea per line, and time only moves forward after the opening. Each line also says what the camera shows. A beat table with a chronology lint goes to you for approval.
2. **Voice.** A free scratch voice (macOS `say` or espeak-ng) times the film first. The final voice can be any TTS or a person, recorded one section at a time and split into timed lines automatically. Suspect cuts get flagged.
3. **Images.** Wikimedia Commons search and download, with each licence recorded. Non-free files are refused. You can also add your own photos or AI stills. `credits.md` is written for you.
4. **Scene.** A short Python file places items on the voice's timing (`doc.W(line, "word")`) and keys the camera.
5. **Review.** The agent renders stills and contact strips of every move and checks them for known mistakes before showing you a draft.
6. **Sound and finish.** It synthesises the sound effects (nothing to license) and mixes them with the voice and an optional score, ducked and loudness-normalised. A memory-aware parallel render follows, then four caption styles and an SRT.

The agent stops for your approval after the beat table, the look, and a 30 second draft.

## Try the example

```bash
cd skills/cinematic-film/scripts
python3 new_project.py ~/wright --example
python3 fetch_commons.py get --project ~/wright
python3 make_map.py --project ~/wright && python3 prep_assets.py --project ~/wright
python3 tts_say.py --project ~/wright && python3 split_takes.py --project ~/wright && python3 build_narration.py --project ~/wright
python3 render.py --project ~/wright --size 1280x720 --out out/draft.mp4 --audio audio/narration.m4a
```

On a 16 GB laptop the 92 second film renders at 1080p in about 6 minutes.

## Credits

Built from a 5 minute documentary about Al Capone that exploraX made with an agent, then opened up to any subject. The rules and code here were written from what broke along the way. The example film uses public-domain photographs from Wikimedia Commons; see its `photos.json`.

## Works well with

- [Open 3D Skills](https://github.com/Moh4696/open-3d-skills): three.js scenes, scroll films and frame-exact recording, from the same author. Its `motion-assets` skill plans AI stills.

## Feedback

Open an issue or a pull request, or find me on X at [@exploraX_](https://x.com/exploraX_).

## License

[MIT License](LICENSE) · Copyright (c) 2026 exploraX
````
