Whiteboard Animation Works When Drawing Order Follows the Story

A whiteboard animation can be drawn in the correct order and still tell the wrong story. If a background object appears after the character who depends on it, or if a punchline is visible before the subtitle reaches it, the viewer has to reconstruct the sequence instead of following it. The useful design unit is not the coordinate rectangle. It is the narrated event.

SRT Whiteboard Animation is built around that distinction. Its README describes a subtitle-driven workflow that parses SRT, splits a script into scenes, maps visible elements to semantic drawing order, and renders each region as a continuous stroke. Its SKILL.md makes the composition rules explicit: a scene should move from setup to subject, then to action or change, then to reaction or result. Coordinates still matter, but they serve the narrative rather than replacing it.

The frame is a stage, not a spreadsheet

It is tempting to annotate an illustration from left to right. That approach is easy to explain and easy to implement: sort the boxes by their x-coordinate, reveal them in that order, and let the hand travel across the canvas. It fails whenever the image has a different logic. A mountain on the right may be the setting for a character on the left. A small object in the center may be the cause of the action. A group of observers may belong at the end even though they occupy the nearest empty area.

The repository's annotation model separates spatial facts from story facts. Each element has an integer-pixel region, but it also has a sequence, subtitle, and narrativeRole. The region says where the marks are. The other fields say why those marks should appear now. That is a modest schema change with a large creative consequence: the timeline can be edited without redrawing the source image, and an element can be moved in the narrative without pretending that its visual position changed.

Consider the README's example scene: a small monkey sits on a rocky mountain with a banana, a larger monkey takes the banana, and children watch. A coordinate-first plan might draw the mountain because it is large, then whichever monkey is closest to the next empty space, and finally the children. A semantic plan is more specific:

Setup: establish the rocky setting and the small monkey's starting situation.
Key object: make the banana legible as the thing being held.
Change: introduce the larger monkey and the act of taking it.
Result: reveal the children as witnesses to the completed action.

The second plan gives the viewer a question and answers it in order. What is the situation? What matters inside it? What changes? Who reacts? This is why semantic drawing order beats coordinates: it controls attention and causality, not just hand movement.

Turn subtitle events into visual beats

SRT timing gives the project a natural editorial spine. The repository recommends splitting scenes around 25 to 35 seconds, but that range is not a license to fill a scene with unrelated objects. Each scene should express one core idea. A thirty-second scene can contain several reveals when they belong to one action; a ten-second scene can be overloaded if it introduces a setting, three characters, a diagram, and a conclusion.

Start with the subtitle text and extract verbs, participants, objects, and consequences. “A small monkey sits on the mountain” contains a setting, a subject, and a state. “The large monkey grabs the banana” introduces an agent, an object, and a change. “The children watch” is not another decoration; it is the reaction that closes the beat. Those distinctions should become annotation records, not merely notes in a production document.

The subtitle field on an element is valuable because it keeps the visual reveal tied to the exact spoken event. If a later edit moves the banana before the grabbing action, the mismatch is visible in the data. The preview editor can show the relationship between modules and subtitle text, while sequence and startMs make the intended order inspectable without watching a full render.

A practical timing pass looks like this:

Reserve the opening for the first stable fact the viewer needs. Do not spend it on decorative texture.
Give important objects enough time to be drawn and recognized before the next action begins.
Keep regions serial when the effect is a single moving hand. The SKILL specifies that later regions should begin after the previous region ends, with a short optional breathing gap.
Leave at least half a second at the end of a scene for the complete drawing to settle before the next scene.

This produces a narration that feels like thinking on paper. A character does not merely materialize; it becomes relevant at the moment the sentence makes it relevant.

Why protectedRegions solve the hard occlusion cases

Rectangles are convenient proxies, but they are blunt. A region around a mountain may include the sky above it. A region around a person may include the space occupied by a later prop. If the renderer freely draws every pixel inside the current rectangle, a later object can leak into the animation before its reveal time. The problem is not only visual overlap. It is a broken promise about what the viewer is allowed to know.

SRT Whiteboard Animation handles this at the orchestration layer. For a region, the allowed drawing mask is its rectangle minus the regions of later modules, and then minus any additional protectedRegions. The latter use the same integer pixel coordinate format as the main region. They are explicit holes in the current drawing permission. A stream stroke can continue through the current area while being prevented from touching a later character, prop, or fragile contour.

Imagine a wide rockery drawn first, with a larger monkey partly overlapping its right edge. The rockery needs a generous box so its contour can be drawn naturally. That box would also cover part of the larger monkey. Put the monkey's rectangle in the rockery's protected regions, or use a tighter protected subregion when only the face and hand overlap. The rockery can still appear as the setting, but the later actor remains genuinely absent until the subtitle introduces the theft.

This is better than drawing the foreground object first and hiding it with a temporary wipe. A wipe can make the final frame correct while leaving the reveal logic difficult to reason about. A protected region states the invariant directly: this earlier element may draw here, but not in the pixels reserved for a later event. The preview's destination-out treatment and the renderer's allowed-mask calculation then have a common interpretation.

Protection is also useful for accidental background leakage. A hand-drawn source image may contain a long baseline, a loose contour, or a shadow that crosses another module's space. If the line is allowed to stream across the whole rectangle, the viewer may see a fragment of a future object or infer a relationship too soon. Marking that crossing as protected is often safer than trying to make the source illustration unnaturally disconnected.

There is a limit, however. More protected regions mean more annotation work and more opportunities to hide legitimate strokes. They should describe real narrative occlusion, not become a substitute for a badly composed image. If every object needs a complicated maze of exclusions, redraw the source with clearer separation or split the scene. A mask can preserve timing; it cannot repair an illustration whose forms are inseparable.

Design source images for controlled reveals

The source image determines how much freedom the timeline will have. The project's visual rules are deliberately restrictive: warm paper around #F5EBD7, dark gray sketch lines, and small accents of red, orange, or blue. The image should be a minimal hand-drawn illustration with a clean background, generous empty space, and no text, labels, letters, numbers, photorealistic detail, 3D treatment, or dense texture.

Those constraints are not just an aesthetic preference. A whiteboard renderer needs visual separability. Simple contours are easier to assign to regions, easier for a grid or skeleton path to follow, and easier for a viewer to recognize while incomplete. Dense shading produces hundreds of incidental marks with no obvious narrative owner. A label can explain a diagram in a static image but becomes a spoiler when it is visible from the first frame.

Compose the image as a set of actors and relationships. Leave a real gap between the setting and the foreground subject. Keep a prop close enough to its owner that the connection reads when both are present, but not so entangled that the prop cannot be protected. Put reaction figures in their own visual pocket. Avoid a background line that runs behind every object; it creates a mask problem and makes the drawing feel like one undifferentiated layer.

It helps to think in terms of revealable silhouettes:

Setting: one or two broad shapes that establish place and scale.
Subject: a simple figure or object whose pose communicates the initial state.
Trigger: the small item, gesture, or second actor that changes the situation.
Consequence: a visible reaction, destination, or altered pose.

Use color sparingly and assign it meaning. A red accent can mark the contested object; blue can separate a secondary actor; orange can draw attention to a change. Do not use color to compensate for weak sequencing. If the banana is only understandable because it is bright yellow against a busy scene, the source is already asking too much of the animation.

There is a productive tradeoff between a beautiful static illustration and an animatable one. A polished image often relies on overlaps, subtle shading, and carefully balanced detail. A good whiteboard source sacrifices some of that richness so each stroke can carry a role. The result may look plain as a PNG, yet become more expressive when the hand builds it in time. Judge the source at three moments: the empty paper, the half-drawn scene, and the completed frame. If the middle state is confusing, simplify before annotating.

Continuous ink changes the meaning of a region

The project does not reveal rectangles as if a slideshow were uncovering tiles. Each region is rendered as a continuous stream of strokes, with an ink phase for the line work followed by a color phase. The default ratio in the SKILL is two parts ink to one part color. A grid path is the stable default, while a skeleton path can follow a clear line drawing more closely; contour-wipe and brush are the available color-fill styles.

This matters for composition because a region is not merely a visibility switch. It is a small performance. The hand has to enter the area, establish the contour, and leave enough of the object readable before the next semantic event takes over. A huge background region can consume the whole scene if it contains too many paths. Conversely, a tiny but important prop may deserve a deliberate pause even though its box is small.

Keep the regions conceptually coherent. One region for an entire crowd may be efficient, but it removes the ability to make the first witness appear before the second. Splitting every limb into its own region is the opposite mistake: it creates mechanical timing and distracts from the spoken line. The right boundary is usually an event-bearing unit, not an individual shape.

The distinction between preview and final rendering also deserves attention. direction and handPath control the rectangle proxy in the preview editor; the actual stream renderer generates the real stroke path. They are useful for testing order and timing, but they are not a promise that the final hand will travel exactly from the declared start point to the end point. Treat the preview as an editorial instrument, not a frame-accurate animation simulator.

Coordinates still matter, just later

Rejecting coordinate-first composition does not mean ignoring geometry. The annotation format requires the canvas size to match the source image, and every region and protection rectangle must use integer pixel coordinates inside that canvas. That precision prevents a common class of production errors: a mask aligned to a resized image, a hand path outside the frame, or a protection hole that misses the object by a few pixels.

The better order is semantic first, geometric second. Identify the event sequence from the subtitles. Identify the visible object that expresses each event. Then measure the rectangle that safely contains that object, leaving room for its stroke while excluding later content where possible. Finally, add protection for the overlaps that remain. This sequence prevents the annotation tool from dictating the story simply because its boxes are easy to drag.

Use the preview stage to test three questions. Does the first frame show only paper? At the midpoint, are future modules completely hidden, including stray contours? At the end, is the full source image present and held long enough to read? The repository's quality checks call out those exact failure points, including a clean opening, protected overlaps, and a complete final frame. A scene that passes only the last check is not finished.

Where the approach pays off, and where it does not

This workflow is a strong fit for explanatory narration, short lessons, story beats, and product concepts that benefit from progressive understanding. SRT supplies timing, semantic annotations supply causality, masks prevent spoilers, and stream drawing gives the result a human pace. The same separation also makes revision cheaper: a change to subtitle wording or event order can often be handled in annotation JSON without generating a new illustration.

It is less suitable when the source depends on exact typography, photorealistic continuity, fast simultaneous motion, or a large number of independently moving parts. The rules forbid text in the source image, so a diagram that truly requires labels needs another treatment. Serial drawing is also slower than a conventional cut when several facts must arrive at once. You can create the illusion of concurrency with careful scene boundaries, but the renderer's model is still a single ordered stream.

There is an engineering cost as well. Every scene needs subtitle segmentation, a source image, annotation, preview, and render checks. Protected regions add a second layer of spatial reasoning. The project deliberately includes confirmation gates—strategy, line art, annotation, preview, final timing, and rendered scenes—because a late mask correction is more expensive than an early composition correction. Skipping those gates may feel faster on a simple test, but it removes the point at which a bad narrative order is cheapest to fix.

For a small project, a disciplined manual annotation pass is usually a better investment than building an automatic object sorter. Automatic sorting sees boxes; it does not know that the object in the lower corner is the consequence of the sentence rather than its setting. The repository's design leaves automation where it is reliable—SRT parsing, previews, stream rendering, and scene merging—and leaves narrative judgment visible in the annotation fields.

A composition checklist for the final render

Before exporting, read the scene as both an editor and a renderer. Confirm that the subtitle event represented by each element matches its narrativeRole. Check that sequence begins at one and has no gaps, and that startMs values produce a serial drawing when the scene calls for one. Verify the canvas dimensions and all integer rectangles. Then inspect the opening, an overlapping middle reveal, and the completed ending.

At the opening, the viewer should see warm paper rather than a faint preview of the finished image. During the middle reveal, the current hand should stay near the active stroke, later objects should remain hidden, and protected zones should not expose a contour or fill early. At the ending, the drawing should be complete and held for at least half a second. For multiple scenes, merge only after the individual MP4s have passed those checks; otherwise a sequence error becomes harder to locate after concatenation.

The central rule is simple: draw what the sentence makes meaningful, not what happens to be closest to the cursor. Coordinates define the stage, but semantic sequence defines the performance. With a restrained source image and explicit protected regions, a whiteboard animation can reveal an idea one necessary mark at a time instead of displaying the answer before the question has been asked.