gpt-hand-drawing-skill

GPT Hand Drawing Skill for Codex

Create a working animation project and the requested MP4 or loop. Frames are deterministic functions of time, painted by p5.brush in Chrome and encoded by FFmpeg. No Claude runtime, paid API, or image-generation model is required. Clawd is an optional built-in character; follow the user's chosen cast and style.

Start a project

Resolve this skill's directory from the loaded SKILL.md location. Do not hard-code a Claude directory. Run:

python "<skill-dir>/scripts/new_project.py" "<project-dir>"

The cross-platform initializer copies template/, disconnects the demo, installs locked dependencies with npm ci, and reports tools. Use --keep-demo only for a demo or engine check, --skip-install for scaffolding only, or --npm-cli /path/to/npm-cli.js when Node is available but npm is not on PATH. NPM_CLI_JS is an equivalent environment override. It will not overwrite a nonempty project.

Read the generated ANIMATION_GUIDE.md in full before designing. Inspect docs/emotions.jpg and docs/views.jpg with an available image viewer (for example view_image via the execution tools). The guide contains the engine and character API. Read references/music-video.md for MVs or videos longer than about 20 seconds. Read references/codex-runtime.md for runtime issues, platform commands, and renderer limitations.

Plan and build

Use the user's existing choices. Ask only for missing information that materially affects the work; do not repeat answered questions. For an MV, collect the audio and timing source. A lyric video needs supplied lyrics with LRC or equivalent timestamps; do not invent missing lyrics. An instrumental MV does not need LRC. When creative direction is missing, one optional question can cover story, mood, recurring imagery, and things to avoid. If the user delegates direction, propose and proceed with a coherent interpretation.

Measure music with python "<skill-dir>/scripts/beat_grid.py" song.mp3 --from=0 --to=30 --lrc=song.lrc (requires NumPy and FFmpeg). Treat tempo as an estimate with half/double-time ambiguity; supplied audio and timestamps define timing. LRC usually times lines, so karaoke's per-character fill is an approximation unless word-level timing is supplied. Do not claim forced alignment.

Write STORYBOARD.md: logline, world and palette arc, visual motif, emotional arc, and shots with time ranges, action, viewer reads, and transitions. Share the direction for review when useful; if the user has asked you to proceed, continue. The complete worked example is examples/xiaozhen/STORYBOARD.md, with its scene files alongside it.

Set duration, bpm, offset, and optional audio in src/config.js. Implement scenes as IIFEs in src/scenes/, register shots([[t0, fn], ...]), and include their scripts in studio.html. Block readable poses first. Use a common cast, palette, and recurring motifs across shots.

Render and inspect

From the project directory, render selected frames, a short motion strip, and details when needed:

node render.mjs --sheet=0.1,0.8,1.6,2.4 --cols=4 --w=480 --out=out/check/poses.jpg
node render.mjs --strip=2.1:2.6 --out=out/check/motion.jpg
node render.mjs --sheet=2.3 --crop=760,420,500,400 --w=500 --out=out/check/face.jpg

Open the generated images. Check each shot's event and read time, faces, prop contact, character size, transitions, and palette. Inspect motion around key actions and seams. Fix observed problems, then inspect the affected frames again. A contact sheet verifies poses and continuity; inspect a short encoded preview for important motion timing. Do not claim visual review from source code alone.

Use measured ms/frame and frame count to estimate final cost. This desktop environment is local: a request to create a video normally authorizes local rendering. Respect an explicit local/cloud choice; do not add a mandatory location approval gate or use a paid/cloud service without authorization. If work is actually remote and rendering location is material, clarify before a full render. Preserve a runnable project and previews if the user requests only source or local commands.

node render.mjs --clip --out=out/video.mp4
node render.mjs --frames --workers=4
node render.mjs --encode --audio=assets/song.mp3 --out=out/video.mp4

Use the same --fps in frame rendering and encoding. Frame files are resumable, but cached frames must be removed for changed time ranges before re-rendering. --encode consumes frames starting at zero; a partial range beginning later needs its own FFmpeg start number and matching audio trim (see runtime reference).

Verify encoded duration, resolution, fps, and audio with ffprobe and inspect the result. Return the video and project paths, measured performance, and any real limitations. Keep node_modules, frame caches, and temporary files out of portable source archives.

Visual and engine invariants

• Paint with paint() and inkLine(); use glow() for additive light. Flat 2D drawn key views, soft palette, boiling ink. These are style defaults; explicit user requirements take priority.
• Avoid unnecessary text; lyric karaoke and requested lettering are supported. Load src/karaoke.js after timeline.js, fill LY, and keep action above its bottom band. Verify the actual font and Chinese glyphs.
• Every shot needs an event, cause followed by reaction, and readable held meaning. Animate faces through emotions() and idles through feel(). Fit transitions to the story and connect ending to opening when appropriate.
• Every frame is a pure function of t: no accumulated simulation, unseeded Math.random(), or dependency on render order. Use hash() for stable variation and boilSeed(key) per independent element.
• Keep helpers in scene IIFEs to avoid p5 global name collisions. Guard degenerate geometry and NaN. Mask door/window contents with foreground frames; reduce outline weight under close zoom.
• Performance depends on brush fills and strokes. Measure a few representative frames before scaling up; reduce excessive geometry and worker count when GPU memory is tight. --soft-gl is a slow fallback, not a default optimization.
• Implement chapters sequentially unless the user explicitly asks for agents. Parallel render workers are a renderer feature and do not require subagents.

Source and license: references/upstream.md. Retain both bundled MIT notices when redistributing the engine or skill.