Communitygithub.com

Pulupulu Motion

Directs a motion film as an HTML and GSAP timeline, screenshots it frame by frame in headless Chrome, and muxes narration and music with ffmpeg.

What is Pulupulu Motion?

Checks that Node, ffmpeg, and the pulupulu CLI are present, then builds flat vector scenes, type, charts, and maps. It refuses jobs that need a real face, lip-sync, or continuous physical action.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Alucard0x1/pulupulu-motion/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does Pulupulu Motion do?

A film here is a timeline in HTML that Chrome renders frame by frame. Nothing is a video editor: you write a page, the CLI screenshots it at a fixed frame rate, ffmpeg muxes the sound.

This file is the router. It answers: may I do this job, what do I run first, what has to pass, and which page has the detail. Load a reference page only for the part you are working on.

1. Before promising anything

python scripts/doctor.py                    # read-only: python, node, ffmpeg, the CLI, key, disk
python scripts/doctor.py --project film/    # also: the page contract is present

Exit 1 means a film cannot be made on this machine. Do not discover that after writing scenes. Never call npx per command: a network round trip on every check, still and render is the most common self-inflicted slowdown in this workflow.

This tool is the wrong choice when the story needs footage it does not have, a real person's face or likeness, articulated human or animal anatomy, a physical action performed continuously, or lip-sync. It renders flat vector geometry, type, charts, maps, icons and colour-coded objects well, and those other things badly. Say so instead of producing a lookalike: a drawn stand-in for archival material is a provenance problem, not a style choice.

2. The workflow, in order

One beat = one sentence = one shot. Timing comes from measured speech, never from invention.

  1. Brief. Subject, audience, platform, language, whether there is narration. Ask for a missing subject; do not ask whether to narrate when a video was requested.
  2. Storyboard before HTML — references/narration-and-captions.md. The caption is the verbatim spoken words, not a summary of them.
  3. Narrate and measure. python scripts/deepseek_voice.py beats beats.json film/assets/voice.wav --voice stella --timeline timeline.json, then gate to check every phrase by ASR. Route, voices and limits: references/narration/deepseek-tts.md.
  4. Build the page from timeline.json, not from the storyboard. Contract: references/cli.md. When the story needs objects no icon library carries, generate them as print panels first — references/generated-assets.md — and assemble those; never hand-draw a stand-in for a photograph.
  5. Check, then look. pulupulu check ., then pulupulu still . --at 2,12,24 --out .om/stills and open the stills. A page that passes check can still render blank.
  6. Render — pulupulu render . --format mp4 --fps 30. Stalls, black frames and wrong lengths: references/render-traps.md.
  7. Mix and mux with explicit stream mapping — scripts/deliver_check.py --video out/film-vN.mp4 --audio assets/mix.wav --out out/final.mp4 muxes and validates in one call. Manual recipe and the ducking chain: references/workflow.md.
  8. Validate the file you will deliver, not the renderer's newest output: python scripts/deliver_check.py out/film.mp4 --timeline timeline.json.
  9. Deliver with honest caveats: what is drawn rather than sourced, and what the QA note says.

3. Gates

Only these block. Everything else a tool prints is a reading note: answer it with an argument or fix it, but never report it as passed when it was not.

gatecommandwhat it provesif it fails
preflightpython scripts/doctor.pythe machine can renderstop, report what is missing
compositionpulupulu check .page contract, no missing filefix before rendering
languagepython scripts/lang-audit.py film/index.html --lang enno text in the other language, including string literals inside <script>translate the literal, re-run
speechpython scripts/deepseek_voice.py gate beats.json --voice stellaevery phrase transcribes back to its own wordsrewrite the phrase; never ship a fragment
filepython scripts/deliver_check.py out/film.mp4 --timeline timeline.json (or --video/--audio/--out to mux first)frame size, frame rate, audio present and long enough, true peak, delivery sizere-mux or re-encode
popspulupulu qa out/film.mp4no single-frame popsfind the one-frame element

pulupulu qa also reports motion per second, still for ≥ 1 s and flat opening. Those are judgements about pacing, measured on a 96×54 greyscale comparison, so a low-contrast slow move can read as still. Use them as a reason to look, not as a verdict to obey.

What no gate proves: that the film is good, that ASR heard the right number (check digits and proper nouns as tokens), or that a caption sits where a platform's UI will not cover it.

4. Traps that cost a render

Full detail and fixes in references/render-traps.md. The ones that stop a render dead:

  • Raw <g>/<rect>/<path> written into a <div> renders nothing and warns nothing. Wrap every scene fragment in its own <svg viewBox>.
  • A webfont inside inline SVG <text> re-rasterises that layer every frame. Put text in HTML, or draw it as shapes.
  • feTurbulence as a per-frame filter — inline SVG or a CSS background — stalls the renderer. Bake the noise into a PNG tile once.
  • A full-frame GSAP scale on an inline SVG re-rasterises the plate; translate composites fine, and a bitmap layer can be scaled. When a push is impossible, animate small inner groups.
  • repeat: -1 makes the timeline infinite: an 87 s film silently becomes 117 s. Compute finite laps.
  • After a failed render, kill only the headless Chrome it left behind. taskkill //IM chrome.exe closes the user's own browser.

5. Where the detail lives

working onpage
commands, page contract, installreferences/cli.md
the nine steps, project contract, muxreferences/workflow.md
storyboard, captions, one-language gatereferences/narration-and-captions.md
palette, element budget, personality, rhythmreferences/design-taste.md
motion languages, techniques, 3D layerreferences/motion-library.md
punch-up, product demo, talking head, grammarsreferences/workflows-specialized.md
music worlds, composer, sfx, narration synthesisreferences/audio-and-music.md, references/narration/deepseek-tts.md
a blank, stalled or wrong-length renderreferences/render-traps.md
what to check, and in what orderreferences/verification.md
style recipes, camera languagereferences/art-motion/INDEX.md
sourcing icons and vectors, licencesreferences/asset-sourcing.md
art generated by an image model, cropping prints, mountingreferences/generated-assets.md
flat-vector craft, scrolling worldsreferences/2d-vector-motion.md
which subjects this renderer can carryreferences/topic-fit.md
timing and easing at sub-second levelreferences/ui-motion/
publishing this skill (one commit, v1.0)references/publishing-skills.md, references/publishing.md

The style-recipe route (scripts/art-motion/engine/) is 20 MB of vendored runtime that is deliberately not in this repository: a skill should not make every agent fetch an engine it may never use, and a 37 MB tree cannot be reviewed. It installs pinned and checksum-verified, onto the exact paths the pages above cite:

python scripts/install_art_motion.py --check                   # is it there?
python scripts/install_art_motion.py                           # core: lib + demos + scenes, 20 MB
python scripts/install_art_motion.py --with-reference-films    # + study material, 14 MB more

Everything else — the Python gates, the clip specs, the documentation — is in the repository and needs no install. Never commit the fetched tree back: .gitignore already covers it.

6. Scripts

scriptdoes
scripts/doctor.pypreflight, read-only
scripts/deepseek_voice.pyprobe · speak · cost · lay · beats · asr · gate — narration and its measured timeline
scripts/deliver_check.pyvalidates the delivered file: size, rate, audio, peak, duration against the timeline
scripts/lang-audit.pyone-language gate over markup and script literals
scripts/art-motion/icon_audit.pyicon families, colour count, contact sheet
scripts/art-motion/qa.pypacing and pop heuristics on a rendered file
scripts/stamp_credit.pyadds the by Alucard0x1 line to text files

7. Working with a person

Show frames, not adjectives. One hero frame per act kills a week of wrong work. When they correct you, put the correction into this skill rather than into a chat reply.

Handoffs: narration timing and prosody → skill tts-intonation · merging or translating another library → skill agent-skill-sourcing · rights and likeness before publishing → skill media-content-safety · sourcing a reference video → skill streaming-mirror-extraction · 3D or footage-based shots → skills headless-three-video-render and cinetic · type-first films → skill kinetic-typography.

Related Skills