Cinematic Skill

---
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