Moh4696/cinematic-skill

Overview

Cinematic Skill packages a workflow plus Python rendering code so a coding agent can produce narrated short films — documentaries, product stories, science explainers, trailers — without generative video. Every frame is drawn by code with Skia in Python over a single designed "world", and one continuous camera move is timed to the narration. Because the output is deterministic, re-rendering is cheap and swapping in a new voice re-times the film automatically. It targets people using Claude Code, Codex, Cursor, Gemini CLI or OpenCode who want scripted, repeatable motion graphics rather than AI-generated footage.

Install

The recommended path uses the npx skills CLI (Node 22.20+), which wires the skill into the agents it detects:

npx skills add Moh4696/cinematic-skill

The README also documents a Claude Code plugin install, a Codex plugin install and a Gemini CLI extension, plus a shell installer if Node is unavailable. After installing the skill, install the runtime dependencies and ensure ffmpeg is on PATH:

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

check_setup.py verifies the environment and reports missing pieces. Start a new agent session afterwards so the skill is loaded.

Try the bundled example

From a clone of the repository, the README walks through generating the 92-second Wright brothers documentary:

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

This downloads public-domain photos from Wikimedia Commons (with their licences), synthesizes a scratch voice, prepares assets and renders a draft MP4. The README reports that the 92-second film renders at 1080p in about 6 minutes on a 16 GB laptop.

Workflow

The agent moves through six stages: research and script (with a beat table and chronology check for your approval), scratch voice timing, image sourcing with recorded licences, scene setup where items are keyed to spoken words via doc.W(line, "word"), a still/contact-strip review, and finally sound effects, mixing and captions. It pauses for approval after the beat table, the visual look, and a 30-second draft. The README lists four visual looks (cork evidence wall, studio, blueprint, night) covering photo-and-text, maps, cards, counters and annotations.

Constraints

Node 22.20+ is needed for the npx path, Python with skia-python, numpy and pillow for rendering, and ffmpeg on PATH. The scratch voice relies on macOS say or espeak-ng; a final voice can be any TTS or a recorded person, supplied one section at a time. Non-free images are refused and a credits.md is generated. The bundled example uses public-domain photos from Wikimedia Commons. The project is MIT licensed.

HotRepo's take

On 2026-11-10 the repository entered HotRepo's new-project list: a Python-language snapshot recorded 111 stars and 6 forks, with 7 stars gained in a roughly one-hour window starting at 16:15 UTC. Star sampling that afternoon shows 108 to 111 within half an hour. These are early, single-snapshot numbers rather than a trend, and no GitHub daily rank or Hacker News discussion is recorded. The notable technical fact is the pairing of an agent skill with deterministic Skia rendering and voice-driven timing — a concrete mechanism that supports re-rendering and re-timing, which is the project's own stated advantage.

Project source and documentation