@algorisys/tinyfly 0.91.0 → 0.93.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2785 -1794
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6575 -5454
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +4 -0
  54. package/lib/types/characters/species/human-motion.d.ts +45 -0
  55. package/lib/types/characters/species/human.d.ts +2 -0
  56. package/lib/types/characters/stick-figure.d.ts +2 -0
  57. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  58. package/lib/types/engine/authoring/index.d.ts +1 -0
  59. package/llms-full.txt +12548 -0
  60. package/llms.txt +57 -0
  61. package/package.json +6 -2
  62. package/skills/tinyfly/SKILL.md +64 -0
  63. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,728 @@
1
+ # Rendering Video from Code
2
+
3
+ tinyfly can render a complete animation to an MP4 **without a browser**: write a
4
+ scene in JavaScript, run one command, get a video (plus captions and PNG stills
5
+ for checking). This is the workflow of Cairo or Processing scripts, with
6
+ tinyfly's timeline, easing and JSON on top.
7
+
8
+ ```bash
9
+ npm install @algorisys/tinyfly @napi-rs/canvas # @napi-rs/canvas: the 2D canvas for Node
10
+ # ffmpeg must be on the PATH
11
+
12
+ npx tinyfly video scene.mjs -o scene.mp4 --srt scene.srt
13
+ npx tinyfly video scene.mjs --stills stills/ # one PNG per caption line (else per marker step)
14
+ npx tinyfly video scene.mjs --stills stills/ --frames 0,79,88 # stills at chosen frames (or --times 0,2640 in ms)
15
+ npx tinyfly video scene.mjs --loop-check # does it loop? (exit 1 when not)
16
+ npx tinyfly video scene.mjs --scale 0.5 --fps 12 # quick preview
17
+ ```
18
+
19
+ Runnable scenes are in [`examples/headless-video/`](../examples/headless-video/):
20
+ a narrated stick figure (`stick-figure.mjs`), a bar chart made only of timeline
21
+ targets (`bar-chart.mjs`), a pure immediate-mode sketch (`cairo-style.mjs`) and a
22
+ pencil-test gag on notebook paper with boiling lines (`pencil-sketch.mjs`), an
23
+ eraser gag that rubs out the figure's arm and then the ground under it (`eraser-gag.mjs`),
24
+ squash, stretch and rubber-hose limbs in a jump and a noodle-arm wave (`rubber-hose.mjs`), and
25
+ the animator's hand drawing the ground and a sun, then erasing the sun (`drawing-hand.mjs`).
26
+ The Examples gallery's **Video** category has a **Narrated Scene** card that
27
+ plays the same idea live in the browser, a **Stick Figure** card for trying
28
+ the poses, a **Pencil Sketch** card that plays the drawing-hand gag live with
29
+ toggles for the pencil, the boil rate and rubber limbs, and a **Dressed Stick
30
+ Figures** card: costumes, hair and props drawn with `layers`, a figure that walks
31
+ in turned, sits on a charpai, and a speech bubble that follows a head.
32
+
33
+ ## The scene
34
+
35
+ A scene module default-exports a `VideoScene` (or a function, sync or async,
36
+ that returns one):
37
+
38
+ ```js
39
+ export default {
40
+ width: 1920,
41
+ height: 1080,
42
+ fps: 30, // default 30
43
+ duration: 5000, // ms; defaults to the timeline's duration
44
+ timeline, // a TimelineDefinition (plain JSON)
45
+ targets: { … }, // canvas targets the timeline animates, by id
46
+ background: '#fff', // a colour, 'transparent', or a draw function
47
+ draw(ctx, frame) { … }, // immediate-mode drawing over the targets
48
+ audio: 'narration.wav', // muxed in; relative to the scene file
49
+ fonts: { Poppins: 'fonts/Poppins-Bold.ttf' },
50
+ captions: [ { start, end, text } ], // default: from the timeline's markers
51
+ bloom: true, // a glow around bright things (see Bloom)
52
+ }
53
+ ```
54
+
55
+ Every frame is drawn from scratch at an exact time (`frame / fps`): background,
56
+ then the targets at the timeline's state, then `draw`. The output is
57
+ deterministic: the same scene renders the same pixels, in any frame order.
58
+
59
+ There are three ways to draw, and they mix freely:
60
+
61
+ | | What it is | Good for |
62
+ |---|---|---|
63
+ | **Targets** | `rect`, `circle`, `text`, `line`, `path`, `image` animated by timeline tracks | Anything the editor can make; stays pure data |
64
+ | **Custom targets** | A target whose `draw` function is code; the timeline animates its values | Characters, charts, props: drawn by code, driven by keyframes |
65
+ | **`background` / `draw`** | Functions of `(ctx, { time, index, state, stateAt, width, height })` (`stateAt(t)`: the timeline's state at any other time, for trails) | Backdrops, captions, one-off effects, porting Cairo scripts |
66
+
67
+ ## Custom targets
68
+
69
+ A `custom` canvas target is drawn by a function, but positioned, faded, rotated
70
+ and scaled like any other target, and its own values are animated by tracks:
71
+
72
+ ```js
73
+ const figure = {
74
+ type: 'custom',
75
+ x: 500, y: 300, width: 120, height: 300, // the box is the transform pivot
76
+ props: { arm: 0, mouth: 0 }, // values tracks may animate
77
+ draw(ctx, target, time) {
78
+ // ctx is already translated to (x, y), with opacity/transforms applied
79
+ const { arm, mouth } = target.props
80
+ …
81
+ },
82
+ }
83
+ ```
84
+
85
+ A track whose `property` is a key of `props` writes into `props`; `x`, `y`,
86
+ `opacity`, `rotate`, `scale` and the other base properties work as for every
87
+ canvas target. Only keys declared in `props` are routed there, so every animated
88
+ value is listed up front. This works in the browser too: `CanvasAdapter` renders
89
+ custom targets anywhere.
90
+
91
+ ## Timing from narration
92
+
93
+ For a narrated video, the voice sets the timing. `planNarration` lays out scenes
94
+ of spoken lines from their clip lengths, with a lead before each scene's first
95
+ line, a gap between lines and a tail after the last:
96
+
97
+ ```js
98
+ import { planNarration, narrationMarkers, narrationSceneAt } from '@algorisys/tinyfly'
99
+
100
+ const plan = planNarration(
101
+ [
102
+ { id: 'intro', lines: [{ text: 'Meet the figure.', duration: 1400 }] },
103
+ { id: 'wave', lines: [{ text: 'It waves,', duration: 1200 }, { text: 'and talks.', duration: 1500 }], tail: 400 },
104
+ ],
105
+ { lead: 350, gap: 300, tail: 550 } // the defaults, in ms
106
+ )
107
+
108
+ plan.duration // total ms
109
+ plan.scenes // [{ id, start, duration, cues }]
110
+ plan.cues // [{ id: 's0-l0', scene, line, start, end, text }, …]
111
+ narrationMarkers(plan) // one marker per line: { id, time, label }
112
+ narrationSceneAt(plan, time) // the scene playing at a time
113
+ ```
114
+
115
+ Use `cue.start` / `cue.end` as keyframe times, put `narrationMarkers(plan)` in
116
+ the timeline's `config.markers` (stills and players step through them), and pass
117
+ `captions: plan.cues` so the caption file covers exactly the spoken spans. The
118
+ audio must be assembled with the same pauses, or from the cue times.
119
+
120
+ ### From recorded lines
121
+
122
+ With a voice-over recorded (or synthesised) one clip per line, let the clips set
123
+ the timing. `voiceNarration` decodes every clip with ffmpeg, measures it from its
124
+ samples, lays the lines out with `planNarration`, and writes the whole narration
125
+ as one WAV whose lines start exactly at their cue times:
126
+
127
+ ```js
128
+ import { voiceNarration } from '@algorisys/tinyfly/headless'
129
+
130
+ const { plan, audio } = await voiceNarration(
131
+ [
132
+ { id: 'intro', lines: [{ text: 'Meet the figure.', audio: 'voice/01.wav' }] },
133
+ { id: 'wave', lines: [{ text: 'It waves,', audio: 'voice/02.wav' }, { text: 'and talks.', audio: 'voice/03.mp3' }] },
134
+ ],
135
+ { output: 'build/narration.wav', baseDir: new URL('.', import.meta.url).pathname, sampleRate: 48000 }
136
+ )
137
+
138
+ export default { /* …timeline built from plan… */ audio, captions: plan.cues }
139
+ ```
140
+
141
+ Scene modules may use top-level `await`, or default-export an async function.
142
+ `assembleNarration(plan, clips, sampleRate)` and `encodeWav(samples, sampleRate)`
143
+ are the pure steps underneath, for audio you generate yourself.
144
+
145
+ ## Characters
146
+
147
+ `@algorisys/tinyfly/characters` has a poseable stick figure. A pose is a set of
148
+ numbers (joint angles in degrees, plus the face: eyes, brows, mouth and gaze), so
149
+ poses blend and every joint can be a timeline track. It is also on the script-tag
150
+ bundle's `tinyfly` global (`tinyfly.drawStickFigure`, `tinyfly.POSES`, …):
151
+
152
+ ```js
153
+ import { stickFigureTarget, poseTracks, POSES } from '@algorisys/tinyfly/characters'
154
+
155
+ targets: {
156
+ hero: stickFigureTarget({
157
+ x: 640, y: 620, // where the feet stand
158
+ style: { height: 340, color: '#1e3a8a', headFill: '#f2c49b', label: 'HERO', facing: 1 },
159
+ }),
160
+ },
161
+ timeline: {
162
+ id: 'hero',
163
+ config: { duration: 4000 },
164
+ tracks: [
165
+ ...poseTracks('hero', [
166
+ { time: 0, pose: 'rest' },
167
+ { time: 400, pose: 'wave', easing: 'ease-out' },
168
+ { time: 2000, pose: { rightShoulder: 90, rightElbow: 0 } }, // changes from the last key
169
+ { time: 2600, expression: 'surprised' }, // only the face changes
170
+ { time: 3200, pose: 'shrug', expression: 'confused' }, // body and face
171
+ ]),
172
+ // Walking and talking are props too
173
+ { id: 'walk', target: 'hero', property: 'walk', keyframes: [{ time: 0, value: 0 }, { time: 2000, value: 3 }] },
174
+ { id: 'walking', target: 'hero', property: 'walking', keyframes: [{ time: 0, value: 1 }, { time: 2000, value: 0 }] },
175
+ { id: 'talk', target: 'hero', property: 'talk', keyframes: [{ time: 2000, value: 1 }, { time: 3500, value: 1 }] },
176
+ ],
177
+ },
178
+ ```
179
+
180
+ | | |
181
+ |---|---|
182
+ | `POSES` | `rest`, `wave`, `cheer`, `shrug`, `point`, `think`, `handsOnHips`, `sad`, `surprised`, `crouch` (squashed), `jump` (stretched), `sit` (seated, hands on the knees) |
183
+ | `EXPRESSIONS` | `neutral`, `happy`, `joyful`, `sad`, `crying`, `surprised`, `shocked`, `angry`, `furious`, `worried`, `scared`, `confused`, `skeptical`, `thinking`, `sleepy`, `disgusted`, `smug`, `wink` |
184
+ | `withExpression(pose, face)` | The pose with its face replaced: a name, or face fields to change |
185
+ | `pose(changes)` | A full pose from the joints that differ from rest |
186
+ | `blendPose(a, b, t)` | Linear blend of two poses |
187
+ | `walkPose(phase, base?, stride?)` | A stride at `phase` (0 → 1 is one cycle): legs scissor, hanging arms swing against them; raised arms and the face keep `base` |
188
+ | `strideLength(height)` | Ground one walk cycle covers; set `walk` to distance / stride length (with the same easing as `x`) so the feet stay planted |
189
+ | `talkingMouth(time)` | A deterministic 0..1 chatter |
190
+ | `drawStickFigure(ctx, pose, style, time?)` | Draw with the feet at (0, 0), for `draw` functions; `time` picks the boil frame of a `sketch` style |
191
+ | `sketchPen(ctx, sketch, time)` | Hand-drawn `line(points)`, `curve(points)`, `circle(cx, cy, r)` and `ellipse(cx, cy, rx, ry)` strokes with line boil; each takes a last `progress` (0..1) to draw it on |
192
+ | `stickFigureTarget({ x, y, pose, style })` | A `custom` target whose props are the pose plus `walk`, `walking`, `talk`, `rubber` |
193
+ | `rubberLimb(root, joint, end, rubber)` | Points along a limb, from jointed (0) to a rubber-hose curve through the joint (1) |
194
+ | `stickFigureJoints(pose, style?)` | Where every joint, limb and the head are, as drawn, without drawing (see [Costumes, hair and props](#costumes-hair-and-props)) |
195
+ | `resolveStickPose(props, time)` | The pose a `stickFigureTarget` draws at `time`, with `walk`/`walking` and `talk` folded in |
196
+ | `stickFigureAt(target, frame, id)` | A target's pose and scene-space joints in a frame, for `draw(ctx, frame)` |
197
+ | `jointsToScene(joints, x, y)`, `headPoint(head, x, y)` | Move joints to where the feet stand; a point on the head in head units |
198
+ | `seatHeight(height, stretch?)` | Height of the hips above the feet when fully seated: where a bench top goes |
199
+ | `taperedLine(ctx, points, from, to)` | Fill a line whose width tapers along a polyline (limbs, sleeves, trouser legs) |
200
+ | `poseTracks(target, keys)` | Tracks for a sequence of named or partial poses, each optionally with an `expression`; only fields that leave rest get a track |
201
+
202
+ ### The look
203
+
204
+ By default the figure is drawn **organic**: limbs taper from root to tip,
205
+ elbows and knees are always a little rounded (as `rubber` 0.3, more if you set
206
+ more), it has small hands and feet, the lower foot always rests on the ground (so
207
+ a walk bobs as the stride opens and closes), and the body leans forward as it
208
+ sits down or stands up. Seen from the front the feet turn out, each to its own
209
+ side; as the figure turns (`turn`) they swing round to the way it faces. They tip
210
+ with the shin, so a trailing foot rolls onto its toe.
211
+
212
+ `style: { classic: true }` draws the 0.75 look instead: even strokes, sharp
213
+ joints, no hands or feet, and the hips at a fixed height (feet can float off the
214
+ ground mid-stride). It draws exactly what 0.75 drew for the same pose, so
215
+ existing videos can keep their look. A `sketch` style uses pencil strokes in
216
+ either look.
217
+
218
+ `walkPose` also leans into the walk and lets each forearm follow through as its
219
+ arm swings forward.
220
+
221
+ **Brush and head size.** `lineWidth` (px, default 2.5% of the height) sets the
222
+ brush; the bold look of viral stick-figure videos is around 4–5%.
223
+ `headSize` is the head's diameter as a fraction of the height (default 0.24);
224
+ a bigger head (0.3) leaves more room for the face and takes its height from the
225
+ torso, so the feet and hips stay put. Face lines are lighter than the body's and
226
+ capped by the head size, so a thick brush never blots out the eyes and brows.
227
+
228
+ ```js
229
+ style: { height: 400, lineWidth: 400 * 0.045, headSize: 0.3 }
230
+ ```
231
+
232
+ Angles are degrees from hanging straight down; positive raises a limb outward.
233
+ Elbows add to the upper arm's angle (past 180° the forearm folds back in), and
234
+ knees swing the shin back toward the centre. The module is browser-safe, so the
235
+ same figure draws on a web page's canvas.
236
+
237
+ ### Faces
238
+
239
+ Every face feature is a number too, so expressions blend and animate like joints:
240
+
241
+ | Field | Range |
242
+ |---|---|
243
+ | `leftEye`, `rightEye` | 0 shut, 1 normal, up to 1.6 wide (the whites show above about 1.2) |
244
+ | `blink` | 0..1, closes both eyes on top of their openness |
245
+ | `leftBrow`, `rightBrow` | -1 lowered, 0 rest, 1 raised |
246
+ | `browTilt` | -1 angry (inner ends down) to 1 worried (inner ends up) |
247
+ | `lookX`, `lookY` | -1..1: where the pupils point (+x is the way the figure faces, +y is down) |
248
+ | `mouth` | 0 closed to 1 wide open |
249
+ | `smile` | -1..1: a frown or smile when closed; open, a wail (-) or a grin (+) |
250
+ | `mouthWidth` | 1 normal, 0.5 pursed, 1.5 wide |
251
+
252
+ Shut eyes arch upward when the figure smiles (a laugh) and curve down otherwise.
253
+ `talk` sets only `mouth`, so a figure keeps its expression while it speaks.
254
+
255
+ ### Squash, stretch and rubber limbs
256
+
257
+ Two more numbers give the figure cartoon acting:
258
+
259
+ - **`stretch`** is part of the pose (1 normal). Above 1 the figure is taller and
260
+ thinner, as in a jump; below 1 it squashes, as in a wind-up or a landing. The
261
+ body and legs scale by it, the arms by its square root, the head becomes an
262
+ ellipse of the same area, and the feet stay on the ground. `POSES.crouch`
263
+ and `POSES.jump` carry a squash and a stretch, and any key can set it:
264
+
265
+ ```js
266
+ ...poseTracks('hero', [
267
+ { time: 0, pose: 'rest' },
268
+ { time: 400, pose: 'crouch', easing: 'ease-out' }, // wind up
269
+ { time: 560, pose: 'jump', easing: 'ease-out' }, // spring
270
+ { time: 1200, pose: { stretch: 0.75 } }, // land
271
+ { time: 1400, pose: { stretch: 1.08 }, easing: 'ease-out' },
272
+ { time: 1600, pose: { stretch: 1 }, easing: 'ease-in-out' }, // settle
273
+ ]),
274
+ ```
275
+
276
+ - **`rubber`** is how the limbs are drawn: 0 straight segments jointed at the
277
+ elbows and knees, 1 smooth rubber-hose curves through them, in between a blend.
278
+ Set it on the style (`style: { rubber: 1 }`) for a rubber-hose character. It is
279
+ also a prop of `stickFigureTarget`, so a `rubber` track can stiffen and loosen
280
+ the limbs. It lives on the style rather than in the pose so that a named
281
+ pose never resets it.
282
+
283
+ A pose written before `stretch` existed draws unstretched.
284
+
285
+ ### Turning, sitting and ground contact
286
+
287
+ - **`turn`** (pose field, 0..1) turns the figure toward the way it faces: 0 is
288
+ front-on, 1 is profile. The face slides toward the facing side and narrows,
289
+ and shoulders set with `shoulderWidth` close up. A walker reads better turned
290
+ toward where it goes (`turn: 0.7`).
291
+ - **`sit`** (pose field, 0..1) folds the figure down onto a seat: the thighs swing
292
+ forward to level, the shins hang straight down, and the hips drop to
293
+ `seatHeight(height)` above the feet at 1. From 0.25 on, the lower foot stays on
294
+ the ground, so sitting down and standing up never sink the feet. Put the top of
295
+ a bench, log or charpai at `seatHeight`. `POSES.sit` is seated with the hands on
296
+ the knees.
297
+ - **Ground contact:** `stickFigureJoints()` reports `feetY` (the lower foot's y)
298
+ and `grounded.left` / `grounded.right` (a foot within 1% of the height of the
299
+ lower one), so a shadow or a dust puff can sit under the planted foot. In the
300
+ organic look `feetY` is 0: the figure always stands on the ground.
301
+
302
+ ```js
303
+ ...poseTracks('tum', [
304
+ { time: 0, pose: { turn: 0.7 } }, // walks in, turned
305
+ { time: 3000, pose: { turn: 0.3 } },
306
+ { time: 3800, pose: 'sit', easing: 'ease-in-out' }, // sits down
307
+ ]),
308
+ ```
309
+
310
+ Both are pose fields, so they blend and get tracks like any joint. Poses
311
+ written before they existed draw standing and front-on.
312
+
313
+ ### Pencil sketch style
314
+
315
+ For a hand-drawn, pencil-test look, give the figure a `sketch` style. Each line
316
+ is drawn in a few slightly bowed passes, the head is a circle whose end
317
+ overshoots its start, and the wobble *boils*: it is redrawn a few times a second,
318
+ so the figure looks alive even standing still.
319
+
320
+ ```js
321
+ stickFigureTarget({
322
+ x: 640, y: 560,
323
+ style: { height: 300, color: '#2f2f33', lineWidth: 6, headFill: 'none',
324
+ sketch: { roughness: 3, passes: 2, boil: 8, seed: 7 } },
325
+ })
326
+ ```
327
+
328
+ | `sketch` field | |
329
+ |---|---|
330
+ | `roughness` | Largest wobble in px (default 2) |
331
+ | `passes` | Strokes per line: 1 clean, 2–3 sketched (default 2) |
332
+ | `boil` | Redraws per second; 0 holds the wobble still (default 8) |
333
+ | `seed` | So two drawings do not boil in step (default 1) |
334
+
335
+ Canvas shapes take the same style: a `rect`, `circle`, `line` or `path` target
336
+ with `sketch: { … }` draws its outline in pencil (the fill stays clean), and a
337
+ `drawOn` track (0..1) draws it on. See the [API reference](api-reference.md#canvasadapter).
338
+
339
+ The same strokes are available for anything you draw yourself, such as ground
340
+ lines and props in `background` or `draw`:
341
+
342
+ ```js
343
+ import { sketchPen } from '@algorisys/tinyfly/characters'
344
+
345
+ background(ctx, { time }) {
346
+ const pen = sketchPen(ctx, { roughness: 3, seed: 2 }, time)
347
+ ctx.strokeStyle = '#2f2f33'
348
+ ctx.lineWidth = 5
349
+ pen.line([{ x: 60, y: 560 }, { x: 700, y: 562 }])
350
+ pen.circle(900, 200, 40)
351
+ }
352
+ ```
353
+
354
+ The wobble comes from a generator seeded by `seed`, the boil frame
355
+ (`boilFrame(time, boil)`) and the stroke's place in the drawing order, never
356
+ `Math.random`, so a frame renders the same every time. Draw strokes in the same
357
+ order each frame.
358
+
359
+ Every stroke takes a last `progress` argument (0..1) to draw it on:
360
+ `pen.line(points, 0.4)` draws the first 40% of the line. The part drawn so far
361
+ lies exactly on the finished stroke, so it grows without jumping, and a stroke
362
+ drawn partway does not change the wobble of the strokes after it. `drawStickFigure(ctx, pose, style, time)` takes
363
+ the time for the same reason.
364
+
365
+ ### Costumes, hair and props
366
+
367
+ The figure can tell you where its parts are, and lets you draw inside its z-order,
368
+ so a costume, a hair style or a held prop moves with every pose, walk and squash.
369
+
370
+ `stickFigureJoints(pose, style)` returns the same geometry `drawStickFigure`
371
+ draws with: `hip`, `neck`, `shoulders`, `elbows`, `hands`, `knees`, `feet` and
372
+ `toes` (each `{ left, right }`), `handAngle` (the forearm's direction in radians, for
373
+ holding a prop at the right angle), `limbs` (each limb's centre line as drawn,
374
+ rounded joints and rubber-hose curves included, for sleeves and trousers to
375
+ follow, plus `spine` from hip to neck) and `head`
376
+ (`center`, `rx`, `ry`, `angle`, and the face's `eyeY`, `browTopY`, `mouthY` and
377
+ `faceX` in head units). Points are in the figure's space, feet at (0, 0), and
378
+ already mirrored for `facing`, so you never need `ctx.scale(-1, 1)` (which
379
+ would mirror your text too).
380
+
381
+ `style.layers` draws your code at fixed depths inside the figure:
382
+
383
+ ```
384
+ behind → legs → torso → body → back arm → sleeve(back) → front arm →
385
+ sleeve(front) → behindHead → head and face → overHead → front → label
386
+ ```
387
+
388
+ Each hook is called once per frame as `(ctx, joints, time, pen?)` (`sleeve` gets
389
+ `(ctx, joints, side, time, pen?)`), with the context saved and restored around
390
+ it and in the figure's space, unmirrored. The left arm is always the back arm:
391
+ the figure faces the viewer and mirrors as a whole, so its left side is always
392
+ the one away from the way it looks. Turned more than a quarter of the way
393
+ (`turn` above 0.25), the back arm and its `sleeve` are drawn before the torso
394
+ and `body`, so the body and its clothes hide it:
395
+ `behind → legs → back arm → sleeve(back) → torso → body → front arm → …`.
396
+ When the figure is sketched, `pen` is a
397
+ sketch pen that boils with it. `style.shoulderWidth` (half the shoulder width,
398
+ as a fraction of the height; default 0) starts the arms from two shoulders
399
+ square to the spine, joined by a line, instead of one point.
400
+
401
+ ```js
402
+ import { stickFigureTarget, stickFigureAt, headPoint } from '@algorisys/tinyfly/characters'
403
+
404
+ const tum = stickFigureTarget({
405
+ x: 250, y: 900,
406
+ style: {
407
+ height: 400, color: '#3A1010', headFill: '#F2C49B', rubber: 0.6, shoulderWidth: 0.075,
408
+ layers: {
409
+ body: (ctx, j) => drawShirt(ctx, j, '#EF4444'),
410
+ sleeve: (ctx, j, side) => drawSleeve(ctx, j.limbs[side + 'Arm'], '#EF4444'),
411
+ overHead: (ctx, j) => {
412
+ const fringe = headPoint(j.head, j.head.faceX, j.head.browTopY - 0.1)
413
+ drawHair(ctx, j.head, fringe)
414
+ },
415
+ front: (ctx, j) => drawPot(ctx, j.hands.left, j.handAngle.left),
416
+ },
417
+ },
418
+ })
419
+
420
+ export default {
421
+ width: 1920, height: 1080,
422
+ targets: { tum },
423
+ timeline,
424
+ // Immediate-mode drawing that follows the figure: a speech-bubble tail at its head.
425
+ draw(ctx, frame) {
426
+ const { joints } = stickFigureAt(tum, frame, 'tum')
427
+ drawBubble(ctx, 'भैया, UPI चलेगा?', joints.head.center)
428
+ },
429
+ }
430
+ ```
431
+
432
+ `stickFigureAt(target, frame, id)` applies the frame's tracks for `id` (the
433
+ target's key in `targets`) the way the canvas adapter does, including `x`/`y`,
434
+ walking and talking, and returns `{ pose, joints }` with the joints in scene
435
+ coordinates. A `rotate` or `scale` on the target itself is not applied.
436
+
437
+ The [model sheet](model-sheet/README.md) is a worked example: a man and a woman,
438
+ dressed with layers, in five turnaround views with height guides, colour swatches
439
+ and expressions.
440
+
441
+ With `classic: true`, no `layers` and `shoulderWidth` 0, the figure draws
442
+ exactly as 0.75 did. `taperedLine(ctx, points, from, to)` is the tapered fill the
443
+ organic limbs use, handy for sleeves and trouser legs that follow `limbs`.
444
+
445
+ ### The drawing hand
446
+
447
+ The animator's hand draws things into the scene. `drawnPathTarget()` is a
448
+ custom target that draws a stroke on: its `draw` prop (0..1) is a track, and
449
+ while it is between 0 and 1 a cartoon hand holds the pencil at the end of the
450
+ line, its arm reaching in from off screen.
451
+
452
+ ```js
453
+ import { drawnPathTarget, circlePath } from '@algorisys/tinyfly/characters'
454
+
455
+ targets: {
456
+ ground: drawnPathTarget({ path: [{ x: 80, y: 560 }, { x: 1200, y: 560 }], sketch: { roughness: 3 } }),
457
+ sun: drawnPathTarget({ path: circlePath(1000, 180, 70), smooth: true, sketch: { roughness: 3 } }),
458
+ },
459
+ // …and in the timeline:
460
+ { id: 'g', target: 'ground', property: 'draw', keyframes: [{ time: 600, value: 0 }, { time: 2400, value: 1 }] }
461
+ ```
462
+
463
+ The path is in scene coordinates. `smooth: true` draws a curve through the
464
+ points instead of straight segments; `hand: false` hides the hand, and a
465
+ `HandStyle` changes it. `erasable(target, { path, hand: true })` puts the same
466
+ hand on the eraser.
467
+
468
+ | | |
469
+ |---|---|
470
+ | `drawnPathTarget({ path, smooth?, color?, lineWidth?, sketch?, hand? })` | A target with a `draw` prop (0..1) that draws the path on, with the hand at its end |
471
+ | `drawHand(ctx, at, style?, pen?)` | A hand holding a pencil (or `tool: 'eraser'`) with the tool's tip at `at`; `angle`, `scale`, `skin`, `sleeve`, `outline` |
472
+ | `drawPencil(ctx, at, style?, pen?)` | Just the pencil, tip at `at` |
473
+ | `circlePath(cx, cy, r, overshoot?)` | A circle as points from the top, a little past a full turn, for drawing on |
474
+
475
+ ### Erasing
476
+
477
+ An eraser travels along a path and rubs out whatever is under the part it has
478
+ covered. How far it has got is one number, 0..1, so erasing is a timeline track.
479
+
480
+ Wrap a custom target in `erasable()` and it gains an `erase` prop:
481
+
482
+ ```js
483
+ import { erasable, scrubPath, stickFigureTarget } from '@algorisys/tinyfly/characters'
484
+
485
+ targets: {
486
+ doodle: erasable(stickFigureTarget({ x: 640, y: 560, style }), {
487
+ path: scrubPath(196, 70, 58, 50, 7), // back and forth over a box, in the target's own box
488
+ width: 26, // eraser width, px
489
+ }),
490
+ },
491
+ // …and in the timeline:
492
+ { id: 'rub', target: 'doodle', property: 'erase', keyframes: [{ time: 800, value: 0 }, { time: 2600, value: 1 }] }
493
+ ```
494
+
495
+ The path is in the target's own box (0, 0 is its top-left), so the erased part
496
+ moves with the target. It does not follow a limb: if an erased arm moves, the
497
+ gap stays where the arm was. The eraser is drawn while `erase` is between 0 and
498
+ 1; pass `eraser: false` to hide it, or an `EraserStyle` to change it.
499
+
500
+ For things you draw yourself, `withErased()` erases from them by time:
501
+
502
+ ```js
503
+ import { withErased, pointAlong, drawEraser } from '@algorisys/tinyfly/characters'
504
+
505
+ background(ctx, { time }) {
506
+ const progress = Math.min(1, Math.max(0, (time - 4500) / 1900))
507
+ withErased(ctx, GROUND_SCRUB, 30, progress, () => drawGround(ctx, time))
508
+ },
509
+ draw(ctx, { time }) {
510
+ const progress = Math.min(1, Math.max(0, (time - 4500) / 1900))
511
+ if (progress > 0 && progress < 1) drawEraser(ctx, pointAlong(GROUND_SCRUB, progress))
512
+ },
513
+ ```
514
+
515
+ | | |
516
+ |---|---|
517
+ | `erasable(target, { path, width?, eraser? })` | The target with an `erase` prop (0..1) that rubs it out along `path` |
518
+ | `withErased(ctx, path, width, progress, draw)` | Run `draw` with the swath erased from it |
519
+ | `clipErased(ctx, path, width, progress)` | The clip itself, for use between your own `save()` and `restore()` |
520
+ | `scrubPath(x, y, width, height, strokes?)` | A back-and-forth path covering a box |
521
+ | `drawEraser(ctx, at, style?, pen?)` | A block eraser with its rubbing end at `at` (sketched when given a `sketchPen`) |
522
+ | `erasable(…, { hand: true })` | The eraser is held by the animator's hand |
523
+ | `partialPath(path, t)`, `pointAlong(path, t)`, `pathLength(path)` | Polyline helpers: the start of a path, the point at `t` of its length, its length |
524
+
525
+ Erasing cuts the swath out with clipping, not an offscreen layer, so it needs
526
+ only a Canvas 2D context. Only what is drawn inside it is erased: whatever was
527
+ drawn earlier (the paper, the background) shows through.
528
+
529
+ ## Loops
530
+
531
+ For a video that should loop forever (Shorts, Reels, GIF-style), make every
532
+ motion repeat over the scene's `duration`: periodic functions of
533
+ `time / duration`, a whole number of turns, a self-similar zoom that steps
534
+ one level per loop. Then the frame at time = duration *is* the first frame,
535
+ and a looping player's jump from the last frame back to the first is a step
536
+ like any other.
537
+
538
+ `--loop-check` checks it by rendering five frames (no video, no ffmpeg):
539
+
540
+ ```
541
+ $ npx tinyfly video droste-head.mjs --loop-check
542
+ frame at the duration vs the first: identical
543
+ last → first (the seam): 17.41 dB
544
+ ordinary steps: 17.61 dB, 19.06 dB
545
+ ✓ closes: the frame at the duration matches the first (identical), so the seam is an ordinary step
546
+ ```
547
+
548
+ - **Closes**: the frame at the duration matches the first (40 dB or more):
549
+ every motion repeats.
550
+ - **Seamless**: it does not close exactly, but the last → first step differs
551
+ no more than an ordinary step (within 3 dB of the worse of the first and
552
+ last steps).
553
+ - **Does not loop**: the seam stands out; the command exits 1, so a build can
554
+ check it.
555
+
556
+ The numbers are PSNR (higher is more alike; fast or trembling motion makes
557
+ every step lower). From code: `checkLoop(scene)` returns the same report, and
558
+ `psnr(a, b)` / `loopReport(frames)` work on any RGBA frames.
559
+
560
+ ## Bloom
561
+
562
+ `bloom: true` (or options) adds a glow around everything bright, after each
563
+ frame is drawn: neon signs, emissive 3D materials, light trails.
564
+
565
+ ```js
566
+ export default {
567
+ // …
568
+ bloom: { threshold: 0.5, strength: 1 },
569
+ }
570
+ ```
571
+
572
+ | Option | Default | Meaning |
573
+ |---|---|---|
574
+ | `threshold` | `0.55` | How bright (0..1, by the brightest channel) a pixel must be to glow; saturated neon counts as bright |
575
+ | `strength` | `0.9` | How much glow is added back |
576
+ | `radius` | 2% of the larger side | Blur radius of the tight glow, in scene pixels (scaled with `--scale`) |
577
+ | `halo` | `0.6` | Strength of a second, three times wider halo |
578
+ | `downsample` | `4` | The glow is computed at 1/4 size: faster, and it is blurry anyway |
579
+
580
+ It is a bright pass (keeping each pixel's hue), a separable box blur and an
581
+ additive composite, all in plain arithmetic: no `ctx.filter`, so every frame
582
+ is the same on every machine. The same `applyBloom(ctx, options)` works on any
583
+ 2D canvas (from `@algorisys/tinyfly/adapters`, or the browser bundle), e.g.
584
+ after drawing a live canvas.
585
+
586
+ [`examples/headless-video/neon-bloom.mjs`](../examples/headless-video/neon-bloom.mjs)
587
+ is a looping neon scene: emissive 3D shapes plus bloom.
588
+
589
+ ## Light trails
590
+
591
+ A trail is where something has been: a band along its positions over the
592
+ last moments, narrowing and fading toward the tail. Ask for the positions
593
+ with `trailSamples` (a pure function of time, so every frame and every seek
594
+ draws the same trail) and draw them with `drawTrail`:
595
+
596
+ ```js
597
+ import { trailSamples } from '@algorisys/tinyfly'
598
+ import { drawTrail } from '@algorisys/tinyfly/adapters'
599
+
600
+ const LOOP = 8000
601
+ // Whole cycles per loop (2 across, 3 up and down), so the video loops.
602
+ const turn = (t) => (t / LOOP) * Math.PI * 2
603
+ const comet = (t) => ({ x: 640 + 500 * Math.sin(2 * turn(t)), y: 360 + 250 * Math.sin(3 * turn(t)) })
604
+
605
+ export default {
606
+ width: 1280, height: 720, duration: LOOP, background: '#05030c',
607
+ bloom: true,
608
+ draw(ctx, frame) {
609
+ const trail = trailSamples(comet, frame.time, { length: 1200, samples: 64, period: LOOP })
610
+ drawTrail(ctx, trail, { color: '#00e5ff', width: 10, blend: 'add', head: { radius: 14, color: '#ffffff' } })
611
+ },
612
+ }
613
+ ```
614
+
615
+ | `trailSamples(positionAt, time, options)` | |
616
+ |---|---|
617
+ | `length` | How far back, ms |
618
+ | `samples` | Points along it (default 32): more for fast, curvy motion |
619
+ | `period` | Motion that repeats every `period` ms: earlier times wrap, so a loop starts with the last lap's tail |
620
+ | `since` | Nothing before this time: the trail grows from here |
621
+
622
+ | `drawTrail(ctx, samples, style)` | |
623
+ |---|---|
624
+ | `color`, `width` (px, default 6), `opacity` | |
625
+ | `taper`, `fade` | 0..1 (default 1): narrow to a point, fade to nothing |
626
+ | `blend` | `normal` (default) paints; `add` adds light (`'lighter'`), brighter where trails cross |
627
+ | `head` | `{ radius, color? }`: a glowing comet head |
628
+
629
+ The band is one strip of segments that share their corners, with a round
630
+ head, built additively: it reads as one smooth stroke at any speed, with no
631
+ beads where segments overlap and no seams between them. `ribbon(points)` and
632
+ `ribbonHeadCap(points)` give its geometry for other renderers. 3D scenes have
633
+ `line` and `trail` objects, sorted by depth among the meshes (see
634
+ [3D Scenes](scene-3d.md#lines-and-trails)).
635
+
636
+ ## Camera, overlay and drawing on twos
637
+
638
+ - `camera: true` sees the scene through the tracks of the `Camera` target:
639
+ `x`/`y` pan, `scale` zooms, `rotate` rolls, and `shakeX`/`shakeY`/`shakeRotate`
640
+ shake on top. `cameraTracks()` writes them from shots (push in, cut, shake,
641
+ follow). The background, targets and `draw` are filmed; a colour background
642
+ fills the frame.
643
+ - `overlay(ctx, frame)` draws last, in screen space: captions and titles that
644
+ stay put while the camera moves.
645
+ - `drawingRate: 12` holds the timeline's poses for two frames of 24 fps ("on
646
+ twos"), as hand-drawn animation is timed.
647
+
648
+ See [acting.md](acting.md) for camera shots, beat scripts and the rest of the
649
+ cartoon acting tools.
650
+
651
+ ## Captions
652
+
653
+ `toSRT(cues)` and `toWebVTT(cues)` (in `@algorisys/tinyfly/export` and
654
+ `@algorisys/tinyfly/headless`) write caption files from `{ start, end, text }` cues.
655
+ `captionCuesFromTimeline(definition, { language })` makes cues from a timeline's
656
+ markers: each marker's caption (or label) runs until the next marker.
657
+
658
+ ## From a script
659
+
660
+ The CLI is a thin wrapper over `@algorisys/tinyfly/headless`:
661
+
662
+ ```js
663
+ import { renderVideo, renderStills, sceneCaptions, toSRT } from '@algorisys/tinyfly/headless'
664
+ import { writeFileSync } from 'node:fs'
665
+ import scene from './scene.mjs'
666
+
667
+ await renderVideo(scene, {
668
+ output: 'out.mp4',
669
+ baseDir: '.', // relative audio and font paths resolve against this
670
+ scale: 1, crf: 20, preset: 'medium',
671
+ onProgress: (done, total) => {},
672
+ })
673
+ await renderStills(scene, { dir: 'stills' })
674
+ writeFileSync('out.srt', toSRT(sceneCaptions(scene)))
675
+ ```
676
+
677
+ `FrameRenderer` (also exported) draws a scene at any time onto any 2D context.
678
+ It needs no Node API, so the same scene can be previewed on a browser canvas:
679
+
680
+ ```js
681
+ const renderer = new FrameRenderer(scene)
682
+ renderer.render(canvas.getContext('2d'), timeMs)
683
+ ```
684
+
685
+ ## Porting a Cairo script
686
+
687
+ | Cairo / pycairo | tinyfly |
688
+ |---|---|
689
+ | `draw(ctx, t, T)` per scene | `draw(ctx, { time })`, with `narrationSceneAt(plan, time)` to pick the scene |
690
+ | `T.s(i)`, `T.e(i)`, `T.on(i, t)` | `plan.scenes[n].cues[i].start` / `.end`, `time >= cue.start` |
691
+ | `ease(seg(t, a, b))` | a keyframe track with an easing, or `getEasingFunction('ease-out')` in code |
692
+ | `ctx.set_source_rgb`, `ctx.arc`, `ctx.stroke` | the Canvas 2D API: `fillStyle`, `arc`, `stroke` |
693
+ | `ctx.push_group` + `paint_with_alpha` | `globalAlpha`, or a target's `opacity` track |
694
+ | `figure()`, `blend_pose()`, `walker()` | `stickFigureTarget`, `blendPose`, `walkPose` from `@algorisys/tinyfly/characters` |
695
+ | TTS clips → `narration.wav` (`build_timeline`) | `voiceNarration()` |
696
+ | Other helpers (`tag()`, `quote_card()`) | custom targets, or plain functions called from `draw` |
697
+ | ffmpeg pipe + `write_srt` | `tinyfly video … --srt` |
698
+
699
+ ### Benchmark: one scene of a real Cairo video
700
+
701
+ Scene 8 of a published pycairo explainer ("the table grows": 12 stick figures
702
+ round a growing table, flying envelopes, a doorway, a quote card, a waiting
703
+ room) was ported call for call to Canvas 2D and rendered at 1920×1080, 24 fps,
704
+ 1202 frames, with the same x264 settings (`medium`, CRF 20). Same machine, no other load:
705
+
706
+ | | pycairo | tinyfly (`@napi-rs/canvas`) |
707
+ |---|---|---|
708
+ | Draw only | 24.4 s (20.3 ms/frame) | 5.4 s (4.5 ms/frame) |
709
+ | Draw + encode to MP4 | 46.5 s | 52.3 s |
710
+
711
+ - Drawing is about 4.5× faster. The finished video is not: both renders spend
712
+ most of their time in x264, so the encoder sets the pace.
713
+ - The stills match frame for frame (mean pixel difference about 1/255). What
714
+ differs is text: Skia draws glyphs slightly narrower than Cairo.
715
+ - The port was 235 lines for the scene (the Python was 125) plus 368 lines of
716
+ helpers carried over from the Cairo engine: tags, top captions, quote cards,
717
+ the round table, envelopes, doors, camera drift and a figure matching the
718
+ original proportions. Those helpers are what tinyfly still lacks, not engine
719
+ features.
720
+
721
+ ## Requirements and limits
722
+
723
+ - Node 18+, `@napi-rs/canvas` (an optional peer dependency, loaded only when
724
+ rendering) and `ffmpeg`. Rendering defines `globalThis.Path2D` from the canvas
725
+ package when it is missing, because path targets use it.
726
+ - Output is H.264 MP4 (`yuv420p`, odd sizes padded to even), with AAC audio when
727
+ `audio` is set; video stops at the shorter of picture and sound.
728
+ - `image` targets need images loaded with the canvas package's `loadImage`.