@algorisys/tinyfly 0.92.0 → 0.94.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.
- package/README.md +7 -6
- package/bin/tinyfly.mjs +34 -1
- package/docs/2d-animation-roadmap.md +191 -0
- package/docs/3d-rotations.md +164 -0
- package/docs/3d-support-plan.md +628 -0
- package/docs/DEPLOYMENT.md +414 -0
- package/docs/acting.md +529 -0
- package/docs/api-reference.md +2353 -0
- package/docs/camera.md +94 -0
- package/docs/cartoon-hands.md +96 -0
- package/docs/character-system-m1.md +218 -0
- package/docs/character-system-plan.md +384 -0
- package/docs/dance.md +315 -0
- package/docs/editor-guide.md +1249 -0
- package/docs/examples.md +765 -0
- package/docs/extending.md +168 -0
- package/docs/file-format.md +690 -0
- package/docs/getting-started.md +314 -0
- package/docs/grid-and-snapping.md +64 -0
- package/docs/gsap-compat.md +1241 -0
- package/docs/llm-guide.md +131 -0
- package/docs/maps.md +116 -0
- package/docs/onion-skinning.md +41 -0
- package/docs/pen-tool.md +65 -0
- package/docs/polygon-star.md +44 -0
- package/docs/scene-3d.md +299 -0
- package/docs/scroll-animation.md +314 -0
- package/docs/shape-morph.md +61 -0
- package/docs/sprite-sheet-export.md +54 -0
- package/docs/symbols-and-library.md +137 -0
- package/docs/teaching.md +348 -0
- package/docs/video-rendering.md +728 -0
- package/lib/addons/adapters.js +22 -18
- package/lib/addons/characters.js +3045 -2024
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6968 -5817
- package/lib/browser/tinyfly.umd.js +9 -4
- package/lib/engine/tinyfly-engine.js +286 -258
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
- package/lib/types/characters/acting/beat-check.d.ts +102 -0
- package/lib/types/characters/acting/custom.d.ts +66 -0
- package/lib/types/characters/acting/gags.d.ts +10 -0
- package/lib/types/characters/acting/hand-path.d.ts +35 -0
- package/lib/types/characters/acting/index.d.ts +4 -0
- package/lib/types/characters/acting/persona.d.ts +93 -0
- package/lib/types/characters/acting/script.d.ts +75 -11
- package/lib/types/characters/capabilities.d.ts +61 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +12 -0
- package/lib/types/characters/figure-props.d.ts +87 -0
- package/lib/types/characters/gaits.d.ts +8 -0
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/stick-figure.d.ts +9 -2
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12631 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +67 -0
- 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`.
|