geeklee/srt-whiteboard-animation: an SRT-driven whiteboard animation skill

What problem the SRT whiteboard animation skill solves

Most whiteboard animation tools ask you to draw on a timeline. This one asks you for a subtitle file. The README frames the whole project as "字幕驱动、逐步确认": the SRT is the source of narrative order, and every drawn element is attached to a subtitle event rather than to an absolute frame number. That is a narrow but real problem. If you already produce explainer videos, course subtitles or short-form voiceover scripts, the timing information is sitting in the SRT already, and re-entering it by hand into a video editor is the tedious part.

The intended audience is specific: knowledge explainers, story narration, course subtitle material and short-video copy, per the README's own description. The output is an MP4 drawn on a warm beige paper background, with a suggested hex of #F5EBD7, dark grey sketch lines and only small accents of red, orange and blue. The visual rules are stated as constraints, not suggestions: no scene text, no labels, no photographic look, no 3D, no complex texture.

What it is not: it does not draw your illustrations for you. The repository ships an example line art PNG, and the annotation format assumes you have a source image with integer pixel coordinates. Anyone arriving without artwork is at the wrong door.

Subtitle events, mask regions and streaming ink

The mechanism has two halves that the README names directly: mask region staging and continuous streaming ink.

The staging half lives in annotation.json. Each element gets a region in original-image integer pixels, plus sequence, subtitle and narrativeRole fields that bind it to a moment in the SRT. The README recommends ordering regions as scene setup, then key character or object, then action or change, then reaction or result. Overlap is handled explicitly: when objects occlude one another, you list the areas that must stay hidden inside the protectedRegions array of the earlier element, so later content does not leak out ahead of its cue.

The ink half is generated at render time. The README is explicit that direction and handPath in the annotation are only rectangular proxies for the preview page, and that the real stroke in the finished video is produced automatically by the streaming renderer. Each region is drawn in two passes: first ink lays down the line art, then color adds fill. The renderer exposes this as flags, with --ink-path accepting grid or skeleton and --color-fill accepting contour-wipe. The hand asset, assets/drawing-hand.png, is passed in as a positional argument, so the pen tip follows the ink as it is laid down.

The confirmation loop is the third structural piece. The README describes seven steps that each wait for approval before moving on: parse SRT, generate line art, build annotation, produce region check images, adjust in the preview page, render per scene, merge scenes. The stated reason is cost control, so that rendering is not wasted on a storyboard or annotation that is not final.

Installing the skill and rendering your first scene

The project ships its own Python virtual environment preparation script rather than asking you to install into a global interpreter. The README says to run the check first on the initial run. A successful check prints ENV_PY=<path>, and that interpreter is the one to use for all later rendering so dependencies stay isolated.

python scripts/prepare_env.py --check
python scripts/prepare_env.py

With the environment ready, the first real use is parsing a subtitle file into a suggested storyboard. The README's target window is 25 to 35 seconds per scene, defaulting to 30.

python scripts/parse_srt.py <字幕.srt> --target-sec 30 --min-sec 25 --max-sec 35

Next, generate a region check image from your line art and its annotation. The README requires the image and annotation to share a name, so scene-01-demo.png pairs with scene-01-demo.annotation.json.

python scripts/render_annotation_preview.py <图片路径> <标注路径> <预览图输出路径>

Open assets/preview.html and use the folder-open control to load the scene directory; the README says this is where you edit regions, order, timing and subtitle association. When the annotation is final, render one scene. The two style flags below are the values shown in the README example.

<ENV_PY> scripts/render_stream_whiteboard.py <图片路径> <标注路径> <输出.mp4> assets/drawing-hand.png \
  --ink-path grid --color-fill contour-wipe

Multi-scene projects merge after each scene is approved, with the merge order matching the subtitle storyboard.

<ENV_PY> scripts/merge_scenes.py --inputs 幕1.mp4 幕2.mp4 幕3.mp4 --output final.mp4

The README's quality checklist is the thing to actually look at after the first render: the first frame should be clean warm paper with no lines showing early, canvas dimensions should match the source image, and unfinished regions and protected regions should not appear in mid-render frames.

Where the pipeline breaks down

The most consequential limitation is stated by omission. The README documents a line art generation step in the workflow, but the repository's scripts directory contains parse_srt.py, render_annotation_preview.py, render_stream_whiteboard.py, merge_scenes.py and prepare_env.py. There is no renderer for illustrations among them. The workflow expects you to arrive with line art in a consistent style, and the annotation format is built around a single source image per scene with fixed canvas dimensions. If your scenes need different art, you supply it.

Second, the coordinates are absolute. Regions are integer pixels inside the original image, and the README's quality checks require canvas to match the source image size. Resizing or re-cropping artwork after annotation invalidates the regions. The example annotation uses a 1672 by 941 canvas, which is the scale the tool expects you to work at.

Third, the confirmation loop is a human-in-the-loop design, not an automation feature. Seven stages each wait for approval. For a one-off explainer that is reasonable. For a batch of fifty subtitle files it is a throughput problem, because nothing in the README describes an unattended path through the storyboard and annotation stages.

Fourth, the visual constraints are rigid by intent. No scene text, no labels, no photographic look. If your content needs on-screen labels or diagrams with text, this renderer fights you rather than helping.

How this differs from general whiteboard animation software

The obvious alternative is conventional whiteboard animation software, where you import assets and keyframe the drawing by hand on a timeline. The difference in approach is where the ordering information lives. In a timeline tool, you decide when each element appears and type the duration. Here, the ordering is derived from the SRT: sequence, subtitle and narrativeRole in annotation.json bind an element to a spoken line, and parse_srt.py suggests the scene splits in the 25 to 35 second range.

That has a practical consequence. A timeline tool can animate anything, including content with no narration. This one is only useful when subtitles exist and carry the narrative. It also means the SRT is a real dependency rather than an optional caption track: if the subtitles are wrong or badly segmented, the drawing order inherits that.

The second difference is the ink rendering. Timeline tools typically reveal a pre-drawn image through a mask, which looks like a wipe. The README describes something different: a streaming renderer that generates the actual stroke path, with an ink pass followed by a color pass, and a hand image that tracks the current stroke. The annotation's direction and handPath fields are only proxies for the editor, so the visual result is not something you can fully preview from the JSON alone.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-07-27. The only listed release is v1.0.0, published the same day, described as the first public release of the skill. That is a young project with a single release tag, so the practical upgrade question is not about migrating between versions but about whether the annotation schema and script interfaces stay stable as the project moves past its first release.

The annotation format is the coupling point. If element fields such as sequence, subtitle, narrativeRole, reveal and protectedRegions change shape, every existing annotation.json has to be rewritten by hand, because the README documents no migration script and no version field in the annotation example. Keeping your SRT files and source PNGs alongside the annotations is the cheap insurance here.

Licensing is MIT, per the README and the LICENSE file at the repository root. That permits commercial use and modification with attribution, but the repository does not state a policy on the bundled assets. assets/drawing-hand.png and the example artwork under examples/ ship with the project, and the README does not record their provenance or any separate terms. If you plan to reuse the hand asset or the example art in published work, confirm their status with the maintainer rather than assuming the MIT text covers them. This is a question about the project's own files, not legal advice.

Environment cost is low but real: prepare_env.py builds an isolated virtual environment, and the README instructs you to render with the interpreter it prints. Expect to re-run the check if that environment is rebuilt.

Editorial conclusion

Adopt it if you already own line art and an SRT file and want the drawing order tied to subtitle events rather than to manual keyframes: the annotation schema in annotation.json makes sequence, subtitle and narrativeRole explicit, and the preview.html page lets you fix regions before paying for a render. Do not adopt it if you need a drag-and-drop drawing app or have no artwork to animate, because the README describes no illustration generation of its own. Before committing, run python scripts/prepare_env.py --check and confirm it prints ENV_PY=<path>; then render one scene with render_stream_whiteboard.py and inspect the first frame for warm paper and no early lines.

Frequently asked questions

Official sources

1. geeklee/srt-whiteboard-animation on GitHub
2. Issues
3. License: MIT
4. README
5. Releases