⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

cinematic-film

moh4696@moh4696⭐ 272 stars· last commit 6d ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 272 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

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.

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.

Install

npx skills add Moh4696/cinematic-skill

That uses the npx skills CLI (Node 22.20+). It installs for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and dozens more. Start a new agent session afterwards.

/plugin marketplace add Moh4696/cinematic-skill
/plugin install cinematic-skill@cinematic-skill
codex plugin marketplace add Moh4696/cinematic-skill
codex plugin add cinematic-skill@cinematic-skill
gemini extensions install https://github.com/Moh4696/cinematic-skill
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.

Then install what the scripts use:

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

KindLookImages
Documentary, history, true crimeCork evidence wall, slateArchive photos and documents, black and white
Product launch, brand or founder storyStudio, charcoalYour own product shots and photos, in colour
Science, engineering, how it worksBlueprint, paperDiagrams, archive or AI stills
Tech, space, trailersNightScreenshots, 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

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: 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_.

License

MIT License · Copyright (c) 2026 exploraX

// HOW IT'S BUILT

// FILES

33 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/cinematic-film/SKILL.md9.4 KB132766ea60a8upstream ↗
    ---
    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.
    
  • skills/cinematic-film/scripts/build_narration.py4.9 KB302c6f068558upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/build_sfx.py12 KBc0b1b474b1cfupstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/burn_captions.py5.6 KB897ab120e679upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/captions.py7.7 KBbe7cdc7da088upstream ↗
    """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()
    
  • skills/cinematic-film/scripts/check_setup.py3.2 KBbaa1581dc37aupstream ↗
    #!/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)
    
  • skills/cinematic-film/scripts/engine.py73 KBa8ac47ef4ea2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/cinematic-film/scripts/fetch_commons.py8.6 KB8082cc6ce2d0upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/get_fonts.py2.2 KB0542cb0544fdupstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/make_beats.py4.0 KB04533b60bb91upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/make_map.py8.9 KB37018d6be0acupstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/mix_soundtrack.py5.0 KB824c866d17e8upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/new_project.py1.9 KBa36a7b402753upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/prep_assets.py9.5 KBd7890a8d9bf3upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/render.py7.5 KB6299e6a5883dupstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/split_takes.py7.8 KB5524b8396535upstream ↗
    #!/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()
    
  • skills/cinematic-film/scripts/tts_say.py4.1 KB8889f8b876caupstream ↗
    #!/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()
    
  • skills/cinematic-film/references/archive.md5.0 KB7ef0682e80f7upstream ↗
    # 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")
    ```
    
  • skills/cinematic-film/references/film.md7.9 KB2664bef59a44upstream ↗
    # 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.
    
  • skills/cinematic-film/references/performance.md2.8 KB91a63ff37775upstream ↗
    # 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.
    
  • skills/cinematic-film/references/sound.md2.6 KB7fa19334739cupstream ↗
    # 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".
    
  • skills/cinematic-film/references/story.md4.9 KB5c2c57e89c59upstream ↗
    # 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
    
  • skills/cinematic-film/references/voice.md2.9 KBdf399a437daaupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/cinematic-film/assets/template/map.json323 B2717bc21a03bupstream ↗
    {
     "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]}
     }]
    }
    
  • skills/cinematic-film/assets/template/photos.json59 B5d16949966e2upstream ↗
    {
     "grade": "natural",
     "photos": [],
     "recreations": []
    }
    
  • skills/cinematic-film/assets/template/scene.py2.5 KBb451083b2990upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/cinematic-film/assets/template/script.json1.5 KB60062efbe1b4upstream ↗
    {
     "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."]
    }
    
  • skills/cinematic-film/assets/wright-flyer/map.json716 B42cedf2b30e5upstream ↗
    {
     "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]}
     }]
    }
    
  • skills/cinematic-film/assets/wright-flyer/photos.json1.6 KBd7a01b822894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/cinematic-film/assets/wright-flyer/scene.py11 KB087172bd4891upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/cinematic-film/assets/wright-flyer/script.json6.5 KBc81e98fb8c5fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/cinematic-film/agents/openai.yaml158 B207b58ccb0b5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/moh4696-cinematic-skill-skills-cinematic-film.md

// REPO STATS

272 stars
0 open issues
Last commit: 6d ago