flipbook

https://github.com/user-attachments/assets/60d42983-127c-48f8-90ed-102034ec5a94

https://github.com/user-attachments/assets/4720fa7b-ec6e-4c25-b361-1ca15e2cc42e

Claude Opus 5.5 made this from one prompt: a paper boat sails through sun, rain and snow. First try, 6.7 minutes, $1.48. 25 s, preset music.

https://github.com/user-attachments/assets/5ee87eff-1436-473b-b31a-81c74769659d

Also from one prompt: a butterfly's life on paper, egg, caterpillar, chrysalis and butterfly, each stage with its title. First try, 13.5 minutes, $2.78. 30 s, preset music.

flipbook is an agent skill for short animated films that tell a story. Your agent writes the story first, one sentence (who wants what, what stands in the way, what they end up with) told in three to six beats, then a timeline counted in beats and one HTML composition. The skill renders it frame by frame into an MP4 with music and checks the video against the story before you get it. Paper is the house look: cut paper, pencil, prints. A film about a product works the same way, one idea with the product moving the story.

It is for anyone who wants short animations from AI: intros, data animations, concept explainers, book quotes, clips cut to music.

It fixes three things that go wrong with AI-written web animation: every recording comes out different, Chinese characters drop out, and a blank video gets reported as a success.

0.x, so interfaces may change. The default look is paper: a paper ground with grain, handmade materials such as pencil hatching and halftone, handwriting drawn on canvas, and templates that build a glyph out of objects. The default sound is a score the agent writes for each film, played by synthesized instruments (piano, strings, flute, music box and more), plus four sound effects, normalized to -14 LUFS. Three quick presets (pluck, marimba, soft pad) are there for plain clips. You can go silent or bring your own music. Chinese text renders with no missing glyphs.

Characters and looks

A story needs someone to follow. There are three ways to make one, and they all move on the beat:

• Cut-paper puppets drawn in code. puppet() hangs paper parts on bones. The walk keeps the planted foot on the ground, and hands and faces swap on cue.
• Puppets from a parts sheet. Draw the parts on one sheet, or have an image model draw them. flipbook puppet finds the joints and rigs them: woodcut, gouache, crayon.
• Frame-by-frame sprites. A sheet of whole drawings, from an image model, a game asset pack or your own hand. flipbook sprite cuts it and lines the drawings up on the feet. In a walk it follows the planted foot and holds it still, and warns when it cannot. Packed game sheets are cut by their grid.

Paper is the house look, and two more sit beside it. Riso: two or three spot inks, overprinted, a little off register, tints printed as grain or halftone dots. Pixel: a small grid of cells in a few colors, blown up by a whole number, with a pixel font for the words. On macOS 14 or newer, a photo with a real background can be cut into a paper sticker too, with the Vision framework that comes with the system.

https://github.com/user-attachments/assets/f942b13d-683a-459b-9f4c-b2b1a6454716

A woodcut postman rigged from a generated parts sheet. The wind takes his letter and he chases it to the post box. About 17 s.

https://github.com/user-attachments/assets/d9371fc1-27c8-4752-b725-7462784b5c25

A sprite postman from two generated sheets walks past dark windows. One lights up, a child waves, and he waves back. 12 s.

https://github.com/user-attachments/assets/a4ac0370-f154-453a-8777-16283a554194

A pixel robot waters a mound for three days. On the fourth morning a sprout comes up. 12 s.

Install

Hand this line to your agent:

Install flipbook following https://github.com/liustack/flipbook/blob/v0.9.0/INSTALL.md, render the sample it names, and tell me the result.

Or install the skill yourself. For Claude Code:

npx -y skills add liustack/flipbook#v0.9.0 --skill flipbook --global --agent claude-code -y

For Codex:

npx -y skills add liustack/flipbook#v0.9.0 --skill flipbook --global --agent codex -y

You need Node 22.19 or newer and ffmpeg with libx264 (brew install ffmpeg on macOS, sudo apt-get install -y ffmpeg on Debian and Ubuntu). The first check or render downloads a pinned Chromium (about 95 MB) and three fonts, two Chinese and one pixel font (about 55 MB), into your user cache. To skip the npx download on every run, install the skill's renderer globally: npm install -g @liustack/flipbook@0.9.0.

From an idea to a film

You say:

Make a 20-second paper animation: a storm puts out the lighthouse lamp, and a small boat finds its way home by a child's lantern.

The agent follows the skill's steps: write story.json (who wants what, what stands in the way, what they end up with, where the film shows each, and three to six beats) and show it to you, settle the spec, write timeline.json (a scene or two per beat), write index.html, run check and snapshot and fix things until the contact sheet looks right, run render, then read the final contact sheet against the story and deliver:

bash ~/.claude/skills/flipbook/scripts/run.sh check lighthouse
bash ~/.claude/skills/flipbook/scripts/run.sh snapshot lighthouse
bash ~/.claude/skills/flipbook/scripts/run.sh render lighthouse
# lighthouse/out/video.mp4 and lighthouse/out/contact-sheet.png

Each command prints a JSON report to stdout. Every failure in it names a code and the fix and, depending on the problem, the second, the frame, the element or an evidence image. A field of timeline.json, story.json or sprite.json that fails its check is named by its path, and a file that is not valid JSON by the root, $. When the same kind of problem keeps failing, flipbook tells the agent to stop and hand you the contact sheet and the report, instead of burning through your quota.

What the checks catch

Render twice on the same machine with the same version and the raw frames match hash for hash.

Eval

Before the 0.3 release, Claude Code with Claude Opus 5.5 ran 8 prompts once each, unattended. All 8 were one-shot passes: from one sentence to a video that passed acceptance, with nobody stepping in. A run took 1.9 to 13.5 minutes and cost $0.65 to $2.78. Illustrated stories (a seed growing into a tree, the life of a butterfly) took 2 to 3 times the time and money of text and data videos. A person then went through every video and found none broken in a way the checks missed. Those cases were written for short animation in general and have since been retired: the eval now has ten new cases built around stories, characters and looks, not run yet. The new cases, how a run is judged and the old numbers are in docs/eval.md.

Support

What each platform was tested on, the sandbox settings and the memory a container needs: Platform.

What it does not do

• 3D characters. Nothing with 3D models or motion capture. Characters are flat: cut-out puppets, drawn in code or rigged from a parts sheet, and frame-by-frame sprites.
• Editing real footage. It does not cut video you shot. That is a job for a video editor or ffmpeg.
• Video from video models. Motion is drawn by code, frame by frame. Still images, generated ones included, can be material: a character's parts, a backdrop, a prop, with their source written down in assets/SOURCES.json.
• Voice-over. No text-to-speech narration yet, only music and sound effects.
• Beat detection. With your own music, you give the bpm and the second where beat 1 falls.
• Native Windows. Run it inside WSL2.
• Identical frames across machines. Frames match hash for hash on the same machine and version. Another machine or system can differ slightly.
• Taste. The checks catch broken frames, not ugly ones. The agent looks at the contact sheet before it delivers, and you have the last word.

Documentation

Contributing

Pull requests are not accepted. Issues and forks are welcome, see CONTRIBUTING.md. Report security problems privately, see SECURITY.md.

License

MIT. Licenses for third-party code, dependencies and fonts are in THIRD_PARTY_NOTICES.md.