{"slug":"blender","title":"blender","summary":"3D scenes, character acting and product shots from a shot spec, rendered in Blender, as a finished film, as clips for any other build (moviepy, a video job, an editor), or as elements of a Remotion video (transparent characters over a scene, a Remotion render on a 3D laptop, phon","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-11-14T19:10:39.383188Z","repo":{"url":"https://github.com/digitalsamba/claude-code-video-toolkit","stars":2563,"forks":450,"license":"MIT","updatedAt":"2026-11-14T19:04:25Z"},"bodyHtml":"<hr>\n<h2>name: blender\ndescription: 3D scenes, character acting and product shots from a shot spec, rendered in Blender, as a finished film, as clips for any other build (moviepy, a video job, an editor), or as elements of a Remotion video (transparent characters over a scene, a Remotion render on a 3D laptop, phone or floating card that the camera pulls back from, an imported 3D model on a studio stage). A rigged cartoon cast described in JSON (build, face, hair, clothes, a seed), sets, shots by type, acting beats in seconds or on narration words, every camera checked by geometry, sound placed on the motion. Use when a video needs a consistent directable character (parody, explainer gag, reaction shot), a 3D reveal or element in a Remotion video, a device or product shot of an app or a model, or exact acting timing that AI video clips can't hold. Triggers include Blender, 3D, character animation, rigged character, cast, shot spec, acting, camera angles, transparent clip, alpha, pull out from the screen, phone mockup, device mockup, product shot, turntable, orbit, glTF, GLB, BlenderClip.</h2>\n<h1>Blender shot specs</h1>\n<p><code>tools/blender_render.py</code> turns a JSON <strong>shot spec</strong> into 3D footage: a whole film, one clip per shot for another\nbuild, or both from the same spec. The spec says <em>what happens</em>; <code>lib/blender/</code>\ndecides <em>where things go</em>: cameras are placed by shot type round their subject and checked (in frame, nothing in\nthe way) before they are kept; acting is verbs (<code>expression</code>, <code>pose</code>, <code>shake_head</code>) rather than keyframes; every\nmoment worth a sound is exported with its time, so the sound is on the motion by construction.</p>\n<p>Four worked examples:</p>\n<ul>\n<li><code>examples/blender-product-shot/spec.json</code>: a studio stage with no character: a picture on a floating card and\non a phone, and an imported model, with <code>reveal</code>, <code>orbit</code> and <code>product</code> shots.</li>\n<li><code>examples/blender-disk-panic/spec.json</code>: a film from one spec (22.5 s, 8 shots, 37 beats).</li>\n<li><code>examples/blender-in-remotion/</code>: Blender clips inside a Remotion video. A terminal scene cuts to itself on a 3D\nlaptop and the camera pulls back; then a transparent character acts beside the list of beats it is acting.</li>\n<li><code>examples/blender-kitchen/</code>: a fitted character (experimental). Mara, a generated model seated on the rig with\n<code>fit</code>, walks in with a mug, sits, puts it down, opens the laptop and drinks. Its README says what the spec\nworks round.</li>\n</ul>\n<pre><code>uv run tools/blender_render.py doctor                                         # Blender found? s/frame on this machine\nuv run tools/blender_render.py check  examples/blender-disk-panic/spec.json   # ~5 s: checks + stills + contact sheet\nuv run tools/blender_render.py render examples/blender-disk-panic/spec.json   # ~15 min (M4, EEVEE, 1080p)\nuv run tools/blender_render.py render spec.json --res 640x360                 # a draft to judge motion, 0.35 s/frame\nuv run tools/blender_render.py render spec.json --engine cycles               # physical light; ~10x slower (17 s/frame)\nuv run tools/blender_render.py render spec.json --clips --alpha --to projects/my-video/public/blender\nuv run tools/blender_render.py open   spec.json                               # the built scene in Blender\n</code></pre>\n<p><strong>Tell the person how long it will take before you start.</strong> A fitted character acting in a room renders at about\n2.2 s a frame at 1080p (45 s of film is close to an hour, and is rendered more than once), so a film of this kind\nis two to three hours of unattended work a session, and takes a few sessions with the person's notes between\nthem. End each session with the film, its checks, a decisions file and a prompt for the next session that leaves\na gap for their notes: <code>docs/blender.md</code>, \"A film over several sessions\".</p>\n<p>Output in <code>&lt;spec dir&gt;/out/</code> (<code>out/&lt;name&gt;/</code> for a spec not called <code>spec.json</code>): <code>checks.json</code>, <code>contact_sheet.png</code>, <code>stills/</code>, <code>events.json</code>, <code>scene.blend</code> (open it\nin Blender and scrub), and after <code>render</code> the <code>.mp4</code> named after the spec's folder, or <code>clips/</code> with <code>--clips</code>.</p>\n<p>Requires Blender 4.2 or later. It has been run on 5.3 (macOS) and 4.2 LTS (Linux, in a container); Windows is\nsupported by the code and not yet run. Optional component: nothing else in the toolkit needs it.\nInstall, timings and troubleshooting: <code>docs/blender.md</code>.</p>\n<h2>What the render is for</h2>\n<p>These are uses of one spec format, not separate modes: the same spec renders as a film and as clips, and a video\ncan mix them (a product shot between two Remotion scenes, a character film with a Remotion title card).</p>\n<table>\n<thead>\n<tr>\n<th>The video is</th>\n<th>Do</th>\n<th>Then</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>A 3D short on its own (a gag, a parody shot)</td>\n<td><code>render spec.json</code></td>\n<td><code>qc.py --render</code>, add music with <code>addmusic.py</code></td>\n</tr>\n<tr>\n<td>A Remotion video with a 3D character in some scenes</td>\n<td><code>render --clips --alpha --to &lt;project&gt;/public/blender</code>, set kind <code>desk</code></td>\n<td><code>&lt;BlenderClip&gt;</code> over the scene's field</td>\n</tr>\n<tr>\n<td>A Remotion video that turns out to be on a screen in a room</td>\n<td>render the scene with Remotion, name it in <code>set.screen.video</code>, a <code>pull_out</code> shot, <code>render --clips</code></td>\n<td>hard cut from the flat scene to the clip</td>\n</tr>\n<tr>\n<td>An app, a UI or a product shown as an object</td>\n<td>set kind <code>studio</code> with a <code>phone</code>, <code>card</code> or <code>model</code> prop; <code>reveal</code>, <code>orbit</code>, <code>product</code> shots</td>\n<td>a clip between scenes, or <code>--alpha</code> over the scene's field</td>\n</tr>\n<tr>\n<td>A moviepy build, a video job or an edit in another tool that wants a 3D shot</td>\n<td><code>render --clips</code> (a picture-only <code>.mp4</code> per shot, its effects as a <code>.wav</code>; <code>--prores</code> for editors)</td>\n<td><code>VideoFileClip</code>, a <code>file</code> scene in <code>video_job.py</code>, <code>cutdown.py</code> for 9:16</td>\n</tr>\n<tr>\n<td>Narrated, with acting on the words</td>\n<td>a <code>voice</code> block and <code>\"at\": \"cue:...\"</code></td>\n<td>the spec follows the voice when it is re-timed</td>\n</tr>\n</tbody>\n</table>\n<p>For Remotion, set the spec's <code>\"fps\": 30</code> (the composition's): a clip plays frame for frame.</p>\n<p><strong>When to suggest it.</strong> While planning any video, if <code>blender_render.py doctor --no-bench</code> exits 0, offer a\nBlender shot where one fits: a character reacting, a reveal, a product or device shot. If Blender isn't\ninstalled, don't propose it unless the user asks for 3D; then say what it needs (<code>docs/blender.md</code>).</p>\n<h2>The loop (do this, in this order)</h2>\n<ol>\n<li><strong>Write the spec</strong> from the brief or narration (below: <em>From a brief to beats</em>).</li>\n<li><strong><code>check</code></strong> and read the report. Every shot prints PASS/FAIL, its exposure, and any camera fix the solver made\n(\"swung +24 deg: nominal had view blocked by dev_hood\"). Exit 1 on a failure, 2 on a spec error.</li>\n<li><strong>Look at <code>contact_sheet.png</code></strong> (read the PNG). Geometry can't judge everything: a hand over the key text, an\nexpression that reads wrong, a beat landing in the wrong shot. Green bar = passed checks, red = failed.</li>\n<li><strong>Fix in the spec, not in Blender</strong>: change a shot's <code>type</code>, <code>az</code>, <code>dist</code>, <code>dur</code>, or a beat's <code>at</code>. If the\nsolver had to move a camera, consider writing its fix into the spec (<code>\"az\": ...</code>) so the intent is explicit.</li>\n<li>Repeat 2–4 until it passes and reads right, then <strong><code>render</code></strong>. Check the result with\n<code>uv run tools/contact_sheet.py out/&lt;name&gt;.mp4</code> (cuts are detected), and <code>uv run tools/qc.py</code> for loudness.</li>\n</ol>\n<p><code>check</code> builds at the film's own shape (the spec's <code>resolution</code> scaled down), so a 9:16 spec is solved and judged\nin 9:16. Never hand-edit <code>scene.blend</code> as the source of truth; it is rebuilt from the spec every run.</p>\n<h2>Spec format</h2>\n<pre><code>{\n  \"title\": \"Disk Panic\", \"fps\": 24, \"resolution\": \"1920x1080\", \"engine\": \"eevee\",\n  \"look\": {\"exposure\": -0.9, \"look\": \"AgX - Punchy\"},\n  \"set\":  {\"kind\": \"desk_room\", \"palette\": {...}, \"screen\": {...}},\n  \"cast\": [{\"id\": \"dev\", \"kind\": \"clay_person\", \"colors\": {\"top\": \"#F26B1F\"}}],\n  \"shots\": [{\"id\": \"S1_wide\", \"dur\": 3.0, \"type\": \"wide\"}, ...],\n  \"beats\": [{\"at\": \"S1_wide+1.6\", \"do\": \"blink\"}, ...],\n  \"score\": [{\"from\": 0, \"to\": \"S2_alert+0.5\", \"mood\": \"calm\"}, ...]\n}\n</code></pre>\n<p>Also at the top level: <code>\"transparent\": true</code> (the same as <code>--alpha</code>) and <code>\"voice\"</code> (below), and <code>\"clock\"</code> (seconds): where\nthis spec starts on a longer film's timeline, so clips made from several specs breathe in step and join without a\njump. Start and end each such clip in the same pose, looking at the same thing.</p>\n<p><strong>Acting takes the same time at any <code>fps</code>.</strong> A blink, a typing rhythm and a head shake are written in seconds\ninside the rig, so a 24 fps film and a 30 fps clip for Remotion act alike.</p>\n<p><strong>A mistake in a spec is named, with the choices.</strong> An unknown face, pose, shot type, subject or cast member is a\nspec error (exit 2) that lists what there is, before anything is rendered.</p>\n<p><strong>Times</strong> are seconds: a number (absolute), or relative to a shot: <code>\"S3\"</code> (its start), <code>\"S3+0.4\"</code>,\n<code>\"S3.end-0.2\"</code>, <code>\"end\"</code>. Write beats relative to the shot they play in, so changing one shot's <code>dur</code> keeps the\nacting in step. Beats are applied in time order; a beat's length is <code>dur</code> (seconds) or <code>until</code> (a time).</p>\n<p><strong>Times from the narration.</strong> List the caption files <code>tools/captions.py</code> wrote, each with where its audio starts,\nand a time can be the moment a word is said:</p>\n<pre><code>\"voice\": [{\"captions\": \"../public/audio/scenes/02_alert.captions.json\", \"at\": \"S2_alert+0.3\"}],\n\"beats\": [{\"at\": \"cue:disk is full\", \"do\": \"alert\"},\n          {\"at\": \"cue:full#2-0.1\", \"do\": \"expression\", \"face\": \"shocked\"}]\n</code></pre>\n<p><code>cue:</code> takes a word or a phrase (case and punctuation ignored), <code>#2</code> for its second occurrence, and an offset. A\nphrase that isn't in the narration is a spec error that prints what the narration does say, as <code>cue()</code> does in\nRemotion. Paths are relative to the spec.</p>\n<h3>Cast</h3>\n<p>A cast member is a description, and every field is a named choice or a hex colour, so an agent can write one\nfrom a sentence (\"a woman in her forties with a grey bob, glasses and a green shirt\") or from a photo:</p>\n<pre><code>{\"id\": \"maya\", \"kind\": \"clay_person\", \"seed\": 12,\n \"body\":    {\"build\": \"slim\", \"skin\": \"brown\"},\n \"face\":    {\"shape\": \"oval\", \"eyes\": \"brown\", \"brows\": \"thin\", \"nose\": \"small\", \"beard\": \"none\"},\n \"hair\":    {\"style\": \"bob\", \"color\": \"grey\"},\n \"clothes\": {\"top\": \"shirt\", \"top_color\": \"#2E7D5B\", \"pants\": \"#252B45\", \"shoes\": \"#F0F0EC\"},\n \"accessories\": [\"glasses\"]}\n</code></pre>\n<table>\n<thead>\n<tr>\n<th>Field</th>\n<th>Choices</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>body.build</code></td>\n<td><code>average</code>, <code>slim</code>, <code>broad</code></td>\n</tr>\n<tr>\n<td><code>body.skin</code></td>\n<td><code>pale</code>, <code>light</code>, <code>tan</code>, <code>brown</code>, <code>dark</code>, <code>deep</code>, or a hex colour</td>\n</tr>\n<tr>\n<td><code>face.shape</code></td>\n<td><code>round</code>, <code>oval</code>, <code>square</code></td>\n</tr>\n<tr>\n<td><code>face.eyes</code></td>\n<td><code>brown</code>, <code>hazel</code>, <code>green</code>, <code>blue</code>, <code>grey</code>, or a hex colour</td>\n</tr>\n<tr>\n<td><code>face.brows</code>, <code>face.nose</code></td>\n<td><code>medium</code>, <code>thin</code>, <code>thick</code>; <code>round</code>, <code>small</code>, <code>long</code></td>\n</tr>\n<tr>\n<td><code>face.beard</code></td>\n<td><code>none</code>, <code>moustache</code>, <code>full</code></td>\n</tr>\n<tr>\n<td><code>hair.style</code></td>\n<td><code>tufts</code>, <code>short</code>, <code>bob</code>, <code>long</code>, <code>bun</code>, <code>curly</code>, <code>bald</code></td>\n</tr>\n<tr>\n<td><code>hair.color</code></td>\n<td><code>black</code>, <code>dark</code>, <code>brown</code>, <code>chestnut</code>, <code>red</code>, <code>blonde</code>, <code>grey</code>, <code>white</code>, or a hex colour</td>\n</tr>\n<tr>\n<td><code>clothes.top</code></td>\n<td><code>hoodie</code>, <code>tee</code>, <code>shirt</code>; <code>top_color</code>, <code>pants</code>, <code>shoes</code> are hex colours</td>\n</tr>\n<tr>\n<td><code>accessories</code></td>\n<td>any of <code>glasses</code>, <code>headphones</code>, <code>earrings</code></td>\n</tr>\n</tbody>\n</table>\n<ul>\n<li><strong>Left out with no <code>seed</code>:</strong> the defaults, which is the character the examples use.</li>\n<li><strong>Left out with a <code>seed</code>:</strong> drawn from the seed. <code>{\"id\": \"extra\", \"seed\": 41}</code> is a whole person, the same one on\nevery machine, and another seed is someone else.</li>\n<li><strong>A standing cast.</strong> Keep a character in its own file and name it: <code>{\"id\": \"lead\", \"from\": \"../../kits/acme/cast/maya.json\", \"clothes\": {\"top_color\": \"#B23A48\"}}</code>. Fields beside <code>from</code> override the\nfile, so one video can change the costume and keep the person. <code>kits/example/cast/maya.json</code> is one.</li>\n<li>From a photo: choose the nearest named choice for each field and sample the hex colours from the picture. The\nresult is a caricature in the toolkit's style, not a likeness.</li>\n<li>Every character has the same rig, so every verb works on every character. Check a new one with a <code>closeup</code> and\na <code>medium</code> shot before writing the beats.</li>\n<li><strong>Where they start.</strong> A cast member sits at the desk unless told otherwise: <code>\"posture\": \"stand\"</code>, <code>\"at\": [x, y]</code>\n(a spot on the floor, metres) and <code>\"facing\"</code> (degrees: 0 faces -Y, toward the desk; positive turns to their own\nleft) put them on their feet anywhere in the room.</li>\n</ul>\n<p><strong>A fitted model (experimental).</strong> <code>\"model\": \"lead.blend\"</code> in a character file swaps the clay body for a\ngenerated 3D character fitted to the rig by <code>lib/blender/fit_model.py</code> (an A-pose mesh from an image-to-3D\nservice, plus a <code>fit.json</code> of its joints and face). The model keeps its own shape: it is bound in its A-pose and\nthe rig poses it, so the same verbs drive it, and the chair, desk and laptop are placed for its legs and arms (seat\nat its knee height, keyboard under its hands). <code>glasses</code> is the one accessory a model takes. Its face is made from its own marks (a lower\nlip, teeth and lids on the model's lip line and eyes, with the cheeks and chin moving for a smile or an open\nmouth), and with a second model of the same character with open hands the fit gives it fingers: hand shapes, a\ngrip on a door handle, hands laid flat on the desk, fingertips on the keys. The fit lays a generated thumb in to\nthe palm (it stands off it on a thick wedge), so the hands type at a typist's slope. The donor's hands are sized to the body's own, the wrist joint\nis put at the cuff, and the desk, the keys and how far apart the hands lie come from the body's measures, so one spec\nruns on characters of different builds (run a spec on two to find a number tuned on one; <code>docs/blender.md</code> has the\nmethod). Head shots aim at a fitted character's own head, whatever its\nproportions. A worked example with an invented character is <code>tests/fixtures/blender-fitted</code>. The steps and their costs are in <code>docs/blender.md</code>.</p>\n<h3>Shots</h3>\n<table>\n<thead>\n<tr>\n<th><code>type</code></th>\n<th>Subject</th>\n<th>Use for</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>wide</code></td>\n<td>character (3/4 front)</td>\n<td>establishing: who, where</td>\n</tr>\n<tr>\n<td><code>front_wide</code></td>\n<td>character (straight on)</td>\n<td>endings, titles above the head</td>\n</tr>\n<tr>\n<td><code>medium</code></td>\n<td>character (waist up)</td>\n<td>gesture: hands on head, shrug</td>\n</tr>\n<tr>\n<td><code>closeup</code></td>\n<td>character (face)</td>\n<td>the reaction; emotion lives here</td>\n</tr>\n<tr>\n<td><code>side</code></td>\n<td>character (profile)</td>\n<td>effort, leaning in, typing hard</td>\n</tr>\n<tr>\n<td><code>over_shoulder</code></td>\n<td><code>\"subject\": \"screen\"</code></td>\n<td>what they see: the alert lands</td>\n</tr>\n<tr>\n<td><code>insert</code></td>\n<td><code>\"subject\": \"screen\"</code></td>\n<td>the detail: a bar draining, a number changing</td>\n</tr>\n<tr>\n<td><code>screen_fill</code></td>\n<td><code>\"subject\": \"screen\"</code></td>\n<td>the screen covers the frame edge to edge, square on</td>\n</tr>\n<tr>\n<td><code>pull_out</code></td>\n<td><code>\"subject\": \"screen\"</code></td>\n<td>starts as <code>screen_fill</code>, holds, then travels back round the shoulder to a side view of the desk</td>\n</tr>\n<tr>\n<td><code>push_in</code></td>\n<td><code>\"subject\": \"screen\"</code></td>\n<td><code>pull_out</code> reversed: ends on the screen, ready to cut to the flat scene</td>\n</tr>\n<tr>\n<td><code>full</code></td>\n<td>character, on their feet</td>\n<td>head to toe; <code>\"follow\": true</code> travels with a walk</td>\n</tr>\n<tr>\n<td><code>feet</code></td>\n<td>character, on their feet</td>\n<td>a low insert on the feet, travelling with them: an entrance before the face</td>\n</tr>\n<tr>\n<td><code>tilt_up</code></td>\n<td>character, on their feet</td>\n<td>starts on the feet, holds, tilts up to the face (<code>hold</code> seconds at each end)</td>\n</tr>\n<tr>\n<td><code>fixed</code></td>\n<td>none: the camera is put where the spec says</td>\n<td><code>\"cam\"</code> and <code>\"aim\"</code> are points in the room, <code>\"lens\"</code> is for the whole frame, <code>\"push\"</code> moves it that share of the way to the aim over the shot. <code>\"window\": [x0, y0, x1, y1]</code> (from the left and the bottom) renders only that share of the frame, by lens shift, so a clip of the window lies exactly where it would in the whole frame: set the spec's <code>resolution</code> to the window's shape</td>\n</tr>\n<tr>\n<td><code>product</code></td>\n<td>a studio prop</td>\n<td>a three-quarter view of the prop, pushing in a little</td>\n</tr>\n<tr>\n<td><code>orbit</code></td>\n<td>a studio prop</td>\n<td>the camera travels round the prop from <code>az</code> to <code>az_to</code></td>\n</tr>\n<tr>\n<td><code>reveal</code></td>\n<td>a studio <code>phone</code> or <code>card</code></td>\n<td>starts on its screen edge to edge, holds, then pulls back to the <code>product</code> view</td>\n</tr>\n</tbody>\n</table>\n<p>Overrides per shot: <code>az</code> (degrees round the subject; 0 = straight in front, + = the subject's left), <code>dist</code> (m),\n<code>h</code> (camera height above the target, m), <code>lens</code> (mm), <code>push</code> (fraction of the distance closed during the shot),\n<code>shake</code> (handheld jitter, m; ~0.012 for urgency), <code>side</code> (<code>\"left\"</code>/<code>\"right\"</code> flips <code>az</code>).</p>\n<p>The solver tries the nominal placement, then pulls back, swings ±12/24/36°, and rises, keeping the first that\npasses at the shot's start, middle and end. What it changed is in the report.</p>\n<p>A character who has left the chair is filmed where they are at the middle of the shot, facing the way they face\nthen, and the solver also tries the far side of them when a wall is in the way. <code>\"follow\": true</code> on any character\nshot makes the camera travel with them. <code>\"reveal\": true</code> is for a shot the subject enters (through a door): it is\njudged on its last frame only. <code>tilt_up</code> is judged where it ends, on the face.</p>\n<p>The three moves take <code>az</code>, <code>elev</code> (degrees) and <code>dist</code> (m) for their far end, <code>hold</code> (seconds on the full screen\nbefore moving, default 0.4) and <code>lens</code>. They are checked at 13 points along the way, also for the lens passing\nwithin 0.3 m of a character (\"lens 0.16 m from dev_body\"), which is what makes a head fill the frame mid-move.\nTheir contact-sheet still is the far end. They pass in 16:9, 9:16 and 1:1.</p>\n<p><code>product</code>, <code>orbit</code> and <code>reveal</code> take their distance from the prop's size, so a 15 cm phone and a 2 m chair fill\nthe frame alike: <code>fill</code> (0 to 1, the share of the frame the prop takes at its widest moment), <code>az</code>, <code>az_to</code>,\n<code>elev</code>, <code>lens</code>, or <code>dist</code> to set the distance by hand. A prop with a screen also reports <code>screen_readable</code>, the\nshare of the shot in which the screen is within 60 degrees of facing the lens; under half is a failure (\"narrow\nthe orbit\").</p>\n<h3>Beats (<code>do</code>)</h3>\n<p>Character (<code>who</code> defaults to the first cast member):</p>\n<table>\n<thead>\n<tr>\n<th>verb</th>\n<th>fields</th>\n<th></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>type</code></td>\n<td><code>speed</code>: <code>calm</code>/<code>frantic</code>, <code>until</code></td>\n<td>hands typing; a click per key in the sound</td>\n</tr>\n<tr>\n<td><code>pose</code></td>\n<td><code>pose</code>, <code>dur</code></td>\n<td><code>type</code>, <code>rest</code>, <code>hands_on_head</code>, <code>arms_up</code>, <code>hands_behind_head</code></td>\n</tr>\n<tr>\n<td><code>expression</code></td>\n<td><code>face</code>, <code>dur</code></td>\n<td><code>neutral</code>, <code>happy</code>, <code>content</code>, <code>shocked</code>, <code>worried</code>, <code>determined</code>, <code>relieved</code>, <code>grin</code></td>\n</tr>\n<tr>\n<td><code>look</code></td>\n<td><code>target</code>, <code>dur</code></td>\n<td><code>screen</code>, <code>down</code>, <code>ahead</code>, <code>camera</code>, <code>up</code>, or degrees of head pitch</td>\n</tr>\n<tr>\n<td><code>lean</code></td>\n<td><code>amount</code>, <code>dur</code></td>\n<td><code>forward</code>, <code>none</code>, <code>back</code>, <code>far_back</code>, <code>recoil</code>, or degrees</td>\n</tr>\n<tr>\n<td><code>head_bob</code> / <code>shake_head</code></td>\n<td><code>until</code></td>\n<td>idle nod to the work / \"no no no\" (whoosh each turn)</td>\n</tr>\n<tr>\n<td><code>gulp</code>, <code>blink</code>, <code>tap</code></td>\n<td></td>\n<td>single moments (<code>blink</code> takes <code>dur</code>, or <code>frames</code> counted at 24 fps)</td>\n</tr>\n<tr>\n<td><code>sweat</code>, <code>tremble</code></td>\n<td><code>until</code></td>\n<td>a drop slides down / pupils jitter</td>\n</tr>\n<tr>\n<td><code>celebrate</code></td>\n<td><code>until</code></td>\n<td>arms up, wiggling</td>\n</tr>\n<tr>\n<td><code>hold_arms</code></td>\n<td></td>\n<td>freeze the arms where they are</td>\n</tr>\n<tr>\n<td><code>stand_up</code> / <code>sit_down</code></td>\n<td><code>dur</code></td>\n<td>off the chair onto their feet (the head lifts, hands to the knees, the chest comes forward over the feet, then up, the arms dropping last) / onto the chair behind them (a look down, the pelvis back before it goes down, hands to the knees, a small settle). Stand them a thigh's length in front of the seat first. About 1.7 s each reads well; under a second looks hurried</td>\n</tr>\n<tr>\n<td><code>walk</code></td>\n<td><code>to</code>: <code>[x, y]</code>, <code>facing</code>, <code>until</code>, <code>curve</code>, <code>heading</code>, <code>stride</code></td>\n<td>walk to a spot and stop, facing <code>facing</code> degrees. They turn on the spot first when the way to go is more than 30 degrees off, and again at the end. With no <code>until</code> or <code>dur</code> it takes what the steps need. A footstep in the sound per step. <code>\"curve\": true</code> walks a bend in place of a line and two turns: the feet land on the bend, the body banks into it and the head looks along it; <code>heading</code> is the way they are going as they arrive (degrees, like <code>facing</code>). <code>stride</code> is a step's length as a share of the leg (0.5 by default, a stroll; 0.75 to 0.8 is an unhurried lecturer's walk in fewer steps, 0.3 to 0.85)</td>\n</tr>\n<tr>\n<td><code>turn</code></td>\n<td><code>facing</code>, <code>dur</code></td>\n<td>turn on the spot, stepping round: the eyes and head go first, the chest follows, and it swings a little past at the end</td>\n</tr>\n<tr>\n<td><code>wink</code></td>\n<td><code>side</code>: <code>left</code>/<code>right</code></td>\n<td>one eye, the brow dipping with it</td>\n</tr>\n<tr>\n<td><code>look_at</code></td>\n<td><code>target</code>: <code>[x, y, z]</code>, <code>camera</code> or <code>screen</code>, <code>dur</code></td>\n<td>head and eyes to a point: the neck turns most of the way, the eyes the rest</td>\n</tr>\n<tr>\n<td><code>glance</code></td>\n<td><code>yaw</code>, <code>pitch</code>, <code>dur</code></td>\n<td>the eyes alone, in degrees (up to about 25)</td>\n</tr>\n<tr>\n<td><code>reach</code></td>\n<td><code>target</code>: <code>[x, y, z]</code>, <code>hand</code>, <code>dur</code></td>\n<td>a hand to a point in the room; an error says how far short it is</td>\n</tr>\n<tr>\n<td><code>point</code></td>\n<td><code>target</code>: <code>[x, y, z]</code>, <code>camera</code> or <code>screen</code>; <code>hand</code>; <code>back</code>; <code>dur</code></td>\n<td>the arm lifts nearly straight at the target (it reads from across a room), index out, thumb up; held for the beat (1.5 s without <code>dur</code>), then back unless <code>\"back\": false</code>. Without <code>hand</code>, the one on the target's side. Add a <code>look_at</code> to the same target for the eyes. The event gives <code>aim_deg</code></td>\n</tr>\n<tr>\n<td><code>hand</code></td>\n<td><code>shape</code>: <code>open</code>, <code>relaxed</code>, <code>loose</code>, <code>grip</code>, <code>flat</code>, <code>type</code>, <code>point</code>, <code>fist</code>; <code>hand</code>: <code>left</code>/<code>right</code>; <code>dur</code></td>\n<td>the fingers take a shape (both hands without <code>hand</code>). Only a fitted model whose fit found fingers has them: the clay cast's mittens are left as they are. Poses and verbs set shapes themselves (<code>type</code> on the keys, flat on the desk, a grip on a door handle, relaxed at the sides), so this is for a point or a fist. <code>loose</code> hangs more open than <code>relaxed</code>: on a fit whose relaxed hand reads as a fist at the side, set the free hand <code>loose</code> at the clip's start (gestures come back to it)</td>\n</tr>\n</tbody>\n</table>\n<p>A presenter on their feet (a <code>lecture_hall</code> set for the things that are carried; the rest work anywhere):</p>\n<table>\n<thead>\n<tr>\n<th>verb</th>\n<th>fields</th>\n<th></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>talk</code></td>\n<td><code>until</code>, <code>amount</code></td>\n<td>the mouth opens and closes on the narration's words between the beat and <code>until</code> (the spec's <code>voice</code> captions): one opening a syllable, wider for an open vowel, rounder for an o or a u, shut on a pause and on b, m and p; the head dips a little on the longer words. A fitted face only</td>\n</tr>\n<tr>\n<td><code>blinks</code></td>\n<td><code>until</code></td>\n<td>blinks every two to five seconds, now and then twice</td>\n</tr>\n<tr>\n<td><code>whistle</code></td>\n<td><code>until</code>/<code>dur</code></td>\n<td>the lips purse as for a whistle and swell a little on each breath, eased in and out (the sound is yours to lay on: a recording, placed on the same seconds). A fitted face only</td>\n</tr>\n<tr>\n<td><code>gesture</code></td>\n<td><code>kind</code>: <code>open</code>, <code>both</code>, <code>shrug</code>, <code>count</code>; <code>hand</code>; <code>dur</code></td>\n<td>a talking gesture held for the beat, then the hands go back: one open hand lifting on a point, both hands opening out, a shrug with the head tipping, a raised index</td>\n</tr>\n<tr>\n<td><code>present</code></td>\n<td><code>target</code>: <code>[x, y, z]</code> or <code>screen</code>; <code>hand</code>; <code>dur</code></td>\n<td>show something beside or behind them (a board): the chest turns part of the way, the head and eyes go to it and stay for the first half, the arm on that side points; then all come back. Follow it with a <code>look_at</code></td>\n</tr>\n<tr>\n<td><code>dust_hands</code></td>\n<td><code>dur</code></td>\n<td>the hands come up palms together and brush past each other</td>\n</tr>\n<tr>\n<td><code>carry</code></td>\n<td><code>prop</code>: <code>cup</code>; <code>hand</code></td>\n<td>from this beat the cup is in a hand held in front of the chest, and that arm stays out of a walk's swing. A mug is held by its handle (the fist closed on it, the mug out past the knuckles); a takeaway cup in a hand round it. The hand goes on carrying through <code>sit_down</code> and <code>pull_in</code>, level, and lifts the cup clear of the table as it comes under it</td>\n</tr>\n<tr>\n<td><code>put_down</code></td>\n<td><code>prop</code>: <code>cup</code> or <code>chalk</code>; <code>hand</code>; <code>to</code>: <code>[x, y, z]</code>; <code>lean</code>; <code>dur</code></td>\n<td>the hand takes what it holds to its spot on the table and lets go; an error says how far short the arm is. <code>lean</code> is how far the chest bends to it (9 degrees unless given). Someone sitting at a kitchen table leans only as far as the table's edge allows, the hand lies flat beside the laptop afterwards, and the other hand stays where it lies on the table</td>\n</tr>\n<tr>\n<td><code>pick_up</code></td>\n<td><code>prop</code>: <code>chalk</code> or the kitchen's <code>cup</code>; <code>hand</code>; <code>dur</code></td>\n<td>a hand takes the chalk off the table; it lies along the index finger and the hand keeps hold of it through every later shape. The kitchen's mug is taken by its handle and lifted to where a cup is carried (about half a second after the beat), so <code>sip</code> and <code>put_down</code> follow; a mug that has stood there since the film began is turned to offer its handle to that hand</td>\n</tr>\n<tr>\n<td><code>sip</code></td>\n<td><code>hand</code>; <code>dur</code>; <code>part</code>: 0 to 1; <code>stay</code>: true</td>\n<td>the mug in that hand goes up to the mouth, tips, and comes back down by the end of the beat, the elbow rising out to the side over the top half of the way. <code>part</code> stops it short (0.5 is half way up); <code>stay</code> leaves it up there, for a sip that is interrupted. Needs a <code>carry</code> or <code>pick_up</code> first</td>\n</tr>\n<tr>\n<td><code>hold</code></td>\n<td><code>prop</code>: <code>chalk</code>; <code>hand</code></td>\n<td>the chalk is in the hand from this beat (a clip that starts after it was picked up)</td>\n</tr>\n</tbody>\n</table>\n<p>At a kitchen table (a <code>kitchen</code> set; <code>carry</code> and <code>put_down</code> with <code>\"prop\": \"cup\"</code> work there too, the cup being\nthe mug):</p>\n<table>\n<thead>\n<tr>\n<th>verb</th>\n<th>fields</th>\n<th></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>open_lid</code>, <code>close_lid</code></td>\n<td><code>dur</code>; <code>by</code>: a cast id; <code>hand</code></td>\n<td>the laptop's lid swings open or shut (0.6 s unless timed). With <code>\"by\"</code>, that person's fingertips are on its top edge for the move: the hand sets out 0.4 s before the beat, comes to the edge from above, goes with it and rests on it a moment. The chest turns that shoulder to the lid and leans as far as the table's edge lets it, worked out from the reach on each frame: do not add a <code>lean</code>. Shutting, a hand on the keys goes to the table beside the laptop first, and both hands end flat there. Events <code>lid_open</code> (as it starts) and <code>lid_close</code> (as it lands)</td>\n</tr>\n<tr>\n<td><code>claude_type</code></td>\n<td><code>until</code>/<code>dur</code>; <code>speed</code>: <code>frantic</code> or <code>calm</code></td>\n<td>Claude's hands go up and down on his keyboard, with a <code>key_click</code> event for each key (ten a second when frantic)</td>\n</tr>\n<tr>\n<td><code>claude_turn</code></td>\n<td><code>facing</code>: degrees; <code>dur</code></td>\n<td>he turns on his foot to face that way (0 faces -Y), swinging a little past and back</td>\n</tr>\n</tbody>\n</table>\n<p>Poses also has <code>down</code> (arms at the sides), which a standing character starts in; arms swing on a walk only from\n<code>down</code>. A posture verb used in the wrong state is a named error (\"dev is sitting: walk needs them standing\n(stand_up first)\"). <code>ik_max_error_m</code> in the report covers feet as well as hands, and <code>ik_worst</code> names the limb\nand the second when it is over a centimetre: usually a step or a reach that was too far.</p>\n<p><strong>Contact is checked for anyone on their feet.</strong> The report measures, on every frame, what a still can't show:</p>\n<table>\n<thead>\n<tr>\n<th>in <code>checks.json</code></th>\n<th>fails over</th>\n<th></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>under_floor_m</code></td>\n<td>1.5 cm</td>\n<td>any of the body below the floor</td>\n</tr>\n<tr>\n<td><code>hand_in_body_m</code></td>\n<td>3 cm</td>\n<td>a hand inside the torso, head or legs</td>\n</tr>\n<tr>\n<td><code>through_m</code></td>\n<td>3 cm</td>\n<td>the body inside the seat, chair back, desk, laptop or door (a seat cushion gives 3 cm)</td>\n</tr>\n<tr>\n<td><code>foot_slide_m</code></td>\n<td>3 cm</td>\n<td>a foot travelling along the floor while it stands flat on it</td>\n</tr>\n<tr>\n<td><code>touch_miss_m</code></td>\n<td>3 cm</td>\n<td>a hand off the thing it was put on (the door handle, the desk's edge)</td>\n</tr>\n<tr>\n<td><code>grip_open</code></td>\n<td>over 0.75</td>\n<td>hands with fingers: how open a hand still is round what it holds (fingertips' distance from it over a finger's length; a flat hand is about 1)</td>\n</tr>\n<tr>\n<td><code>hands_apart_m</code></td>\n<td>under 0.5 cm</td>\n<td>hands with fingers: the nearest the two hands come to each other</td>\n</tr>\n<tr>\n<td><code>carried_tilt_deg</code></td>\n<td>12 degrees</td>\n<td>something in the hand (a mug of tea) tipped from upright; the tip of a <code>sip</code> is the mug's own and is not counted</td>\n</tr>\n<tr>\n<td><code>carried_through_m</code></td>\n<td>0.6 cm</td>\n<td>something in the hand inside a table, a door or a lid</td>\n</tr>\n<tr>\n<td><code>palm_tilt_deg</code></td>\n<td>35 degrees</td>\n<td>hands with fingers: a hand resting over a table top, rolled from palm down onto its side (a typing hand slopes down from the wrist on purpose; the slope is not counted)</td>\n</tr>\n<tr>\n<td><code>palm_turn_deg</code></td>\n<td>35 degrees</td>\n<td>hands with fingers: a hanging hand's palm turning away from the leg as the arm swings in a walk (it reads as a flapping hand)</td>\n</tr>\n<tr>\n<td><code>snap_m</code></td>\n<td>2 cm</td>\n<td>the chest or a hand moving much further in one frame than in the frames either side (a key beside another, a hand put from one spot to the next in a frame)</td>\n</tr>\n</tbody>\n</table>\n<p>A thin thing (a door leaf, a desk top) counts as gone through once anything is half way into it, and <code>through</code>\nsays how long it lasted (\"from 14.50 s to 20.67 s\"). A hand is checked at its palm and at every fingertip.</p>\n<p>A failure is said in words in <code>body_problems</code> (\"left hand 9 cm inside the body at 5.12 s\") and each number gets an\n<code>_at</code> with the frame. <code>moves</code> lists every posture verb with how far apart in time its parts start and stop and how\ndifferent left is from right: all zeros would be a machine. To look at a move yourself, render the shot as a clip\nwith <code>--keep-frames</code> and tile every second or third frame.</p>\n<p><strong>More that <code>check</code> reports</strong>, each failing the check in words when it is wrong:</p>\n<ul>\n<li><code>walks</code>: each walk's bow off the straight line, its turn, and how far the body leans into a bend. For a fitted\nmodel, <code>arms</code> too: <code>elbow_deg</code> (the most an elbow bends, fails over 35: arms swing from the shoulder),\n<code>forearm_deg</code> (the forearm's least angle below level, fails under 40: it reads as marching) and <code>hand_off_m</code>\n(how far a hand stands out from the body beside it, the middle value through the walk, fails over 4 cm: arms\nheld out like a gunslinger's; <code>hand_off_max_m</code> is the most, which a thigh swinging away makes on long legs).</li>\n<li><code>typing</code>, for hands with fingers: <code>rest_m</code> (the fingertips' usual height over the keys, fails over 8 mm),\n<code>into_m</code> (fails under -4 mm) and <code>finger_travel_m</code> (how far a finger moves on its own, fails under 6 mm: hands\nthat type without moving their fingers).</li>\n<li><code>surfaces_fight</code> and <code>set_problems</code>: two objects of different materials with faces in one plane that a camera\nsees. The renderer draws one or the other from frame to frame, so the strip flickers. Move one, or end it\ninside the other. Graphics layered a little over a screen do not count.</li>\n<li>For a fitted model: <code>face</code> (<code>mouth_share</code>, the mouth's width against the face's, fails under 0.18; how far the\nlip stands off the face; how far its corners travel between a frown and a smile) and <code>skin</code>\n(<code>leg_above_hips</code>, vertices above the hips that move with a leg and tear a hem; <code>stretch</code>, fails over 4).</li>\n</ul>\n<p><strong>A render is checked too.</strong> <code>render</code> writes <code>still_points.json</code> (points of the set that stand still, and where\neach is in every frame) and reads them back out of the picture: a still point that jumps for one frame and comes\nback is flicker. Five such frames on one object in a shot fail (<code>render_checks.json</code>, and the tool exits 1);\nfewer are listed as notes. It runs on the film and on <code>--clips</code>. Points are read between pixels, so a camera\nmoving over a surface with a picture on it (a board with writing) is not reported.</p>\n<p>Set (<code>desk_room</code>): <code>alert</code> (popup + red screen light), <code>work</code> (<code>until</code>: bar drains bad → mid → good),\n<code>done</code> (the \"after\" line pops in), <code>open_door</code> / <code>close_door</code> (<code>dur</code>, <code>angle</code>, and <code>by</code>: a cast member whose hand\ntakes the handle and goes with the door as far as the arm reaches; an error says how far short they stand),\n<code>pull_in</code> (the chair and whoever sits on it come in to the desk: the feet walk it in with short steps and, once\nthe desk is in reach, the hands take its edge and pull). The screen's words and numbers come from <code>set.screen</code>\n(<code>title</code>, <code>subtitle</code>, <code>before</code>, <code>after</code>, <code>fill_before</code>, <code>fill_after</code>, <code>alert</code> [2 lines], <code>working</code>).</p>\n<p>Effects: <code>confetti</code> (<code>count</code>, <code>colors</code>: a list of hex colours, for the brand's), <code>title</code> (<code>text</code>, <code>color</code>): 3D text above the character, wobbles to the end.</p>\n<h3>Sets</h3>\n<p><code>desk_room</code> takes <code>\"door\": {}</code> (a doorway in the wall behind the chair, at <code>x</code> 2.6 unless given, as tall as the\ncharacter needs and with the handle where their hand falls, opening onto a dim hall) and <code>\"chair_out\"</code> (metres the\nchair starts pulled back from the desk). An entrance: the character starts in the hall at <code>[2.6, 3.5]</code> (in reach\nof the handle), <code>open_door</code> with <code>\"by\"</code>, <code>walk</code> in, <code>walk</code> to a thigh's length in front of the pulled-out chair, <code>sit_down</code>, <code>pull_in</code>.</p>\n<table>\n<thead>\n<tr>\n<th><code>kind</code></th>\n<th></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>desk_room</code> (default)</td>\n<td>a room: walls, window, posters, rug, desk, chair, laptop, mug, plant. <code>palette</code> recolours it (<code>wall</code>, <code>wall2</code>, <code>floor</code>, <code>desk</code>, <code>accent1</code>, <code>accent2</code>, <code>rug</code>)</td>\n</tr>\n<tr>\n<td><code>desk</code></td>\n<td>the desk, chair and laptop with no room, for <code>--alpha</code>: the character sits on whatever the Remotion scene puts behind it</td>\n</tr>\n<tr>\n<td><code>lecture_hall</code></td>\n<td>a wall with a board that shows a picture (<code>\"board\": {\"image\": ..., \"x0\", \"x1\", \"z0\", \"z1\"}</code>: the rectangle of the wall it covers, the same one a <code>fixed</code> camera can frame square on), a <code>\"door\"</code>, and a small table (<code>\"table\": {\"at\", \"size\", \"height\", \"cup\", \"chalk\"}</code>) with a takeaway cup and a stick of chalk. <code>\"walls\": false</code> leaves the room out for <code>--alpha</code>; <code>\"table\": {\"hidden\": true}</code> keeps the table to reach for and does not draw it; <code>\"cup_on\": true</code> starts with the cup already on it. The cast stands</td>\n</tr>\n<tr>\n<td><code>kitchen</code></td>\n<td>a home kitchen at night, built round the desk room's table, chair and laptop (so <code>door</code>, <code>chair_out</code>, <code>pull_in</code> and the screen work as they do there): a run of units with a sink under a window, a kettle and a hob, a fridge, a second run on the left wall, a pendant lamp over the table, a clock. <code>\"lid\": \"closed\"</code> starts the laptop shut. <code>\"mug\": {\"at\": [x, y], \"on_table\": true, \"color\", \"inside\"}</code> places the mug of tea (<code>on_table</code> for a clip that starts after it was put down): 12 cm tall with a handle a hand fits, in the room's accent colour unless given one. <code>\"claude\": {\"at\": [x, y], \"facing\", \"screen\": {\"video\" or \"image\", \"at\", \"brightness\"}, \"hat\": false}</code> stands Claude on the worktop: a beige CRT with a face on its screen (bars until you give it a picture or a video at the spec's <code>fps</code>), a tinfoil hat and two arms at a keyboard. <code>palette</code> adds <code>units</code>, <code>worktop</code>, <code>night</code>, <code>lamp</code></td>\n</tr>\n<tr>\n<td><code>studio</code></td>\n<td>a product stage: a backdrop curving from floor to wall, soft lights sized to the props, no character and no beats. <code>palette.backdrop</code> colours it; with <code>--alpha</code> the backdrop is left out</td>\n</tr>\n</tbody>\n</table>\n<p>An evening at the kitchen table, from the door to the screen (the character starts in the hall, a forearm\nfurther from the door than without a mug, so the hand that carries it is not in the leaf):</p>\n<pre><code>\"set\": {\"kind\": \"kitchen\", \"door\": {}, \"chair_out\": 0.75, \"lid\": \"closed\"},\n\"cast\": [{\"id\": \"dev\", \"posture\": \"stand\", \"at\": [2.6, 3.5], \"facing\": 0}],\n\"beats\": [\n  {\"at\": 0, \"do\": \"carry\", \"prop\": \"cup\", \"hand\": \"left\"},\n  {\"at\": \"S1+0.3\", \"do\": \"open_door\", \"dur\": 0.8, \"by\": \"dev\", \"hand\": \"right\"},\n  {\"at\": \"S1+1.2\", \"do\": \"walk\", \"to\": [2.6, 2.0], \"until\": \"S1+3.0\"},\n  {\"at\": \"S1+3.1\", \"do\": \"walk\", \"to\": [0, 0.41], \"facing\": 0, \"curve\": true, \"heading\": -90, \"until\": \"S1.end\"},\n  {\"at\": \"S2+0.1\", \"do\": \"sit_down\", \"dur\": 1.8},\n  {\"at\": \"S2+2.0\", \"do\": \"pull_in\", \"dur\": 1.3},\n  {\"at\": \"S2+3.5\", \"do\": \"put_down\", \"prop\": \"cup\", \"hand\": \"left\", \"dur\": 0.8},\n  {\"at\": \"S3+0.9\", \"do\": \"open_lid\", \"dur\": 0.9, \"by\": \"dev\"}\n]\n</code></pre>\n<p>They sit before the mug goes down: a standing arm does not reach a table that low (only the chest bends, and\nthe error says \"sit them down first\"). Later, <code>{\"do\": \"pick_up\", \"prop\": \"cup\", \"hand\": \"left\", \"dur\": 0.6}</code> and,\nhalf a second after it ends, <code>{\"do\": \"sip\", \"hand\": \"left\", \"dur\": 2.0}</code> have them drink; <code>\"stay\": true</code> on a\nshort <code>sip</code> stops the mug at the lips for something to interrupt. A hand's move runs on for about half a second after its beat ends (the\nhand comes to rest on the table), so leave that before the next beat that uses the arms; a beat that starts\ninside another's move takes the hand from wherever it is on that frame.</p>\n<p><strong>Studio props</strong> (<code>set.props</code>, each with an <code>id</code> that shots name as their <code>subject</code>):</p>\n<table>\n<thead>\n<tr>\n<th><code>kind</code></th>\n<th></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>phone</code></td>\n<td>a phone standing on the stage; <code>screen.video</code> or <code>screen.image</code> is its picture (portrait or landscape, the phone follows the picture's shape)</td>\n</tr>\n<tr>\n<td><code>card</code></td>\n<td>a thin floating panel showing a picture or a video, <code>width</code> in metres (default 0.6): a UI screenshot or a Remotion scene with depth</td>\n</tr>\n<tr>\n<td><code>model</code></td>\n<td>a <code>.glb</code>, <code>.gltf</code>, <code>.obj</code>, <code>.fbx</code> or <code>.stl</code> file (<code>file</code>), scaled so its longest side is <code>size</code> metres (default 0.3) and set down on the floor</td>\n</tr>\n</tbody>\n</table>\n<p>Props stand side by side unless given <code>\"at\": [x, y]</code> (metres); <code>\"turn\"</code> (degrees) rotates one. Without a\npicture, a phone or a card shows the palette's <code>accent</code>, so a layout can be checked before the render exists.\nScreens take <code>skip_frames</code>, <code>at</code> and <code>brightness</code> as the laptop does, and want <code>\"view\": \"Standard\"</code> for the same\nreason.</p>\n<pre><code>\"set\": {\"kind\": \"studio\", \"palette\": {\"backdrop\": \"#DCE2EE\"},\n        \"props\": [{\"id\": \"ui\", \"kind\": \"card\", \"screen\": {\"video\": \"../out/scene.mp4\"}},\n                  {\"id\": \"app\", \"kind\": \"phone\", \"screen\": {\"image\": \"app.png\"}, \"at\": [0.42, -0.12], \"turn\": -18}]},\n\"shots\": [{\"id\": \"P1\", \"dur\": 4, \"type\": \"reveal\", \"subject\": \"ui\"},\n          {\"id\": \"P2\", \"dur\": 3, \"type\": \"orbit\", \"subject\": \"app\", \"az\": -35, \"az_to\": 35}]\n</code></pre>\n<p>An imported model keeps its own materials. Check its licence before it goes in a video, as with any asset.</p>\n<p><strong>A Remotion render on the laptop.</strong> <code>set.screen.video</code> (or <code>image</code>) replaces the storage UI with a picture, 16:9\nand unlit so its colours survive:</p>\n<pre><code>\"look\": {\"view\": \"Standard\", \"exposure\": -0.9},\n\"set\": {\"kind\": \"desk_room\", \"screen\": {\"video\": \"../out/screen.mp4\", \"skip_frames\": 150}}\n</code></pre>\n<ul>\n<li>The video advances one frame per scene frame, so render it at the spec's <code>fps</code>: a video at another rate is a\nspec error. <code>skip_frames</code> starts it part-way in; <code>at</code> (a time) delays it; past its end it holds the last frame.\n<code>brightness</code> scales it.</li>\n<li>Use <code>\"view\": \"Standard\"</code> when a flat scene cuts to the same scene on the laptop: the default AgX view compresses\ncolour, and the cut would show. With Standard the first frame of a <code>pull_out</code> matches the flat frame.</li>\n<li>With a picture on the screen, <code>alert</code>, <code>work</code> and <code>done</code> still tint the screen's light and make their sounds,\nbut draw nothing.</li>\n</ul>\n<p><strong>Score</strong>: <code>calm</code>, <code>tension</code>, <code>resolve</code> sections. This is simple synthesis for a draft; for the real bed run\n<code>tools/music_gen.py</code> at the film's length and mix it under with <code>tools/addmusic.py</code>.</p>\n<h2>From a brief to beats</h2>\n<p>A short gag is a turn: <strong>normal → problem → reaction → effort → fix → payoff</strong>. Give each its shot:</p>\n<ol>\n<li><em>Normal</em>: <code>wide</code>, 2.5–3 s, calm idle (<code>type</code> calm + <code>head_bob</code>), <code>calm</code> score.</li>\n<li><em>Problem</em>: <code>over_shoulder</code> on the screen, the <code>alert</code> ~0.5 s in; hold the character still (<code>hold_arms</code>).</li>\n<li><em>Reaction</em>: <code>closeup</code>, <strong>slow</strong>: the face changes 0.1 s in, then let it sit (<code>tremble</code>, <code>sweat</code>, a <code>gulp</code>\naround 2 s). Comedy is in the hold; 3–3.5 s.</li>\n<li><em>Escalation</em>: <code>medium</code> for the big gesture (<code>hands_on_head</code> + <code>shake_head</code>), <code>tension</code> score.</li>\n<li><em>Effort</em>: <code>side</code> with <code>shake</code>, <code>lean</code> forward, <code>determined</code>, <code>type</code> frantic; cut to an <code>insert</code> of the\nscreen for <code>work</code> → <code>done</code>.</li>\n<li><em>Relief</em>: <code>closeup</code>, <code>relieved</code>, a slow <code>blink</code>, <code>lean</code> back.</li>\n<li><em>Payoff</em>: <code>front_wide</code>: <code>celebrate</code>, <code>grin</code>, <code>confetti</code>, <code>title</code>; end on a settle (<code>hands_behind_head</code>).</li>\n</ol>\n<p>Rules of thumb: a beat lands 0.1–0.5 s <em>after</em> a cut, not on it; one idea per shot; cut to the screen whenever\nthe screen changes; keep expressions on screen at least 0.5 s; vary shot type between neighbours.</p>\n<p>When the video has narration, take the times from the voice: a <code>voice</code> block and <code>cue:</code> times (above), one beat\non the word it illustrates.</p>\n<h2>Blender clips in a Remotion video</h2>\n<pre><code>uv run tools/blender_render.py render spec.json --clips --alpha --to projects/my-video/public/blender\nuv run tools/blender_render.py render spec.json --clips --shots B1_act --to ...    # one shot again\n</code></pre>\n<p>One clip per shot lands in the project with a <code>clips.json</code> manifest: <code>.webm</code> (VP9 with alpha) with <code>--alpha</code>,\n<code>.mp4</code> without, and a <code>.wav</code> of the shot's own effects. <code>--prores</code> adds ProRes 4444 for other editors. To change\none kind of effect against the rest (footsteps too loud under a door), write the WAV again from the render's\n<code>events.json</code> with <code>sound.render(events, wav, start=, end=, score=False, room=False, gains={\"step\": 0.35})</code>\n(0.35 is 9 dB down).</p>\n<p>Several specs can render <code>--to</code> one folder (a room and a transparent desk). Each clip in <code>clips.json</code> carries its\nown <code>fps</code>, <code>resolution</code> and the <code>spec</code> it came from, so they can differ; give the specs' shots different ids (a\nclash is warned about, and the later render wins). Rendering a whole spec drops its shots that are no longer in it.</p>\n<pre><code>import manifest from '../public/blender/clips.json';\nimport { BlenderClip, blenderClip } from '../../../lib/components';\n\nconst act = blenderClip(manifest, 'B1_act');          // throws with the ids it has if the shot isn't there\n&lt;Sequence from={ACT} durationInFrames={act.frames}&gt;\n  &lt;BlenderClip clip={act} style={{ left: 560, top: 270, width: 1440 }} /&gt;\n&lt;/Sequence&gt;\nconst ALERT = ACT + act.event('alert');               // composition frame of the alert, for a caption or a cut\n</code></pre>\n<p>What makes it sit in the scene:</p>\n<ul>\n<li><strong>Let the clip's bottom edge be the frame's.</strong> A <code>wide</code> shot cuts the desk legs at the bottom of the picture;\nplaced higher, they stop in mid-air.</li>\n<li><strong>Put type behind the clip and let the action cross it.</strong> Order in the JSX is depth: a title, then the clip,\nand the confetti falls in front of the words. That is what reads as 3D.</li>\n<li><strong>Show the spec beside the acting.</strong> The Remotion scene can import the spec JSON and light each beat as it\nplays; both read the same times, so they can't drift (<code>examples/blender-in-remotion/src/Video.tsx</code>).</li>\n<li><strong>Hard cut to a <code>pull_out</code>.</strong> Use the flat scene's own component for the first part and cut on the frame the\nspec's <code>skip_frames</code> names. No fade is needed, and a fade would show the two as different pictures.</li>\n<li>A transparent clip has no cast shadow (EEVEE can't render one onto nothing). Keep the character on a flat\nfield, where none is expected.</li>\n<li>A transparent render of a full room is a waste: use kind <code>desk</code>.</li>\n</ul>\n<p><strong>An inset of a clip</strong> is the clip with a <code>crop</code> (the clip's own pixels), scaled to fill the box, with the\nclip's backdrop as <code>background</code> (a picture the size of the clip's frame, cropped with it) and a shadow that\nfollows the character in <code>clipStyle</code>. Do not build one by scaling a layer round the clip: the clip keeps its\nfull-size box and draws outside it.</p>\n<pre><code>&lt;BlenderClip clip={act} volume={0} crop={{ x: 518, y: 92, w: 475, h: 422 }} background=\"board/bg-presenter.png\"\n  clipStyle={{ filter: 'drop-shadow(-6px 4px 6px rgba(0,0,0,0.38))' }} style={{ left: 1620, top: 810, width: 270 }} /&gt;\n</code></pre>\n<p>In a video of many clips (a presenter clip per segment, room shots, a Remotion board):</p>\n<ul>\n<li><strong>Read every frame from its source</strong>: clip starts from the timeline or <code>cue()</code>, lengths from <code>clips.json</code>,\nsound frames from <code>clip.event(...)</code>, and the spec generator from the same timeline file. Never type a frame\nseen in an earlier render: when the script grows, it is silently wrong.</li>\n<li><strong>Play shots by id, not by <code>clips.json</code> order</strong>: a shot rendered again goes to the end of the manifest.</li>\n<li><strong>Sounds for small props</strong> (a cup, a chalk tap) that the clip's WAV does not carry are laid on the clip's\nevent frames in the composition and checked with <code>tools/sync_check.py</code>: <code>impact</code> for a landing, <code>onset</code> for\nsomething picked up.</li>\n<li><strong>One Blender render at a time</strong>: it is bound by the GPU (0.69 s a frame alone, 0.9 s with three side by\nside), so queue the specs.</li>\n<li><strong>After the full render, read the render itself</strong>: <code>qc.py --render</code>, then one frame every 10 s tiled\n(<code>uv run tools/contact_sheet.py out/video.mp4 --count &lt;seconds / 10&gt;</code>). Stills of each part can all look\nright while a layer over them is empty in the render.</li>\n</ul>\n<p>The order to build in when the screen shows the video's own scene: render the Remotion scene\n(<code>npx remotion render ... Screen out/screen.mp4</code>), then the Blender clips, then the video.</p>\n<h2>Extending</h2>\n<ul>\n<li>New verb: a method on <code>ClayPerson</code> (<code>lib/blender/character.py</code>) or <code>DeskRoom</code> (<code>lib/blender/sets.py</code>) that takes\nframes and appends <code>{\"frame\", \"kind\"}</code> to <code>self.events</code> for its sound; then a branch in <code>compile.py</code> and, if it\ntakes a named choice, a line in <code>validate()</code>. Write lengths as <code>n(frames at 24 fps)</code> and repeats with\n<code>ticks()</code> (<code>lib/blender/kit.py</code>), so the verb lasts the same time at any frame rate.</li>\n<li>New look: a choice in <code>lib/blender/cast.py</code> (<code>CHOICES</code>), then the geometry for it in <code>character.py</code>.</li>\n<li>New prop kind: <code>lib/blender/studio.py</code>.</li>\n<li>New shot type: a row in <code>SHOT_TYPES</code> (<code>lib/blender/cameras.py</code>).</li>\n<li>New sound: a <code>kind</code> branch in <code>lib/blender/sound.py</code>.</li>\n<li>Only <code>lib/blender/kit.py</code> touches the low-level API; fix Blender version changes there.</li>\n<li><code>lib/blender/timeline.py</code> (times and cues) and <code>lib/blender/cast.py</code> (character descriptions) have no Blender\nin them and are tested in <code>tests/python/test_blender_spec.py</code>, which also builds real scenes when Blender is\ninstalled: every look, the moves in three frame shapes, the studio, and the spec errors.</li>\n</ul>\n<h2>Looking round the scene, and Blender MCP</h2>\n<p><code>blender_render.py open spec.json</code> opens the built <code>scene.blend</code>. Use it, or a Blender MCP server attached to\nthat window, to try a pose, a light or a camera with a person watching. Then write what worked into the spec or\n<code>lib/blender/</code>: the <code>.blend</code> is rebuilt on the next run, and the spec is what makes the video repeatable. The\nrender itself always goes through <code>blender_render.py</code> (headless Blender Python), never through a live session.\nThe reasoning is in <code>docs/blender.md</code>.</p>\n<h2>Blender gotchas (5.3)</h2>\n<ul>\n<li><p>Blender exits 0 when the script it ran raised. <code>blender_render.py</code> looks for the compiler's <code>COMPILE_DONE</code>\nline, not the exit code.</p>\n</li>\n<li><p>A movie's frame rate is on <code>bpy.data.movieclips.load(path).fps</code>, not on the image datablock.</p>\n</li>\n<li><p>Video output: set <code>image_settings.media_type = \"VIDEO\"</code> <em>before</em> <code>file_format = \"FFMPEG\"</code> (5.0 change).</p>\n</li>\n<li><p>EEVEE's engine id is <code>BLENDER_EEVEE</code> (it was <code>BLENDER_EEVEE_NEXT</code> in 4.2–4.4); <code>kit.setup_render</code> picks.</p>\n</li>\n<li><p>IK on roll-0 arm bones needs <code>pole_angle = +90°</code> (−90 points the elbows backwards). Measure, don't guess:\ncompare the solved elbow with the pole target.</p>\n</li>\n<li><p>Distance-based skin weights bleed the chest into raised arms; use <code>parent_set(type=\"ARMATURE_AUTO\")</code> (bone heat).</p>\n</li>\n<li><p>AgX with default lights washes cartoon colours out; <code>exposure ≈ -0.9</code> and the <code>AgX - Punchy</code> look fix it.</p>\n</li>\n<li><p><code>-P script.py</code> runs with Blender's own Python: only <code>bpy</code>, <code>bmesh</code>, <code>mathutils</code> and the stdlib; no numpy\nguarantees, no toolkit imports. Host-side work (sound, exposure, sheets) stays in <code>tools/</code>.</p>\n</li>\n<li><p>First Cycles frame compiles GPU kernels (minutes); time later frames when estimating (<code>doctor</code> does).</p>\n</li>\n<li><p>An object scaled to zero (a hidden mouth shape) has no inverse matrix: skip it before <code>closest_point_on_mesh</code>.</p>\n</li>\n<li><p>A movie texture needs <code>image_user.use_auto_refresh = True</code> or every frame renders the first one, and\n<code>frame_duration</code> set from the image, or it shows nothing.</p>\n</li>\n<li><p><code>film_transparent</code> gives straight alpha in the PNGs; encode with <code>-pix_fmt yuva420p -auto-alt-ref 0</code> or\nlibvpx drops the alpha plane.</p>\n</li>\n</ul>\n<h2>Limits</h2>\n<p>One character per set (Claude in the kitchen is a prop with two verbs, not a cast member); a lid is opened\nand shut by hand only by a fitted character with fingers who can reach it, and one whose arm is too short to\nshut it, or who cannot lay a hand flat beside the laptop, gets an error that says so (leave out <code>\"by\"</code>, and the\ncheck then fails a lid that shuts on hands left on the keys); a <code>lean</code> beat carries hands that rest on a table\ndown through it, since they hang from the chest (use the verbs that put a hand somewhere); a standing\n<code>put_down</code> needs a table near shoulder height; a <code>sip</code> on a broad short-armed character bunches the sleeve at the\nshoulder from a wide camera (film it close, or use <code>part</code>); the kitchen is 6 m deep, so a <code>wide</code> on the clay cast is behind\nits front wall (use <code>medium</code> or a <code>fixed</code> camera); the clay cast's hands are one bone (a mitten), so its <code>reach</code> puts the hand on a thing\nbut does not close round it (a fitted model can have fingers); nothing stops a walk going through furniture (walk\nround it, or bend the walk with <code>curve</code>); the clay cast's hoodie hem is ragged when it stands, because its\nbody is made seated; a studio set has props and no character; cartoon \"clay\" style;\nhand-keyed acting (no motion capture); no cast shadow on a transparent background; studio props don't move (the\ncamera does). Next on the roadmap: props that move and a tablet prop, cast shadows on transparent clips, two\ncharacters in a set, hand shapes and props in the hand, your own <code>.blend</code> as a set, a <code>script</code> hook in the spec, imported rigs,\nand a <code>blender</code> visual kind in <code>video_job.py</code>.</p>\n","files":[{"path":"SKILL.md","sizeBytes":47753,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-11-14T19:11:59.770025Z","sha256":"9B698BB47BE660F5254D56A502641635B38A9CBAD98F16FF3D7A9B70C4EF958B","sizeBytes":19533},"review":null,"source":{"repositoryUrl":"https://github.com/digitalsamba/claude-code-video-toolkit","path":".claude/skills/blender","license":"MIT","commit":"23b82453d675782b40b78f1fc94f842700a1034d","subtreeSha":"237988F14ECFB157DF44FEB29D960524CC5FB73FDFB36F2CAA7CB3DFC2487B08","lastSyncedAt":"2026-11-14T19:10:39.039882Z"},"reviewedAt":"2026-11-14T19:15:14.603661Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/digitalsamba/claude-code-video-toolkit/tree/main/.claude/skills/blender"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install digitalsamba-claude-code-video-toolkit@llmmart"},{"target":"git","command":"git clone https://github.com/digitalsamba/claude-code-video-toolkit.git"}]}