⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
cinematic-film
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.
// RATINGS
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
| Kind | Look | Images |
|---|---|---|
| Documentary, history, true crime | Cork evidence wall, slate | Archive photos and documents, black and white |
| Product launch, brand or founder story | Studio, charcoal | Your own product shots and photos, in colour |
| Science, engineering, how it works | Blueprint, paper | Diagrams, archive or AI stills |
| Tech, space, trailers | Night | Screenshots, renders, AI stills |
The items work on every look:
- photos and torn newspaper clippings
- typeset documents with real quotes
- clean cards
- big distressed type and rolling counters
- stamps, pen circles and highlighter swipes
- red string between prints
- maps of any country, with filled regions, routes and markers
A spotlight follows the camera so each line has one hero.
How it works
- 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.
- Voice. A free scratch voice (macOS
sayor 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. - 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.mdis written for you. - Scene. A short Python file places items on the voice's timing (
doc.W(line, "word")) and keys the camera. - Review. The agent renders stills and contact strips of every move and checks them for known mistakes before showing you a draft.
- 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-assetsskill 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 textskills/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