
cinecode
Animated films from an idea or a screenplay, made entirely by code: storyboard, rigs, sets, camera, score, mix and render, with skills that build what the engine lacks.
- GitHub stars
- 31
Install
/plugin install cinecode@cinecodeRun it inside Claude Code after adding the marketplace with /plugin marketplace add zakariaf/cinecode.
Contents
Discovered from sourceSkills 4
Build an effect
Built-in effects first: fx beats (dust, splash, sparkle, leaves, rain, fireflies, motes, mist; the last five also as scene overlays), the built-in custom beats and overlays (skydot, sunglow, starstream, eyepiece, lightpulse, orbit, sizerow, moonlets, debris: what each draws and its params in ${CLAUDE_SKILL_DIR}/../cinecode/references/effects.md), the built-in sounds, rim light, grades (CINECODE/docs/storyboard.md). When none is the thing, build it, or start from the built-in that is nearest (CINECODE/engine/effects/<name>.mjs) under a name of your own: an effect named like a built-in replaces it for the whole film (check lists the file with "replaces the built-in …"). An effect file exports any of overlays, custom (beats) and sounds, the same shapes as custom.mjs (CINECODE/docs/effects.md), and is loaded with the film.
- One film:
films/<slug>/effects/<name>.mjs(or, for a few lines, the film'scustom.mjs). Several films:cinecode/effects/<name>.mjsat the project root. - CINECODE below is cinecode's own folder,
${CLAUDE_SKILL_DIR}/../../... The CLI iscinecode(if it isn't on the PATH:node ${CLAUDE_SKILL_DIR}/../../../bin/cinecode.mjs). - Models:
${CLAUDE_SKILL_DIR}/starter.mjs(a glow that follows an actor, a dust puff, a bell),CINECODE/engine/effects/(the built-ins:debris.mjsandmoonlets.mjsdraw at depth,eyepiece.mjsover the whole frame for one shot),CINECODE/films/storm-shelter/custom.mjs(a storm sky with bolts at marks, a storm grade, spray, thunder, a rain bed),CINECODE/films/glim/custom.mjs(a firefly glow, a swarm keyed to a mark),CINECODE/films/kite/custom.mjs(a kite on a string from a hand),CINECODE/films/seventy-six-summers/fx/(comet, mist, reflections).
Steps
mkdir -p films/<slug>/effects && cp ${CLAUDE_SKILL_DIR}/starter.mjs films/<slug>/effects/<name>.mjs; keep what you need, rename.- Use it in
film.json: a scene's"overlays": [{ "name": "storm", "params": { … } }](add"shots": ["2.1", "2.3"]to draw only in those shots of the scene), a beat{ "do": "custom", "name": "puff", "who": "pip", "dur": 0.8 }, a sound{ "sfx": "thunder", "params": { "near": 1 } }. Key timed events to{ "mark": "bolt" }beats (api.marks.bolt), not seconds. Mind a custom beat's time (below):"hold": falseand"scope": "shot". cinecode check films/<slug>(listseffects/<name>.mjs; an unknown overlay name is an error, an unknown custom beat a warning).- Gate:
cinecode verify-effect films/<slug> <name…>until every check passes, then Read the review strip (films/<slug>/out/verify/effects-<names>.jpg: three frames from the first use of each drawn effect: a beat's span, an overlay's scene, or only the shots its"shots"names, or, for one that keeps to some shots by itself, the shots it draws in). Required before you move on. - Strip every shot that uses it (
cinecode sheet films/<slug> --shots=2.1@0.2,2.1@0.5,2.1@0.8 --cols=3) and look: it never covers a face or makes a speaker unreadable, and it reads at the shot's size.
The contract
- Overlay:
{ layer, draw(ctx, api) }, drawn every frame of the scenes that list it (or of the shots their"shots"names). Custom beat:{ layer, sfx: [{ at, name, gain }], draw(ctx, u, api) },u0 → 1 across the beat'sdur. Sound:({ seed, dur, params }) => Float32Array, 48 kHz mono, peak well under 1 (the mixer doesn't normalise). - A custom beat's time. It takes its
durin the beat timeline: laid"with": "prev"over a line, a beat longer than the line holds the next line back."hold": falseplays its wholedurwithout holding the next beat or the shot. It also lasts its wholeduron into the next shots of the scene (and a dissolve's fading picture):warnings.mjswarns,"scope": "shot"ends it at its cut (its latersfxdropped too),"scope": "scene"keeps it on and says so. The engine readsscopeandholdfrom the beat: don't use them as params of your own. - Layers, in drawing order:
sky(screen px, after the sky, before land),back(world, before props and actors),depth(world, at each piece's depth: hands pieces to the depth sort, below),world(world, after the actors; the default),front(world, after the front layers),grade(screen px, after the time-of-day grade: emitted light goes here or night greys it),screen(screen px, last before titles). - api:
t(film s),st(s into the scene),su(scene 0..1),lt(s into the shot),params,seed,marks,W,H,cam(zoom),set(props,horizon,lens),shot,actor(id)(x,y,z,s,face,box,head,mouth,st; null off stage),anchor(name),toScreen([x, y]),toWorld([sx, sy]),project([x, y, z]),item([x, y, z], draw),silhouette(ctx, actor). World layers already have the camera transform; size screen-space things byapi.cam.zoom× the actor'ss. - Depth. An actor with a
z(off the stage) is drawn at its depth's scale:api.project([x, y, z])→[sx, sy, s, a](its screen point, screen px per world px there, its pass of the lens: 1 until 0.04 × the lens from it, 0 by 0.01 × it, don't draw; a near piece off the axis has left the frame by then, so never fade it yourself mid-frame) places anything at its depth on any layer. To be hidden by what is nearer and hide what is farther, draw on thedepthlayer throughapi.item([x, y, z], (ctx, P) => …)(ctx in the world transform of that depth,P = { x, y, s, z, a }); anything drawn straight on ctx there lands behind the set. For planets:globeOf(api, who)andatDepth(ctx, api, z)fromcinecode/paint/planets(CINECODE/docs/effects.md, "Depth"). - Deterministic and stateless: workers draw frames out of order, so a frame may depend only on
api.t/u, the params,api.seedand a seededrng()(cinecode/lib) whose numbers are all drawn up front, before anycontinue. NoMath.random(),Date.now(), or variables kept between calls.
The house style
Soft gouache and ink, not neon: inked edges (ink, line) on solid things, soft radial gradients with screen or lighter for light, colours from the scene's palette, a hint of wobble. Light comes from the upper left. Particles are few and varied in size; motion eases. Match the grade: warm light on grade at dusk and night, cold multiply for storms (storm-light).
The gate: cinecode verify-effect <film> [names…]
| check | fails when | fix |
|---|---|---|
| layer | not one of the layers | pick the layer from the list (the gate's own list doesn't have depth yet, so an effect on it fails this check alone: judge the rest from the other checks and the strip) |
| order | a frame differs when frames are drawn in another order | stateless: no variables kept between calls; draw every random number first |
| draws | the effect changes nothing in its frames | check the times it is active, api.actor returning null, alpha 0, drawing off screen |
| sound | not a non-empty Float32Array; not finite; peak ≥ 1; two calls differ | scale it down; seed the noise from seed |
Without names it checks every effect the film uses, built-in ones too. An effect the film doesn't use yet is only shape-checked: use it in a shot first. An overlay kept to some shots is looked at in those shots. Then look at the strip: is it where the story needs it, at a size that reads, under (or over) the right things, and does it leave faces and captions clear?
Build a set kit
Use this after the cinecode skill decided no built-in kit (meadow, forest, stream, wayside, valley, hill, village, space) can be the place with its params and time of day. A kit is one file that default-exports (params) => set, built with makeSet; cinecode registers it under its file name and stages, routes, frames and lints on it exactly like a built-in.
- One film:
films/<slug>/kits/<name>.mjs("sets": { "harbour": { "kit": "<name>" } }). Several films:cinecode/kits/<name>.mjsat the project root. - Give it a name of its own: a kit named like a built-in one replaces it for the whole film (
checklists the file with "replaces the built-in kit …"). - CINECODE below is cinecode's own folder,
${CLAUDE_SKILL_DIR}/../../... The CLI iscinecode(if it isn't on the PATH:node ${CLAUDE_SKILL_DIR}/../../../bin/cinecode.mjs).
Steps
- Read a model:
CINECODE/engine/set/kits/meadow.mjs(open ground, a hollow tree, a pond),forest.mjs(a path between trunks),stream.mjs(water and stepping stones),hill.mjs(a ridge set: ground as a line),village.mjs(buildings, lights at dusk),space.mjs(no ground: a time of its own, no shadows, perch anchors to hold things in the air). Draw it:cinecode set-sheet meadow -o out/set-meadow.jpg. - Start from the starter, which passes the gate:
mkdir -p films/<slug>/kits && cp ${CLAUDE_SKILL_DIR}/starter.mjs films/<slug>/kits/<name>.mjs, setidto the name, run the gate once. - Lay out the staging first (anchors, walk region, props with solid footprints, water), from the screenplay: where everyone stands, sits, perches and walks. Then paint the layers back to front, and decide its times (below).
- Gate:
cinecode verify-kit films/<slug>/kits/<name>.mjsuntil every check passes, then Read both review images it writes toout/verify/beside the folder that holds the kit:films/<slug>/out/verify/for a film's kit,cinecode/out/verify/for a project's (the gate prints both paths). Both are required before the kit goes intofilm.json. - Use it, then sheet every shot on it: framing, actors' sizes at each anchor, nothing floating.
The contract (makeSet from cinecode/set; DESIGN.md §3, CINECODE/docs/sets.md "Adding a kit")
| field | meaning |
|---|---|
id, W, H, refX, refY | name, nominal size, the reference camera centre for parallax |
area | the painted world { x0, x1, y0, y1 }: at least 3200 × 1800 (the widest view a camera shows) |
view | where the camera centre may go (inside area) |
horizon, laneY, baseS, lane(x) | perspective: scale = baseS × (y − horizon) / (laneY − horizon), 0 at the horizon; lane(x) is the main lane (x:1500 stands there). A ridge set gives walk.ground(x) and walk.band instead (the hill). |
layers | [{ k, paint(ctx, r, S, E), front, outline, anim, shade }]: k the parallax (0.4 far … 1 the ground … 1.3 front: true, over the actors). paint draws once in world pixels inside E with the seeded r(), then it is cached; cover all of E horizontally or the camera sees a gap. anim(ctx, t) for moving parts (water shimmer). |
props | [{ id, x, y, base, solid: { rx, ry }, bounds, paint(ctx, r), ground(ctx), anchors }]: things sorted in depth with the actors by y (trees, rocks, houses). solid is the footprint actors route around; bounds must contain everything paint draws (the gate flags a clipped sprite); anchors on a prop are its surfaces. |
anchors | at least 4: { x, y, type }, type ground (default; must be walkable), surface (a top: prop, depth), perch (branch: { pts, w0, w1 }, at), hollow (clip polygon), view (far landmarks). face, s, surface (footstep sound), z (a depth off the stage: an actor sent there takes it) optional. Name them for the story (dock_end, cave_mouth): letters, digits, _, ., -, and never "left" or "right" (the sides enter and exit use) or a form check reads as a place (x:…, near:…): the gate fails those. |
walk | region (the walkable polygon: keep it below the horizon band), water (polygons; wading and stones), stones (prop ids), paths ([{ poly, surface }]) |
ambience | { day, night } from meadow-day, meadow-night, forest-day, forest-night, stream, village-day, village-night, wind-hill |
skies, times | Earth's eight painted skies by default (skies.<one of them> repaints it). A kit not under Earth's sky declares its own times: { name: { grade, sun, haze } } with a painter skies.<name>: (ctx, rnd, w, h) => … for each: those are then its only times, the first its default (space.mjs: times: { space: { grade: 'neutral', sun: null } }). grade 'neutral' (default), an Earth time's name or { sl, mul, vig, con }; sun null (default: no cast shadows), an Earth time's name or { len, a }; haze [r, g, b] or none. { night: {} } among them keeps Earth's night. A sky with no declared light, or a scene time the kit doesn't have, is a check error. |
groundShadows | false when there is no ground to shade (space): no figure, flier or prop throws a shadow |
lens | world px from a depth-0 camera to the stage (default 2304): how much a depth z scales things |
field | { density }: a near field of specks at every depth that a camera moving through depth streams past, seen only while it moves through depth (1 the usual count; leave it out for none). For a kit with no painted ground (space); expose it as a param (space's dust) and check that param yourself, so a bad value names it |
| optional | light, defaultSky, surface, sampleRoute |
Paint only with the r() you are given (never Math.random()), and from the params: two builds must paint the same picture.
The house style
The helpers in cinecode/paint/paint (CINECODE/engine/paint/): ridge, hazeBand, paper (far hills, haze, paper grain), treeline, bigTree, bush, boulder, stump, meadowFloor, blades, fern, reeds (nature and scenery), paintWater, waterShimmer, lilyPad, steppingStone (water), contactShadow under every prop; cottages, fences, wells, benches, lanterns, cobbles and glow in cinecode/paint/structures. Light from the upper left (LEFT), haze toward the horizon, gouache dabs (clump), an ink outline on mid layers, a ground layer that fills to the bottom of E, and foreground grass (front: true) for depth. Build new structures from the same pieces (inked polygons with cel-style shade) rather than flat fills.
The gate: cinecode verify-kit <file>
| check | fails when | fix |
|---|---|---|
| contract | not a function, or not a makeSet set | export default function name(params = {}) { return makeSet({ … }); } |
| anchors | fewer than 4; a name check reads as something else (left, right, x:…, near:…); a ground anchor off the walk region or in a solid or water; a scale outside 0.2–4; a hollow's contact outside its clip; a perch off its branch | rename it, move it, widen walk.region, check horizon/laneY |
| world | a missing sky (one of Earth's eight, for a kit without times); a sky with no light (a painter under a name of its own that times doesn't declare); an unknown ambience; area smaller than 3200 × 1800; view outside area; scale not growing toward the viewer; the lane outside the picture; a layer that leaves a gap at some camera | widen area/E coverage; paint each layer across its whole extent |
| walk | a collider's centre walkable; open water walkable; a route between two ground anchors blocked or crossing a solid | separate solids, leave lanes between props |
| paint | a time of day leaves over 10% of a preview frame unpainted: under each time's grade (Earth's eight, or the kit's own), at least 90% of the pixels must be more than near-black (r + g + b > 24); a prop clipped by its bounds; two builds differ | fill to the edges; paint a night or space sky deep blue, not black; widen bounds; use r() |
Then look at <name>.jpg (the set at its widest view with the walk region, water, solid footprints, anchors with a hare-height tick at each one's scale, and a sample route) and <name>-times.jpg (dawn to night, or the kit's own times, each under its grade). Fix what doesn't read: an anchor whose tick is too tall or too short for the place, a prop floating or sunk, a flat or empty area the camera will frame, a night where nothing can be seen.
Build a rig
Use this after the cinecode skill's "reuse, adapt, build" step decided that nothing built in reads as the thing (the built-in rigs include things too: planet for any planet, moon or the Sun, telescope; inventory.mjs cast lists them all). A rig is one file that default-exports the rig; cinecode registers it by its kind when the film loads, and from then on it is cast, staged, framed, lit, linted and sheeted exactly like a built-in.
- One film:
films/<slug>/rigs/<kind>.mjs. Several films of the project:cinecode/rigs/<kind>.mjsat the project root. - Give it a
kindof its own: one named like a built-in rig replaces that rig for the whole film (checklists the file with "replaces the built-in rig …"). - CINECODE below is cinecode's own folder,
${CLAUDE_SKILL_DIR}/../../... The CLI iscinecode(if it isn't on the PATH:node ${CLAUDE_SKILL_DIR}/../../../bin/cinecode.mjs).
Steps
- Pick a model to learn from and read it: four legs
CINECODE/engine/cast/fox.mjs(orbadger,deer:leg(),quadFeet()), a birdsongbird.mjsorowl.mjs(perching,flygait), something tinymouse.mjsorbeetle.mjs, a propCINECODE/films/strawberry-race/rigs/strawberry.mjs(a pose per state,expressions: ['neutral']) orCINECODE/engine/cast/telescope.mjs; a thing whose sizes come from its paramsCINECODE/engine/cast/planet.mjs(sizes(params),upright,noShadow). Draw it:cinecode cast-sheet fox -o out/fox.jpgand look. - Start from the starter, which passes the gate:
mkdir -p films/<slug>/rigs && cp ${CLAUDE_SKILL_DIR}/starter.mjs films/<slug>/rigs/<kind>.mjs. Setkind(the file name),label, then run the gate once to see a pass. - Reshape it pose by pose: body and head shapes, limbs, the face, colours as
params(so the cast can recolour it), thenheight/headHeight/widthto match the drawing. Rerun the gate after each big change. - Gate:
cinecode verify-rig films/<slug>/rigs/<kind>.mjsuntil every check passes, then Read both review images it writes toout/verify/beside the folder that holds the rig:films/<slug>/out/verify/for a film's rig,cinecode/out/verify/for a project's (the gate prints both paths). Fix what looks wrong (below). Both are required before the rig goes intofilm.json. - Use it:
"cast": { "rex": { "rig": "<kind>", "params": { … } } }.cinecode checklistsrigs/<kind>.mjs; then sheet and strip the shots with it (cinecode sheet films/<slug> --shots=1.3@0.2,1.3@0.5,1.3@0.8 --cols=3).
The contract
makeRig (import { makeRig } from 'cinecode/rig') turns a paint() into the full rig (DESIGN.md §2, CINECODE/docs/cast.md "Adding a rig"):
| field | meaning |
|---|---|
kind, label | registry key (= file name) and display name |
height, headHeight, width | units at scale 1: standing height (framing, lint), head size (close-ups), body length (routing footprint). The gate holds height to the drawn stand pose within 12%. For scale: mouse 17.5, frog 19, hedgehog 24, songbird 24, fox 83, hare 103, deer 143. |
params | colours and look switches; the cast's params override them. Use them in paint as o.P.<name>. |
poses | named pose objects, numbers only, stand required; give sit, sleep, alert (the sit/sleep/wake beats use them), lie, perch when it can. Every pose carries every key (a key one pose lacks pops when a gesture blends into it). |
gaits, speeds, stride, steps | walk (and run; fly for a flier) as phase => pose, phase 0..1 per stride, looping (phase 0 = phase 1). speeds (units per second) and stride (units per cycle) at scale 1. footAt() plants a foot and sweeps it back one stride so feet don't slide; feet(pose) → [[x, y, planted], …] and steps (phases where a foot lands) make footsteps and the slide check work. |
gestures | gest(dur, [[u, deltas], …]) (starts and ends on its base pose), or { dur, keys, at(u, base) }; jumpAt() for jumps (sets lift). |
expressions | default all eleven (neutral, happy, laugh, sad, surprised, angry, sleepy, smug, worried, scared, determined); ['neutral'] for a thing with no face (no talk or blink checks; the camera crops into it with a zoom above 1, and lint's face rules skip it). |
flies, perch | a flier needs flies: true and a fly gait (it can hover with "height"); perch: true stands on branches. |
sizes(params) | → { height, headHeight, width, speeds, stride } when they depend on the params (a body preset, an age); the engine frames, routes and lints each actor by it. Without it a size param scales them. |
upright | true: the drawing stays vertical on a slope; false: it pitches with the ground. Default: animals pitch, the human and the fliers stay upright. |
noShadow, shadowW, shadowA | true: no contact shadow under it; that shadow's half-width in units (default width / 2); its opacity (default 0.26). The sun's cast shadow is the frame's (none at a perch, at night, or on a set without ground). |
faceless | true / false: whether it has a face, when its expressions alone would say otherwise (default: no face when only neutral). |
| optional | mount(pose, params) (a riding point), lookTime (s a look takes), feet(pose) and steps (see gaits), hangPoses (poses whose legs hang below the ground on purpose), breathPeriod. |
paint(T, pose, F, o) draws in local units: origin = the contact point (feet), +x forward (mirrored for face: -1 by the engine, never by you), ground y = 0, up is negative y. T records the bounds of everything filled or stroked: draw only through T. F is the face: F.eye (open, wide, happy), F.lid, F.tilt, F.cheek, F.browY, F.browT, F.smile, F.open (mouth, follows the voice), F.round, F.look (−1..1 head turn), F.pitch (−1..1 head up/down; pitchPose() applies it), F.breath. o.P params, o.t scene time (ear and tail sway), and set o.out.head = T.map(x, y) and o.out.mouth = T.map(x, y): the camera composes close-ups on the head, captions avoid it, the mouth is where talking happens.
Deterministic and stateless: no Math.random(), Date.now() or variables changed between calls; seeded detail comes from rng(seed) (cinecode/lib) drawn the same way every call.
The house style
cel(T, pts, colour, shade, ink, seed)(cinecode/style): fill, one hard lavender shadow on the side away from the upper-left light, a wobbly ink outline. Every body part goes through it.line(T, pts, width, { seed, color, taper }): inked strokes (legs of small animals, whiskers, toes, antennae).eye(T, x, y, rx, ry, F.eye, iris, F.look * k, F.lid, F.tilt, { cheek: F.cheek })andbrow(T, x, y, w, F.browY, F.browT, colour): the storybook eye and brow every rig uses.- Shapes:
ell(cx, cy, rx, ry, seed, wobble)andrpoly(pts, r, { seed })(cinecode/lib) for hand-drawn ovals and rounded polygons;smoothPts(T, pts)(cinecode/style) to round a polygon into a curve;tube(),spine()(tails),leg(),ik2(),quadFeet()incinecode/rig. - Colour: muted gouache, ink
#2a2130; the far legs and far wing drawn first and darker (darken(col, 0.8)); a lighter belly or muzzle patch without ink (cel(…, ink 0)); big readable eyes on small animals. - Compare with the house rigs in the line-up image: same ink weight, same shading, a size that makes sense next to the hare, the child and the mouse.
The gate: cinecode verify-rig <file>
| check | fails when | fix |
|---|---|---|
| contract | a field is missing or not a number | the table above |
| size | height far from the drawn stand pose; stand not touching the ground; lift ignored | measure -bbox(stand)[1]; the contact point is the feet |
| bounds | pixels painted outside the bounds draw() reports (both facings) | draw through T only; a raw ctx or drawImage isn't tracked |
| ground | a pose, gait phase or gesture frame goes below y = 0 | raise the body (by), clamp feet with footAt; legs that hang on purpose go in hangPoses |
| flip | face −1 isn't the mirror of face 1 | never branch on o.face in paint |
| deterministic | the same state draws different pixels | no Math.random(), Date.now() or state between calls |
| face | an expression, talk or blink changes nothing in the head | use every F field: lids and brows for moods, F.open for the mouth, F.lid for blinks |
| motion | a gait doesn't loop, a planted foot slides, a gesture doesn't start and end on its pose | footAt with the gait's own stride; every key in every pose; gest() keys [0, null] … [1, null] |
Then look at <kind>.jpg (every pose, four phases of each gait, gesture keys, every expression, talk and blink, with bounds, head and mouth marked) and <kind>-lineup.jpg (both facings beside hare, human and mouse at one scale). Fix anything that doesn't read: a face that looks the same in two moods, a walk whose legs cross wrongly, a head anchor off the head, the wrong size beside the others.
cinecode: from an idea to a finished film
cinecode turns films/<slug>/film.json (a storyboard) into a film: painted sets, animated characters, camera, captions, voices, music, sound effects and a mix. Everything is drawn and synthesized by code except the voices (Gemini TTS, cached in films/<slug>/voices/). This is the method that made films/seventy-six-summers (3:45, 56 shots, 56 voiced lines) good. Follow it in order.
Where you work. A film is films/<slug>/ under the folder Claude Code was started in (the person's project; in the cinecode repository, its own films/). Run every command from that folder. Pieces several films share go in cinecode/{rigs,kits,effects}/ at the project root (step 6).
The CLI is cinecode <command> films/<slug> (--help on any command). As a Claude Code plugin, cinecode is on the PATH; if it isn't (inside the cinecode repository without the plugin), run node ${CLAUDE_SKILL_DIR}/../../../bin/cinecode.mjs in its place. The first time on a machine run cinecode setup: it installs the drawing library and checks Node, ffmpeg and the Gemini key; fix what it reports as FAIL before anything else.
cinecode's own folder (engine, docs, worked examples) is ${CLAUDE_SKILL_DIR}/../../.., written CINECODE below; this skill's folder is ${CLAUDE_SKILL_DIR} (the references write it as <skill>). Where things are:
CINECODE/docs/storyboard.md: every storyboard field (CINECODE/DESIGN.md§2–4 and §9–11 are the contracts).CINECODE/docs/effects.md: custom effects;docs/cast.mdanddocs/sets.md: adding a rig or a kit.${CLAUDE_SKILL_DIR}/references/:storyboard-quick.md(a valid skeleton, a space scene, beats, camera, every valid name),cast.md(every rig: speeds, poses, gestures, params, what rigs can't do, substitutes for missing animals),sets.md(every kit: anchors with x, y and scale, props' extents, times; hollows),effects.md(the built-in effects: what each draws, its params, its layer),voices.md(the 30 voices, writing tones, fixing takes),review.md(rendering stills and strips, the per-frame checklist, lint rules, reviewer lenses).${CLAUDE_SKILL_DIR}/scripts/:inventory.mjs(live rig, kit and effect tables),warnings.mjs(warningscheckandplandon't print),timeline.mjs(every beat's start and end, marks, moves that run past a cut),takes.mjs(what each voice take says),levels.mjs(the score's level per shot, and quiet holes in it).CINECODE/films/seventy-six-summers/is the worked example:screenplay.md,film.json,custom.mjs+fx/.CINECODE/films/_test/custom.mjsis a small custom-effects example,CINECODE/films/strawberry-race/rigs/strawberry.mjsa film-local rig (a prop).- The build skills, for anything the engine doesn't have:
build-rig(a character or a prop),build-kit(a place),build-effect(weather, light, a swarm, a sound). Each ends in a gate:cinecode verify-rig,verify-kit,verify-effect.
Ground rules:
- Work inside
films/<slug>/. Never edit cinecode'sengine/for a film: what the engine lacks is built in the film's folder (or the project'scinecode/), step 6. If you find an engine bug, work around it and tell the person. - Never stop at "not available". A character, place, prop or effect the engine lacks is reused, adapted or built (step 1, "What isn't there"), never cut or refused for that reason alone.
- Deterministic: no
Math.random()orDate.now()in film code; userng(seed)fromcinecode/libwithapi.seed. - Look at every image you render with the Read tool. A film is done when the frames are good, not when the commands pass.
- One checkpoint: after step 1, show the person the logline, cast (rig + voice), sets and length in a few lines and ask for a go-ahead or changes. First check that someone can answer: run
cinecode setup --checkand read itssessionrow. If it says nobody can answer (claude -por the SDK), or you are a subagent or part of a workflow, or they said "just make it", skip the checkpoint: decide yourself, work to the end, and list your choices in the report. Never end a run on a question nobody will read. After the checkpoint, work to the end without asking. - 2D or 3D. cinecode draws a film one of two ways: 2D (the flat storybook picture this skill describes, with the full library of rigs and kits) or 3D (lit, with a camera that moves in depth;
"format": { "engine": "3d" }, and its own, much smaller library). If the request says which, use it. If it doesn't, ask at the checkpoint, with what each would mean for this film (what 3D would have to build). When nobody can answer, use 2D. For a 3D film,CINECODE/docs/scene3d.mdreplaces this skill's rig, kit and staging references; story, lines, voices, captions, music, sound, review and the report stay as written here.
1. The story
cinecode new <slug> --title="The Title" creates films/<slug>/ with a screenplay.md template (keep its sections), a starter film.json and a custom.mjs. The starter is a complete example film (Pip, a hare and an owl in the meadow, and a glints custom beat in shot 1.6); only the title is yours. Replace its logline, voices, cast, sets and scenes, and delete from custom.mjs whatever you don't use (with the beats that name it).
Write screenplay.md before any JSON. From a one-sentence idea, invent the rest: who wants what, what stands in the way, the turn, a last image. From a full screenplay, adapt it: map every character to a rig and every place to a kit (reusing, adapting or building, below), and list what you adapted or built for the report. The screenplay has, in this order:
- Logline: one sentence, who wants what and what's in the way. A theme line if there is one, and the lines or images that come back later with a new meaning.
- Characters: for each, the rig, look (
paramscolours, castscale), voice (a Gemini voice + 2–3 delivery adjectives), personality in a line. - Locations and times: kit + time of day per scene, the anchors you will use, what happens there, and the length target (below) as seconds per scene.
- Music plan: a mood per scene; optionally a motif (
note:beatstokens) and where it is stated in full. - Screenplay: scenes with starting places, then shots, each with an id
<scene>.<shot>(2.2= scene 2, shot 2;film.jsonuses the same ids), size, move, action and lines;(pad 0.6 s)for a pause:
**2.2** medium on Fidget and Pebble, static. Fidget sits on the stump; Pebble plods toward it.
FIDGET (bright): "Morning, boulder! Where you headed?"
(pad 0.6 s)
PEBBLE (slow): "The standing stone. Tonight."
- Ending and final image: the last image and how it answers the opening.
Characters: start from the existing rigs (live list: node ${CLAUDE_SKILL_DIR}/scripts/inventory.mjs cast; drawn: cinecode cast-sheet <kinds> -o out/cast.jpg). Walk speeds are units/s; see references/cast.md for on-screen times.
human: a storybook person, child / teen / adult / elder, many clothes and hair params; walk 92; sits on the ground or a seat, crouches, kneels, points, waves, claps, jumps for joy.hare: tall and fast (hop 190, run 640); ears, stretch, yawn, skid, slump; waves, points, thumps, shrugs.tortoise: very slow (walk 15, run 34); scuted shell, neck that hides; carries a rider on its shell (on:<id>); slow looks (1 s); moss, star marking, wet shell.fox: russet; walk, trot, gallop (run 500); points, bows, sniffs.owl: front-facing; perches and flies; hoots, flaps; a dozingone-eyeexpression.squirrel: big tail (tail0.4–1.8); perches on branches; quick runner (165); shushes, nibbles, drops an acorn;flopover a shell.songbird: perches, hops, flies; sings.mouse: tiny; scurries, sits up, gasps, cheers.hedgehog: tiny and slow; curls into a ball, bristles.badger: low and wide; waddles; digs, cheers.deer: the tallest animal; grazes, flicks ears, stamps; optional antlers.frog: sits, croaks (throat sac), catches with its tongue; small hops (walk,hop: 26, slow) or big leaps (run: 92).beetle: tiny, six-legged, slow.butterfly: flies and glides, perches with folded wings.planet: a planet, moon or the Sun (body: saturn, jupiter, earth, mars, venus, mercury, uranus, neptune, moon, titan, pluto, charon, sun); no face, holds at a perch anchor, throws no shadow. For space films (below).telescope: a prop on a tripod; a child stands at its eyepiece (references/cast.md).
What isn't there: reuse, adapt, build. For every character, prop, place and effect the story needs, in this order:
- Reuse a rig, kit or built-in effect that is the thing (a fox is the fox; a lantern-lit cottage is the village at dusk; a view through a telescope is the
eyepiecebeat). The library is more than the lists here:inventory.mjsprints every rig, kit and effect, andreferences/effects.mdsays what each built-in effect draws (skydot,sunglow,starstream,eyepiece,lightpulse,lightbeam,orbit,sizerow,moonlets,debris,ringfield). - Adapt one:
params(coat colours, antlers, tail size, clothes), castscale, a kit's time of day, plus at most a small overlay that follows the actor, and only when the result reads as the thing at the film's framing. A firefly is a dark-winged, yellow-bodied butterfly atscale0.6 with a glow overlay (CINECODE/films/glim/). The substitutes inreferences/cast.mdare this step: a fallback when they truly read, not the answer. - Build it when an adaptation wouldn't read (a wolf in a close-up, a crow that must be a crow, a kite the story turns on, a strawberry that splits, a harbour, a thunderstorm): a new rig (
build-rigskill; props on the ground or in the air are rigs too), a new kit (build-kit) or an effect (build-effect). Each lives infilms/<slug>/rigs|kits|effects/and loads like a built-in once its gate passes (cinecode verify-rig|verify-kit|verify-effect) and you have looked at its review images.
Decide at the checkpoint what you will build: a rig or a kit costs real time, an adaptation that reads is better spent effort. Never tell the person a thing isn't available; say what you reused, adapted or built.
A colouring-book look (line art, black outlines on white, no colour) is built in: "format": { "style": "lineart" } draws every character, prop, set, effect and title card as ink on white paper (CINECODE/docs/storyboard.md, "Line art"). Don't post-process the rendered video into lines.
Places: start from the existing kits (anchors in references/sets.md; drawn with anchors: cinecode set-sheet <kit> -o out/set-<kit>.jpg); a place none of them can be is built (build-kit). Times: Earth's eight (dawn, morning, noon, afternoon, golden, sunset, twilight, night) on every kit but space, which has one of its own, space; a time a kit doesn't have is a check error.
meadow: forest edge; the owl's hollow tree with a low branch (perches), an old stump (stump_top), rocks, a lily pond.forest: a dirt path between big trunks; an oak with a mouse-sized den (den, a hollow), a fallen log (log_top), a boulder; extra wide.stream: a brook across the path; four stepping stones (stone_1–stone_4), a frog rock, banks; wading is possible.wayside: a great tree with a long low branch over a nap spot, a signpost at a fork, three perches.valley: a lookout knoll above a wide valley; farview_*landmarks for journeys seen from afar.hill: a ridge set; a long slope rising left to right to a crest with a standing stone (stone_top) and a hawthorn.village: a cottage with door and windows, picket fence and gate, well, bench (bench_seat), lantern, lane, a tree with perches; windows and lantern light up at dusk.space: a starfield with the Milky Way; no ground, no sun, no shadows; perch anchors (centre,west,east,far*,near*) to hold planets; a near field of dust at every depth that a camera moving through depth streams past, seen only while it moves (dustparam: 0 or false none, 2 twice as much).
Write for what the rigs can do. Every view is side-on. Characters don't touch or hug, and hold only what you draw for them: tell the story with positions, walks, looks, poses, gestures, expressions, timing and the camera. Keep lines short (most under ten words), one emotion per line. Every scene needs a turn you can see with the sound off.
Length target. plan's total includes the title cards (shot 1.1 starts after the opening card), so count them. Shots average 4 s. A card needs 3 s to be read: the title is fully inked 1.4 s in and dissolves into shot 1.1 over the last second; the end card's line is full from 1.3 s until it fades to black over the last 1.2 s.
| film | scenes | shots | lines | title cards |
|---|---|---|---|---|
| about 30 s | 1 | 5–6 | 3–5 | 3 s each (24 s of shots) |
| 1 minute | 1–2 | 12–14 | 10–14 | 4 s each (the starter's) |
| 3 minutes | 6–10 | 40–50 | 40–50 | 4 s each |
A line lasts about words / 2.6 + 0.3 s until it is voiced, but a slow or gruff voice or a line of two sentences can take twice that ("The last strawberry. Mine!" came back at 3.8 s, with a 0.6 s pause), so aim a short film about 10% under its target. A shot lasts as long as its slowest thing: the action, or the lines plus their pauses.
2. The storyboard (film.json)
Look fields up in CINECODE/docs/storyboard.md; the short version with every valid name is references/storyboard-quick.md. Translate the screenplay shot by shot: scene actors (where everyone starts), then each shot's camera and beats. Put the intent in note fields; reviewers read them.
Staging rules (the ones that cost the most rework):
- Everyone stands on something real. Use anchor names from the kit, or
x:…,y:…points you have seen inside the walk region on the set sheet (x:alone is the main lane). Branches (perchanchors) only for rigs that can perch. Riding is"to": "on:<actor>"on a hop or place. A hollow (den) is entered by jumping up into it and shows its occupant against a dark hole: read the notes inreferences/sets.mdbefore staging one. - Fliers hover with
"height". Afly,enterorplacewith"height": N(units at the set's scale; a songbird is 24 tall) ends with the flier flapping N units above its place, over water too, where it can talk and gesture:{ "do": "fly", "who": "glim", "to": "near:tilly", "height": 30 }. Its next move is a flight (a walk flies down and lands). A hoverer can't sit, lie, sleep or take a pose until it lands (acheckerror). Withoutheighta flight ends on the ground, a surface, a perch, a hollow oron:<actor>. - Plan distances from rig speeds. On screen an actor covers
speed × sworld px/s, s = the set's scale there × castscale(about 1.3 on most lanes, up to 2 near the camera). A human crosses 300 px in about 2.5 s; a tortoise needs about 15 s. Each stepping stone is a jump of 0.7–1.5 s (a small rig the longest) whatever its gait orspeed. Write each shot's target position from the previous one: positions carry over from shot to shot inside a scene. - Moves end standing. A walk, run, hop or fly ends in
stand(or perched, on a perch) unless it gives"pose": a held pose (hold-hand-out,sit) is dropped by any move. A pose that starts while its actor still moves (a move carried over from the shot before too) is replaced by the move's end pose, and a gesture laid over a move keeps the gait's legs (ajumpor astampdoesn't show): put them after the move.timeline.mjs(step 3) marks both. - Entrances in wide shots.
enterfrom a side starts outside every view the shot may show: in an establishing shot (or a push-in from one) that is the edge of the set, so the actor arrives only at the end. There, start it as a scene actor just inside the frame andrun. - Lead room and the axis. Face characters the way they move or talk. In a conversation keep A on the left facing right and B on the right facing left for the whole scene.
near:<actor>stops beside someone, clear of its head and tail (and of a hoverer's wings), and turns to face them. - Expressions. A line's
exprthat is a mood (happy,worried) holds until a beat changes it; a reaction (surprised,laugh,laughing,scared) passes 0.4 s after the line. Set the next mood with anemotewhen the scene turns. On the hedgehog, mouse and badgersadreads as a scowl (useworried, orsleepyfor weary), and the badger and fox bare their teeth when they talk: see the faces inreferences/cast.mdbefore a close-up. - Listeners turn to the speaker (the body too, if the speaker is behind) and go back to their own look after the line: a look that must read goes before or after someone else's line, not under it.
- One action per beat. Walk, then talk;
"with": "prev"only when two things truly happen together (a gesture on its line). Pauses are"after": 0.6, never "…" in the text. - Tones are short delivery adjectives: "dry", "soft, tender", "squeaky, disbelieving". The voices-block tone (2–3 words) is joined with every line's tone, and only the last three descriptors are sent (
references/voices.md). - Vary the framing. Establish a place wide, then go in; don't cut between two near-identical framings; a two-shot only when the two are close together at a similar height (see the pitfalls).
- Part of a subject.
zoommultiplies the size's zoom, but while a subject has a face the frame keeps its head in frame and above the captions (anoffsetcan't push it out). When no subject has a face (a planet, a prop) a zoom above 1 crops into the framing and theoffsetmoves it as given:"zoom": 1.6, "offset": [-0.3, 0.1]frames part of Saturn."focus": [0.9, 0.5]puts that point of the subjects' box (or"head", or a point"x:…,y:…") at the frame's centre, for any subject;"on": ["x:1840,y:886"]frames a point of the set. No hidden stand-in needed.
Space and depth
Films in space, or with things in front of and behind each other, are supported. To start one:
- Set and cast. The
spacekit,"time": "space","ambience": "none"; aplanetactor per world ("params": { "body": "saturn" }) at a perch anchor, sized with castscale(true relative sizes: multiply by the ratio of radii,references/cast.md). An Earth side (a child at atelescopeon thehillat night, askydotoverlay where it points) cuts to it. - Depth. A scene actor's
"z"(world px; positive farther, negative nearer) draws it smaller or bigger and behind or in front of everything on the stage: a moon at"z": 2400is about half size and drawn behind Saturn.place,walk,run,hop,fly,enter,exitandsettake a"z"too. Depth is for things in the air and sets with no painted ground: a figure standing on the hill stays at z 0 (warnings.mjssays when one doesn't). - The camera moves through depth.
"z"(its depth at the shot's start, positive toward the stage) and"zTo"(at the move's end, overmoveAt/moveDur) dolly in or out, the near things growing faster than the far, and the space kit's near field streams past while the camera moves (flight, not a zoom; a still shot, a pan or a lens zoom shows none of it); both stay under 1728 (3/4 of the lens). Apush-intoa size with azToholds its subject while the rest changes (a dolly-zoom). A planet has no face, so no lead room: it is centred across the frame. A dolly in grows everything out from the frame's centre, so it composes its subjects near enough the centre to stay in frame at its end (one that ends bigger than the frame is flown at dead centre); for a planet held dead centre throughout, add"focus": [0.5, 0.5]. Things the camera comes up to stay whole until they are almost at the lens (don'tfadeone out by hand as the camera passes it: it turns see-through mid-frame); one off the camera's axis slides out of the frame first, leaving it at about its width × 960 / its offset from the axis (screen px at 1080p; offset in world px from the camera's centre): to have a moon swing past big, stage it within about 20 px of the axis (Titan at scale 0.11), with azin front of the stage that the dolly passes (zTobeyondz+ 2304). - Effects. The built-in space effects above;
debrisdrifts at many depths, so a dolly flies through it;ringfieldlays ice and rock in a planet's rings for a flight into them;lightbeambrings sunlight to a planet as a soft shaft. Frame parts of a planet withzoomandfocus(above). - Lint takes a crop as meant: on a shot with a
focus, azoomabove 1 on subjects with no face, or a dolly (zTo),subject-sizeonly warns of a subject too small (a dolly is judged at its first frame) andedge-cutreports no sliver of the subject (in a dolly, of anyone). Another warning you keep goes on the shot as"lint": { "allow": [rules], "note": "why" };cinecode lintcounts the kept ones, andcheckrejects a malformed block. - Cut, don't dissolve, into a full-frame effect. A scene in another set dissolves in by default, and the last scene shows through the eyepiece's black: give it
"transition": "cut".
references/storyboard-quick.md has a valid space scene to start from.
3. Check and plan
cinecode check films/<slug> # validate; lists every problem with its path
cinecode plan films/<slug> # shot list: start, length, first line (~ = estimated, not voiced yet)
node ${CLAUDE_SKILL_DIR}/scripts/warnings.mjs films/<slug> # misspelled fields `check` ignores; two-shots staged too far apart; an actor dwarfed by an anchor or a bigger actor in "on"; blocked routes; a custom beat drawn on past its shot; your piece replacing a built-in
node ${CLAUDE_SKILL_DIR}/scripts/timeline.mjs films/<slug> 1.4 1.5 # each beat's start and end, moves that run on past a cut, mark times; "!" = a pose or gesture lost under a move
Fix until check is valid and warnings.mjs is clean or every warning is understood. "no warnings" says nothing about framing: only lint and the contact sheets do. Compare plan's total with the length target.
4. Voices
voice needs GEMINI_API_KEY in the environment. Never print it: no echo $GEMINI_API_KEY, env, printenv or set, and never write it into a file or a command line. Check it with:
[ -n "$GEMINI_API_KEY" ] && echo "key is set" || echo "key is missing"
If it's missing, ask the person to export it in their shell profile and restart the session; don't ask them to paste it into the chat. Then:
cinecode voice films/<slug> # only new or changed lines go to the network
node ${CLAUDE_SKILL_DIR}/scripts/takes.mjs films/<slug> --all # every take: what was asked, what was heard, its length and pauses
Each new take is transcribed and checked: a take that reads its tone aloud is retried with less of it (up to 3 tries, the best kept), and voice marks lines still above 20% word error with !. That isn't everything, so read every take in takes.mjs --all (without --all it prints only flagged and non-verbal lines; details in references/voices.md):
- Fix every flagged take,
TONE-CUTincluded (kept after its tone was cut: the right words, maybe a flat delivery), and anything wrong it doesn't flag: an added "Huh,", a clipped first word, a laugh heard as a word. Change the tone word (a new take), or deletevoices/<id>.wavandvoices/<id>.jsonfor a fresh one, then runvoiceagain. - Made-up names get misheard by the checker ("Glim" → "Clem") and use up tries, and so does a one-word line ("Ours." came back as "hours" and "Walrus" three times; "Ours, then." passed): give a lone word some context, and read what was heard before you redo a take.
- Old takes that no line uses any more are listed with an
rmcommand; deleting them is safe. - You can't hear the takes: name the lines the film hangs on (id and file) for the person to listen to.
Voice before the contact-sheet loop: shot lengths come from the real takes, so staging timed on estimates moves. Run plan (and timeline.mjs for shots with moves) again afterwards.
5. The contact-sheet loop
This is where the film gets good. Commands and the full checklist are in references/review.md.
cinecode sheet films/<slug> # middle frame of every shot → films/<slug>/out/sheet.jpg
cinecode sheet films/<slug> --shots=3.1,3.2,3.3,3.4 --cols=2 --tile=640 -o films/<slug>/out/s03.jpg # one scene, bigger
cinecode sheet films/<slug> --shots=3.3 --debug -o films/<slug>/out/s03d.jpg # boxes, contacts, caption box
cinecode sheet films/<slug> --shots=3.3@0.1,3.3@0.3,3.3@0.5,3.3@0.7,3.3@0.9 --cols=5 --tile=384 -o films/<slug>/out/strip.jpg
--shots= takes shot ids (with @u for a point 0..1 in the shot); --t= takes seconds, so --t=2.2 is not shot 2.2.
- Render a scene's sheet and look at every tile. List what's wrong, as
shot: problem → fix: framing (size, lead room, headroom, cut-off heads), floating (feet above their own shadow when nobody is jumping, a shadow on nothing), hidden subjects (behind a trunk, a front layer, mist, an overlay, the dark), eyes (shut, looking at the wrong person), overlap (two characters drawn into each other), captions (over a face, too long, in a band someone walks into), continuity across cuts. - Middle frames hide motion. For every shot with a walk, hop, entrance, camera move, gesture or pose change, render a strip of 4–6 frames and check the whole move: where it starts, that it ends where the next shot begins, that nobody slides or pops.
- Fix
film.json, re-render only those shots and their neighbours, look again. Repeat until a whole pass finds nothing. cinecode lint films/<slug> --step=0.5(about a minute for 3½ minutes of film, seconds for a short; run long ones in the background). Readfilms/<slug>/out/lint.jpg. Fix every error and every warning that is a real problem; a warning you keep on purpose gets"lint": { "allow": ["<rule>"], "note": "why" }on its shot (lint then lists it as kept, in green onlint.jpg, with no fix tried) and goes in the report.edge-cut,tangentandhalomessages end with a camera change or staging that lint tried on the recompiled film: apply it and look again. Asubject-sizewarning thatzoomdoesn't clear means the frame holds something besides the subject: see the lint table inreferences/review.md. One exception: a static shot is framed for the pose its subject holds for most of the shot, so one who sits or lies down early (or stands up late) overfills it while taller: keep the taller pose for most of the shot, cut on the change, or"zoom": 0.8(lint may still warn: keep it and say so).
6. Building what the engine lacks
Small, film-only drawing (a glow on a reskinned rig, a comet, mist that parts, a reflection, a new sound) goes in films/<slug>/custom.mjs: it may export custom (custom beats, { "do": "custom", "name": … }), overlays (whole-scene drawings on a layer: sky, back, depth, world, front, grade, screen), sounds, rigs and kits (CINECODE/docs/effects.md). A piece worth its own file goes in the film's folders, loaded like a built-in:
films/<slug>/rigs/<kind>.mjs export default makeRig({ kind: '<kind>', … }) build-rig skill
films/<slug>/kits/<name>.mjs export default (params) => makeSet({ … }) build-kit skill ("kit": "<name>")
films/<slug>/effects/<name>.mjs export const overlays / custom / sounds build-effect skill
cinecode/rigs|kits|effects/ the same, shared by every film in the project
Film code imports the engine as cinecode/<name> wherever the film lives: cinecode/lib (rng, noise, ink, ell, rpoly, clump…), cinecode/style (cel, line, eye, brow…), cinecode/rig (makeRig, footAt, gest…), cinecode/set (makeSet), cinecode/paint/<name> (scenery, nature, water, structures, planets…), cinecode/engine/<path> for anything else. Never a relative path into cinecode's folder.
- Use the build skill: it has the contract, a starter that passes its gate, and the house-style helpers. The gate is not optional:
cinecode verify-rig <file>/verify-kit <file>/verify-effect films/<slug> <name>must pass, and you must look at every review image it writes, before the piece goes intofilm.json. Fix and rerun until both are good. - Match the style: inked wobbly outlines, gouache dabs, cel shading, light from the upper left. Emitted light (a lamp, a comet, a firefly) goes on the
gradelayer, after the night grade, or it turns grey. - To follow an actor, draw at
api.toScreenofapi.actor(id).box(null while it is off stage), sized byapi.cam.zoom; for one off the stage (itsz), atapi.project([x, y, a.z]), sized by the scale it returns. A prop's painted extent isapi.set.props(the hawthorn's crown has no anchor), the horizonapi.set.horizon, a human's hand inCINECODE/docs/effects.md. - A sound under a whole scene (rain): a custom sound that takes its length from
params,{ "sfx": "rain-bed", "params": { "dur": 30 } }with no beatdur. The beat then takes no time and the sound plays on across the cuts (a beatdurwould hold the shot that long). - A custom beat takes its
durin the timeline: laid"with": "prev"over a line, a long one holds the next line back."hold": falselets the next beats go on while it plays. It also lasts its wholedurinto the next shots (awarnings.mjswarning):"scope": "shot"ends it at its cut. A scene overlay can keep to some shots:"shots": ["2.1", "2.4"]. - Name your pieces apart from the built-in ones: a rig, kit or effect named like one replaces it for the whole film (
checklists the file with "replaces the built-in …"). - Deterministic and stateless: draw only from
api.t,api.seed, the params and a seededrng(), never from state kept between calls (workers draw frames out of order). Key timed events offmarkbeats (api.marks), not hard-coded seconds. - The built-in
firefliesfield is spread thinly over the whole world (3–6 ×nper 420 px square): a shot of a small rig shows few even atn: 6. For a swarm, write an overlay around an anchor, keyed to amark. - Run
check(it lists the extension files it loaded), then a strip across the shots that use the piece. Make sure it never covers a character's face or makes a speaker unreadable.
7. Music, mix, animatic, render
cinecode music films/<slug> # the score alone → out/music.wav
cinecode mix films/<slug> # score + dialogue + sfx + ambience, ducked and mastered to −16 LUFS → out/mix.wav
cinecode animatic films/<slug> # 12 fps, half size, with sound → out/animatic.mp4 (mixes first if stale)
Music comes from scene and shot music cues (moods, stings, a score motif); footsteps and hops are added automatically. You can't hear it, so check what you can measure: plan counts the music cues, mix prints the loudness, and node ${CLAUDE_SKILL_DIR}/scripts/levels.mjs films/<slug> prints the score's level per shot in 0.5 s windows and flags quiet holes under a cue (a mean over a shot hides them). Two causes so far: a mood change on a cut without "downbeat": true can open with a second or more of near-silence (give it downbeat), and the last cue's final chord lands about 3 s before the end and dies under a short end card (give it "hold": true). A quiet scene should still read quieter than a chase. Whether the moods fit is for the person to judge in the animatic; say so in the report. Then look at the whole film at once:
d=$(ffprobe -v error -show_entries format=duration -of csv=p=0 films/<slug>/out/animatic.mp4)
ffmpeg -v error -y -i films/<slug>/out/animatic.mp4 -vf "fps=32/$d,scale=320:-1,tile=8x4" -frames:v 1 films/<slug>/out/overview.jpg
Read the overview (32 frames spread over the film, whatever its length): the journey, the light and the screen direction should read at a glance. Ask the person to watch the animatic: they can hear it, and it's the cheapest moment for notes. Then render:
cinecode render films/<slug> # → out/<slug>.mp4 + out/<slug>.srt (in the background: see below)
cinecode render films/<slug> --from=1:20 --to=1:40 # a full-quality sequence → out/<slug>-80s.mp4
render voices any missing lines first (with the key) and stops without it. It takes tens of minutes for a few minutes of film (every core works). Run it once, in the background, and wait for it: use your shell tool's background option (Claude Code's Bash run_in_background) and wait for the notice that it finished; don't detach it with nohup … & (the shell returns at once and the render looks done while it is still running), and don't poll with long sleeps. Never start a second render of the same film while one runs: cinecode refuses it (another render of … is already running); wait for the first, or stop it. Its last line (verify) is an ffprobe check: size, codec, frame count, fps, duration, audio, subtitles. Grab a few frames from the final file with ffmpeg -ss <t> and look at them.
8. The report to the person
- The file:
films/<slug>/out/<slug>.mp4(and the.srt), its length, resolution, and how to re-render (cinecode render films/<slug>). - What's in it: the logline, the scenes in a line each, the cast (rig and voice), anything custom you built.
- The choices you made without asking (when you skipped the checkpoint), and what you changed from their idea or screenplay and why (substitute rigs or places, cut lines).
- Known issues, honestly: lint warnings you kept, takes you couldn't get right (ids), shots you'd still improve, the lines and the music they should listen to.
- Don't commit, push or publish unless they ask.
Pitfalls we hit
- Tone words read aloud.
[quick, bright, cheeky, sincere, low, slow] Don't stop…came back as the six adjectives; "wondering" alone came back as "Mm, wondering.";[warm, gentle, soft]was read aloud (with "tender" for "soft" it took). Long lists, nouns ("grumpy old badger") and stage directions ("voice catching") get spoken, and no adjective is safe every time (references/voices.mdlists the ones seen). Two or three short adjectives, the line's own delivery last; when one is read, change the word. - Takes that pass but are wrong. A take can say the direction instead of the line, insert "Huh," or "Um", turn a laugh into "Oh", or (
TONE-CUT) keep the words with no direction at all. Never trust a take you haven't read the transcript of (takes.mjs --all). - The slow tortoise. 15 units/s is about 20–30 world px/s: a few hundred pixels is a whole scene. Move it a small step per shot, cut instead of walking (a
placebetween shots or scenes hides the distance), and let the quick characters carry the action while it plods.speedmultipliers above about 1.5 make a slow rig scurry. - Loose two-shots. A static shot frames everything its subjects do, so two characters far apart (or one walking across) make both tiny.
warnings.mjscatches two actors staged too far apart and a small actor dwarfed by a big one or by an anchor ("on": ["tilly", "den"]); lint'ssubject-sizecatches the rest. Stage them within a body length or two, cut between singles, or push in with"to"as they meet. - Branches and ground in one shot. An owl on a branch and a squirrel on the grass: the frame spans both heights and each is tiny (Seventy-Six Summers 2.4: 19% of their single size). Cut between them, or bring the one on the ground up to a perch or a surface near the other.
- Gestures in close-ups. A static or handheld
closeshot eases out to keep a held gesture's head in frame (the mouse'sgaspsits her up), then back. Extreme close-ups and moving shots don't follow: there use the pose of the same name ({ "do": "pose", "who": "tilly", "pose": "gasp", "dur": 0.3 }). - Captions over faces. Burned-in captions sit in a band at the bottom, or the top when that covers fewer heads over the whole chunk (a chunk never changes band; a sound caption during a line takes the other band). The camera keeps framed heads above the bottom band, but a character missing from
on, a small one low in the frame, or the action at someone's feet can end up under it (lint'scaption-facechecks speakers only). Fix withon,offset, a tighter size, or staging further up the ground. A sound caption crosses a cut only for its sfxdur(at least 0.6 s on screen): give a long sound adur. - Mist, overlays and night hiding characters. Height fog, front bands and night grades swallowed the old woman coming down the hill; a mouse in a dark den reads only by its rim light. Check every night and mist shot at full size (
--frame); add a scenerimlight, keep key figures in front of the band, or turn the overlay's params down. - Shot ids are not times.
--t=2.2renders second 2.2. Use--shots=2.2. - Two editors, one file. Only one agent edits
film.json; reviewers report.
Big films: subagents and workflows
For a film past ~15 shots, split the work. Storyboard scene by scene (a subagent per scene is fine when each gets the screenplay, the staging rules above and its scene's start positions, and returns its scene JSON for you to merge). For review, run parallel reviewers on the same sheets, each with one lens (staging and continuity, camera and framing, acting and eyelines, light and atmosphere, captions and timing, story, sound), reporting shot | problem | fix | severity and editing nothing; each renders into its own file names (out/review-<lens>-s03.jpg) so they don't overwrite each other. With a workflow tool, fan out one reviewer per lens (or per scene × lens), then a single fixer. Merge, fix, re-render, and run a second round with fresh reviewers on what changed. Prompts and lenses are in references/review.md.
Sponsors
Details
- Marketplace
- zakariaf/cinecode
- Category
- Community