@algorisys/tinyfly 0.101.0 → 0.102.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 (48) hide show
  1. package/README.md +5 -5
  2. package/bin/tinyfly.mjs +9 -3
  3. package/docs/editor-guide.md +1 -1
  4. package/docs/examples.md +1 -1
  5. package/docs/getting-started.md +1 -1
  6. package/docs/gsap-compat.md +1 -1
  7. package/docs/llm-guide.md +8 -2
  8. package/docs/maps.md +2 -2
  9. package/docs/scene-3d.md +117 -5
  10. package/docs/teaching.md +1 -1
  11. package/docs/video-rendering.md +44 -1
  12. package/lib/addons/adapters.js +168 -123
  13. package/lib/addons/characters.js +4663 -4566
  14. package/lib/addons/scene-3d-webgl.js +30 -30
  15. package/lib/addons/scene-3d.js +650 -341
  16. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
  17. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  18. package/lib/browser/tinyfly.iife.js +13 -13
  19. package/lib/browser/tinyfly.js +4105 -3973
  20. package/lib/browser/tinyfly.umd.js +13 -13
  21. package/lib/engine/tinyfly-engine.js +1207 -1172
  22. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  23. package/lib/headless/headless.js +150 -6
  24. package/lib/types/adapters/canvas/framing.d.ts +27 -0
  25. package/lib/types/adapters/canvas/index.d.ts +1 -0
  26. package/lib/types/characters/character-script-3d.d.ts +21 -1
  27. package/lib/types/characters/index.d.ts +2 -1
  28. package/lib/types/characters/staging-3d.d.ts +56 -0
  29. package/lib/types/engine/authoring/framing.d.ts +48 -0
  30. package/lib/types/engine/authoring/index.d.ts +1 -0
  31. package/lib/types/headless/audio-mix.d.ts +40 -0
  32. package/lib/types/headless/ffmpeg-args.d.ts +2 -0
  33. package/lib/types/headless/frame-renderer.d.ts +7 -1
  34. package/lib/types/headless/index.d.ts +1 -0
  35. package/lib/types/headless/node-audio.d.ts +19 -0
  36. package/lib/types/headless/node-video.d.ts +2 -0
  37. package/lib/types/headless/video-scene.d.ts +12 -0
  38. package/lib/types/scene-3d/index.d.ts +3 -0
  39. package/lib/types/scene-3d/lighting.d.ts +58 -0
  40. package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
  41. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  42. package/lib/types/scene-3d/scene-types.d.ts +14 -2
  43. package/lib/types/scene-3d/shots.d.ts +162 -0
  44. package/lib/types/scene-3d/software-renderer.d.ts +40 -0
  45. package/llms-full.txt +177 -16
  46. package/llms.txt +29 -29
  47. package/package.json +1 -1
  48. package/skills/tinyfly/SKILL.md +4 -1
package/README.md CHANGED
@@ -100,7 +100,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
100
100
  - **Loop check** - `tinyfly video scene.mjs --loop-check` renders five frames and says whether a video loops: whether the frame at the duration matches the first, and whether the last → first seam looks like any other step (exit 1 when it does not). `--frames 0,79,88` renders stills at chosen frames. See [docs/video-rendering.md](docs/video-rendering.md#loops) A scene with `loop: true` is checked before it renders, its frames carry the `period`, and periodic helpers repeat exactly over it: `wobble`, `loopEase`, `loopNoise` (seeded noise round a circle), `torusNoise`; `nestedZoom` draws a Droste picture (a `similarityAbout` step, one level per loop, only the visible levels); `applyZoomBlur` and `drawDiveLines` for dives; the Penrose triangle and stairs as boxes that line up from one viewpoint (`penroseTriangle`, `penroseStairs`, `penroseTriangle3D`); goo as geometry: metaballs that merge and split (`metaballContours`), drips (`dripPath`), bubbles that grow, wobble and pop (`bubblePath`, `bubblePop`) and area-keeping squash and stretch (`squashStretch`)
101
101
  - **Bloom** - `bloom: true` on a video scene adds a deterministic glow around bright things (bright pass, blur, add; no `ctx.filter`), and 3D materials take `emissive` light that shines in the dark and feeds it. `applyBloom(ctx)` works on any 2D canvas. See [docs/video-rendering.md](docs/video-rendering.md#bloom)
102
102
  - **Light trails** - `trailSamples` + `drawTrail` draw comets and light streaks on any 2D canvas: a tapering, fading band with a round head, smooth at any speed, and deterministic (the trail is where the thing was, asked of the timeline, not a frame history). 3D scenes get `line` and `trail` objects whose segments sort by depth among the meshes. See [docs/video-rendering.md](docs/video-rendering.md#light-trails) and [docs/scene-3d.md](docs/scene-3d.md#lines-and-trails)
103
- - **3D scenes** - `@algorisys/tinyfly/scene-3d`: cameras, lights, meshes (box, sphere, cylinder, cone, torus, floor, any SVG path extruded) and props from the catalog (also from the editor's 3D Scene palette) as JSON in metres, animated by ordinary tracks (`stage/box`), cut between cameras with one keyframe, drawn on a plain canvas with flat, smooth or toon shading, ink outlines and fog: in the browser, in Workers, and to MP4 in Node. Characters stand in scenes and dance, seen by any camera, in their pen looks (clean, pencil) or as solid figures (`characterObjects`); props (cars, houses, trees, animals, birds) stand in them by preset name (`propObjects`), sorted a column at a time so figures walk round them rightly, and lit by the scene's lights (a sunset, a night with lit windows). Both are scripted in world metres (`propScript3D`, `characterScript3D`): drive or walk to a point or along a path, wheels and feet keeping pace with the ground. In the editor, a 🧊 3D Scene element builds them without code: add shapes, characters and lights, key them, dance from the playhead, cut between cameras. No WebGL needed (about 7 KB gzipped, its own entry and CDN script); for big or tangled scenes the optional WebGL2 renderer (`@algorisys/tinyfly/scene-3d/webgl`) adds a depth buffer and light per pixel. See [docs/scene-3d.md](docs/scene-3d.md)
103
+ - **3D scenes** - `@algorisys/tinyfly/scene-3d`: cameras, lights, meshes (box, sphere, cylinder, cone, torus, floor, any SVG path extruded) and props from the catalog (also from the editor's 3D Scene palette) as JSON in metres, animated by ordinary tracks (`stage/box`), cut between cameras with one keyframe, drawn on a plain canvas with flat, smooth or toon shading, ink outlines and fog: in the browser, in Workers, and to MP4 in Node. Characters stand in scenes and dance, seen by any camera, in their pen looks (clean, pencil) or as solid figures (`characterObjects`); props (cars, houses, trees, animals, birds) stand in them by preset name (`propObjects`), sorted a column at a time so figures walk round them rightly, and lit by the scene's lights (a sunset, a night with lit windows). Both are scripted in world metres (`propScript3D`, `characterScript3D`): drive or walk to a point or along a path, wheels and feet keeping pace with the ground. In the editor, a 🧊 3D Scene element builds them without code: add shapes, characters and lights, key them, dance from the playhead, cut between cameras. No WebGL needed (about 7 KB gzipped, its own entry and CDN script); for big or tangled scenes the optional WebGL2 renderer (`@algorisys/tinyfly/scene-3d/webgl`) adds a depth buffer and light per pixel. A software depth buffer (`depthBuffer: true`) draws crossing shapes and see-through meshes right in Node too. Films are shot lists as data: `shotTracks` cuts between cameras, `transitionAt` and `drawTransition` crossfade, dip or wipe between shots, `cameraMoveTracks` writes orbits, dollies, cranes, pans and zooms as tracks, `cameraHandheldTracks` adds a seeded shake, and `drawLetterbox` frames it at any aspect. See [docs/scene-3d.md](docs/scene-3d.md)
104
104
  - **3D transforms** - Cards, images, text and shapes turn in 3D (`rotateX`, `rotateY`, `z`, `perspective`, `backfaceVisibility`) and land on the same pixels in DOM, SVG, Canvas (true perspective, also headless) and WebGL, checked against each browser's own CSS. One documented transform order everywhere; Tilt / Turn / Depth / Perspective fields in the editor; 3D Card Flip and Cover Flow samples. Quaternion tracks with `interpolation: "slerp"` turn without gimbal lock; the engine's `vec3`, `quat` and `mat4` helpers are plain arrays. The first steps of [3D support](docs/3d-support-plan.md). See [docs/3d-rotations.md](docs/3d-rotations.md)
105
105
  - **Shape morph** - 🌀 Tween one path into another over the timeline (engine-level path interpolation); plays in every renderer, export, and embed
106
106
  - **Grid, snapping & guides** - ▦ 20px grid, 🧲 snapping of drag/resize to grid/element-edges/artboard with live alignment guides, and 📏 rulers with draggable guides
@@ -237,7 +237,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
237
237
  itself.
238
238
 
239
239
  ```html
240
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
240
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
241
241
  <script>
242
242
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
243
243
 
@@ -273,7 +273,7 @@ A teaching figure needs no code at all:
273
273
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
274
274
  <figcaption>Appending to a full slice</figcaption>
275
275
  </figure>
276
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
276
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
277
277
  ```
278
278
 
279
279
  See [Teaching Animations](docs/teaching.md).
@@ -372,7 +372,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
372
372
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
373
373
  </div>
374
374
 
375
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js"></script>
375
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js"></script>
376
376
  <script>
377
377
  tinyfly.play('#animation', './animation.json', { loop: -1 })
378
378
  </script>
@@ -481,7 +481,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
481
481
  <svg viewBox="0 0 720 200">…</svg>
482
482
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
483
483
  </figure>
484
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
484
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
485
485
  ```
486
486
 
487
487
  ### Audio / Video Sync
package/bin/tinyfly.mjs CHANGED
@@ -27,7 +27,7 @@
27
27
  * JavaScript (RSS, email, print, previews).
28
28
  *
29
29
  * tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,ms,…>]
30
- * [--loop-check] [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]
30
+ * [--loop-check] [--scale <n>] [--fps <n>] [--crf <n>] [--codec h264|prores] [--no-audio] [--srt <file>] [--vtt <file>]
31
31
  * Render a scene module to an MP4 without a browser. The module's default
32
32
  * export is a VideoScene (or a function returning one): a timeline and
33
33
  * canvas targets, a draw(ctx, frame) function, or both. --stills writes
@@ -86,7 +86,7 @@ const usage = () => {
86
86
  ' tinyfly validate <timeline.json> [<timeline.json> …] [--markup <file>]\n' +
87
87
  ' tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]\n' +
88
88
  ' tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,…>] [--loop-check]\n' +
89
- ' [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]'
89
+ ' [--scale <n>] [--fps <n>] [--crf <n>] [--codec h264|prores] [--no-audio] [--srt <file>] [--vtt <file>]'
90
90
  )
91
91
  process.exit(2)
92
92
  }
@@ -162,6 +162,11 @@ async function video() {
162
162
  const scale = numberFlag('--scale')
163
163
  const fps = numberFlag('--fps')
164
164
  const crf = numberFlag('--crf')
165
+ const codec = flag('--codec')
166
+ if (codec && codec !== 'h264' && codec !== 'prores') {
167
+ console.error('tinyfly: --codec is h264 or prores')
168
+ process.exit(2)
169
+ }
165
170
  const silent = has('--no-audio')
166
171
  const loopCheck = has('--loop-check')
167
172
  const framesList = listFlag('--frames')
@@ -214,7 +219,7 @@ async function video() {
214
219
  console.error(`stills: ${files.length} PNG(s) in ${stillsDir}`)
215
220
  return
216
221
  }
217
- const out = output ?? join(baseDir, `${basename(scenePath, extname(scenePath))}.mp4`)
222
+ const out = output ?? join(baseDir, `${basename(scenePath, extname(scenePath))}.${codec === 'prores' ? 'mov' : 'mp4'}`)
218
223
  let lastPercent = -1
219
224
  const started = Date.now()
220
225
  const result = await headless.renderVideo(scene, {
@@ -223,6 +228,7 @@ async function video() {
223
228
  scale,
224
229
  fps,
225
230
  crf,
231
+ codec,
226
232
  audio: silent ? false : undefined,
227
233
  onProgress: (done, total) => {
228
234
  const percent = Math.floor((done / total) * 20) * 5
@@ -1128,7 +1128,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
1128
1128
  **Steps to embed:**
1129
1129
  1. Build the player: `npm run build:player`
1130
1130
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1131
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js`
1131
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`
1132
1132
  instead; see [Deployment](DEPLOYMENT.md))
1133
1133
  3. Copy the generated code into your HTML
1134
1134
  4. Adjust the script `src` path if needed
package/docs/examples.md CHANGED
@@ -694,7 +694,7 @@ For simple website embedding without a build system.
694
694
  </html>
695
695
  ```
696
696
 
697
- Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js`.
697
+ Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`.
698
698
 
699
699
  ---
700
700
 
@@ -185,7 +185,7 @@ with a GSAP-style call (durations are in seconds here):
185
185
  ```html
186
186
  <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
187
187
 
188
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
189
189
  <script>
190
190
  tinyfly.to('.box', { x: 200, duration: 1 })
191
191
  </script>
@@ -74,7 +74,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
74
74
  global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
75
75
 
76
76
  ```html
77
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
78
78
  <script>
79
79
  tinyfly.to('.box', { x: 200, duration: 1 })
80
80
  </script>
package/docs/llm-guide.md CHANGED
@@ -48,8 +48,14 @@ loaded with `kinds: [characterObjects, propObjects]`; its controls are tracks
48
48
  on the object. Script it in world metres with `propScript3D` (`to: [x, z]`,
49
49
  `through: [[x, z], …]`, `face`), not with `propScript`, whose `to` is screen px.
50
50
  Characters in a 3D scene walk the same way with `characterScript3D`
51
- (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`); a rider is
52
- seated with `propRide3D` and spliced into its script with `spliceTracks`. See `docs/props.md`.
51
+ (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`, `say` with a
52
+ line, `look` at a point or `'camera'`); a rider is seated with `propRide3D`
53
+ and spliced into its script with `spliceTracks`. A film from a 3D scene is a
54
+ shot list (`shotTracks`, `transitionAt` + `drawTransition`), camera moves as
55
+ tracks (`cameraMoveTracks`, `cameraHandheldTracks`), a mood from
56
+ `lightingPreset('dusk')` with `ground()` and `shadow: true` on meshes, and
57
+ sound from `renderMix`; draw it with `depthBuffer: true` when shapes cross.
58
+ See `docs/props.md` and `docs/scene-3d.md`.
53
59
 
54
60
  ## Characters with a look
55
61
 
package/docs/maps.md CHANGED
@@ -14,8 +14,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
14
14
  adds to the same `tinyfly` global:
15
15
 
16
16
  ```html
17
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-maps.iife.js"></script>
19
19
  ```
20
20
 
21
21
  It is a separate script because the offline world map it carries adds about
package/docs/scene-3d.md CHANGED
@@ -95,8 +95,11 @@ for a neon glow: `{ color: '#000000', emissive: '#ff2bd6', shading: 'unlit' }`.
95
95
  `roughness` and `metalness` are for the realistic look (three.js, a later
96
96
  milestone); the stylized renderers ignore them, so one material serves both.
97
97
 
98
- The scene can have `background` and `fog: { color, near, far }` (metres from
99
- the camera). A scene with no lights gets a soft default (ambient plus a key
98
+ The scene can have `background` (a colour, or a sky as a vertical gradient
99
+ `{ top, bottom }`), `fog: { color, near, far }` (metres from the camera) and
100
+ `ground` (the height blob shadows lie at, default 0). A mesh with `shadow:
101
+ true` (or `{ opacity, ground }`) gets a soft blob shadow on the ground under
102
+ it, which spreads and fades as the mesh lifts off. A scene with no lights gets a soft default (ambient plus a key
100
103
  light from upper right). Outlines fade into the fog too. `nearFade: { from, to }` fades geometry
101
104
  nearer the camera than `to` metres, gone at `from`, so a dive passes through
102
105
  things as if they were glass (also an option of `resolveScene3D`).
@@ -129,6 +132,85 @@ so instead of picking a winner.
129
132
  the group. `orbitPosition(target, yaw, pitch, distance)` and
130
133
  `dollyPosition(eye, target, amount)` place cameras for keyframes.
131
134
 
135
+ ## Shots and cameras
136
+
137
+ A film is a shot list, as data, over the same scene and timeline:
138
+
139
+ ```js
140
+ import { shotTracks, shotMarkers, transitionAt, withActiveCamera, cameraMoveTracks, cameraHandheldTracks } from '@algorisys/tinyfly/scene-3d'
141
+ import { drawTransition, drawLetterbox } from '@algorisys/tinyfly/adapters'
142
+
143
+ const shots = [
144
+ { id: 'establish', start: 0, end: 4000, camera: 'wide', label: 'Dolly in' },
145
+ { id: 'orbit', start: 4000, end: 7500, camera: 'orbiter', transition: { kind: 'crossfade', duration: 700 } },
146
+ { id: 'close', start: 7500, end: 10000, camera: 'close', transition: { kind: 'dipToBlack', duration: 600 } },
147
+ ]
148
+ const tracks = [
149
+ ...shotTracks(shots, 'set'), // the activeCamera track: a cut is one keyframe
150
+ ...cameraMoveTracks({ scene: 'set', camera: 'wide', start: 0, end: 4000,
151
+ from: { target: [0, 0.8, 0], yaw: 20, pitch: 18, distance: 11 }, to: { distance: 7 } }), // a dolly
152
+ ...cameraHandheldTracks([], { scene: 'set', camera: 'close', start: 7500, end: 10000,
153
+ base: { position: [1.2, 1.4, 3.6], lookAt: [0, 0.75, 1.3] }, seed: 'close' }),
154
+ ]
155
+ ```
156
+
157
+ - **Shots** are `{ id, start, end, camera, label?, transition? }`;
158
+ `checkShots` names overlaps, bad ends and a transition on the first shot;
159
+ `shotAt(shots, time)` is the shot playing; `shotMarkers` gives the
160
+ timeline's markers (stills and captions step through them).
161
+ - **Transitions** (`cut`, `crossfade`, `dipToBlack`, `wipe` with a
162
+ `direction`) start at the shot's start and last `duration` ms. Any frame can
163
+ ask `transitionAt(shots, time)` which two shots to draw and how far along
164
+ (0..1); `drawTransition(ctx, transition, { width, height, draw(ctx,
165
+ cameraId) })` draws both and blends them (a crossfade mixes, a dip covers
166
+ the cut, a wipe sweeps the new shot in), with `withActiveCamera(values,
167
+ sceneId, cameraId)` to draw the shot going out. Pure and frame-addressable:
168
+ the film renders the same in any order.
169
+ - **Camera moves** are presets that write `position`, `lookAt` (and `fov`)
170
+ tracks on the camera: `cameraMoveTracks({ from, to, easing, every })` with
171
+ poses as an orbit round a target (`yaw`, `pitch`, `distance`), or a fixed
172
+ `position` with a moving `lookAt`, or a `fov`: change `yaw` for an orbit,
173
+ `distance` for a dolly, `pitch` and `distance` for a crane, `lookAt` for a
174
+ pan or tilt, `fov` for a zoom, or any mix. `cameraFollowTracks({ subjectAt,
175
+ offset, lag })` keeps a camera on a moving subject. `cameraHandheldTracks(
176
+ tracks, { amount, aim, rate, seed })` adds a deterministic handheld shake
177
+ onto a move's tracks or a still camera's `base`.
178
+ - **Aspect and safe areas**: `drawLetterbox(ctx, canvas, '2.39:1')` paints
179
+ the bars (in a video's `overlay`), `frameRect`, `frameSize` and `safeAreas`
180
+ are the geometry, `drawSafeAreas` draws the action and title guides for
181
+ stills. `FRAME_ASPECTS` has 16:9, 2.39:1, 4:3, 1:1, 9:16 and 4:5.
182
+
183
+ `examples/headless-video/film-shots.mjs` is a three-shot film with a dolly, a
184
+ crossfade into an orbit, a dip to black into a handheld close-up, letterboxed.
185
+
186
+ ## Sets and light for mood
187
+
188
+ A set is objects like any other; what sets the mood is its light, its sky and
189
+ its fog, and those come as presets:
190
+
191
+ ```js
192
+ import { lightingPreset, lightingTracks, ground } from '@algorisys/tinyfly/scene-3d'
193
+
194
+ const light = lightingPreset('dusk') // or 'day', 'night', 'stage'
195
+ const floor = ground({ size: 20 })
196
+ const scene = {
197
+ id: 'set', camera: 'cam', background: light.background, fog: light.fog,
198
+ materials: { ...floor.materials, red: { color: '#ef4444', shading: 'toon' } },
199
+ objects: [camera, ...light.objects, ...floor.objects, { id: 'box', kind: 'mesh', geometry: { type: 'box', size: [1, 1, 1] }, material: 'red', position: [0, 0.5, 0], shadow: true }],
200
+ }
201
+ // Day turning to night over four seconds: tracks on the same lights.
202
+ const tracks = lightingTracks('day', 'night', { scene: 'set', start: 0, end: 4000 })
203
+ ```
204
+
205
+ Every preset uses the same light ids (`key`, `fill`, `sky`, and `spot` on
206
+ the stage), so `lightingTracks(from, to, { scene, start, end })` keys each
207
+ light's `color`, `intensity`, `position` and `target` from one mood to the
208
+ other (a spot only one mood has fades in or out); the sky and fog are the
209
+ scene's to set per shot. `ground({ size, color, segments, y })` is a floor
210
+ on layer −1 with its material; props from the catalog (trees, houses,
211
+ furniture) are the set pieces, placed by preset name (see Props). Blob
212
+ shadows under meshes are `shadow: true`; projected shadows are planned.
213
+
132
214
  ## Lines and trails
133
215
 
134
216
  Two more kinds of object draw a band that faces the camera, as wide as
@@ -174,7 +256,7 @@ front of the meshes. For trails on a plain 2D canvas, see `drawTrail` in
174
256
  loadScene3D(json): LoadedScene3D // validates and builds meshes once (throws with every problem)
175
257
  validateScene3D(json, tracks?): string[] // problems as sentences, empty when fine
176
258
  resolveScene3D(loaded, values, { width, height, time?, valuesAt? }): ResolvedScene3D // pure: matrices, camera, lights, sorted triangles
177
- drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt? }) // resolve and draw, in one call
259
+ drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt?, depthBuffer? }) // resolve and draw, in one call
178
260
  new Scene3DAdapter(new Canvas2DRenderer(ctx), { width, height, valuesAt? }) // registerScene, applyState(state), render()
179
261
  ```
180
262
 
@@ -272,6 +354,21 @@ phase) with the distance, one stride per cycle, so the feet stay planted, plus
272
354
  the stepping pose as it draws, on the pose it holds: a wave carries on while it
273
355
  walks. Objects take `gait` and `walking` as fields too.
274
356
 
357
+ **Speaking and looking.** `{ do: 'say', say: 'A pot of water!' }` lip-syncs
358
+ the line on the character's mouth (the same `lipSyncOver` the 2D scripts use)
359
+ with a talking head, and lasts as long as the line (`speechLength(text)`, or
360
+ `for`). `{ do: 'look', look: [x, z] }` turns the head and eyes toward a point
361
+ at eye height (`[x, y, z]` for any height, `'camera'` for the viewer with
362
+ `options.camera`); `lookFields(from, at)` is the maths. To keep looking at
363
+ something that moves, `characterLookAtTracks(tracks, { scene, character,
364
+ at: { object: 'didi' } | { camera: 'cam' } | [x, y, z] | (time) => [x, y, z],
365
+ start, end, objects })` keys `head.turn`, `head.nod`, `lookX` and `lookY`
366
+ from where both are at every moment; `objectPositionAt(tracks, target,
367
+ base)` is the sampler it uses. For several figures, `stageSpots({ count,
368
+ shape: 'line' | 'arc' | 'circle' | 'cluster', spacing, centre })` gives
369
+ positions and headings that do not overlap: a line across, an arc facing its
370
+ middle, a circle facing in, or a seeded loose group.
371
+
275
372
  **Riding.** `propRide3D({ prop, propId, propTracks, scene, placement, anchor, riderId, pose, start, end, mount?, dismount? })`
276
373
  keeps a rider's hips on a prop's seat anchor (a horse's `saddle`, a bike's or
277
374
  a cart's `seat`) as the prop moves, turns, bobs with its stride and pitches,
@@ -440,8 +537,9 @@ renderer.render(resolveScene3D(scene, values, { width: canvas.width, height: can
440
537
  trails, go on `overlay`, a 2D canvas laid over the GL one (in front of the meshes);
441
538
  solid characters are meshes and sort properly.
442
539
 
443
- It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2, so
444
- headless video uses the Canvas 2D renderer. The cross-browser checks
540
+ It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2;
541
+ headless video uses the Canvas 2D renderer, or its software depth buffer
542
+ (below) when shapes cut through each other. The cross-browser checks
445
543
  (`npm run e2e -- --check scene-3d-webgl`) compile it in Chromium, Firefox and
446
544
  WebKit, compare its silhouettes with the Canvas 2D renderer's and check the
447
545
  depth buffer.
@@ -457,5 +555,19 @@ modest, or use a layer. Each triangle has one colour, so smooth shading is
457
555
  smoothed per triangle, not per pixel; more segments look rounder. The WebGL2
458
556
  renderer (above) has a depth buffer and per-pixel light.
459
557
 
558
+ **A software depth buffer** draws right where the painter's order cannot:
559
+ `drawScene3D(ctx, scene, values, { …, depthBuffer: true })`, or
560
+ `new Scene3DAdapter(new SoftwareRenderer(ctx), …)`. Every triangle is
561
+ rasterised into a pixel buffer with a depth per pixel (`rasterizeResolvedScene`
562
+ gives the bytes and depths without a canvas), so crossing beams, huge floors
563
+ and long meshes need no `layer` or segments; see-through meshes blend over
564
+ what is behind them, and ink is depth-tested so an outline never shows
565
+ through what is in front. Each triangle keeps its one shaded colour and its
566
+ fog, edges are hard (no anti-aliasing), and objects drawn whole (characters
567
+ in their pen looks, lines, trails) go on top of the meshes, as on the WebGL2
568
+ overlay. It costs about three times the painter's time and works anywhere
569
+ the Canvas 2D renderer does. Layers keep their meaning: a lower layer is
570
+ drawn first and a higher one paints over it whatever the depths.
571
+
460
572
  Rendering speed in Node: a 1280×720 scene of a few thousand triangles renders
461
573
  at a few frames a second; parallel rendering for long films is planned.
package/docs/teaching.md CHANGED
@@ -25,7 +25,7 @@ path for all of that:
25
25
  </figure>
26
26
 
27
27
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
28
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
29
29
  ```
30
30
 
31
31
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
@@ -14,6 +14,7 @@ npx tinyfly video scene.mjs --stills stills/ # one PNG per caption line (els
14
14
  npx tinyfly video scene.mjs --stills stills/ --frames 0,79,88 # stills at chosen frames (or --times 0,2640 in ms)
15
15
  npx tinyfly video scene.mjs --loop-check # does it loop? (exit 1 when not)
16
16
  npx tinyfly video scene.mjs --scale 0.5 --fps 12 # quick preview
17
+ npx tinyfly video scene.mjs --codec prores # a ProRes 422 HQ .mov for editing elsewhere
17
18
  ```
18
19
 
19
20
  Runnable scenes are in [`examples/headless-video/`](../examples/headless-video/):
@@ -142,6 +143,38 @@ Scene modules may use top-level `await`, or default-export an async function.
142
143
  `assembleNarration(plan, clips, sampleRate)` and `encodeWav(samples, sampleRate)`
143
144
  are the pure steps underneath, for audio you generate yourself.
144
145
 
146
+ ### A sound mix
147
+
148
+ A film's sound is layers: a music bed, the narration, effects at the moments
149
+ things happen, with the music ducked under the voice. `renderMix` decodes
150
+ every file with ffmpeg, mixes them and writes one WAV for the scene's
151
+ `audio`:
152
+
153
+ ```js
154
+ import { renderMix } from '@algorisys/tinyfly/headless'
155
+
156
+ const audio = await renderMix(
157
+ [
158
+ { id: 'bed', file: 'music/bed.mp3', loop: true, gain: 0.6, fadeOut: 1500, duck: { under: 'voice', amount: 0.7 } },
159
+ { id: 'voice', file: 'build/narration.wav' },
160
+ { file: 'sfx/tap.wav', at: [1200, 2650, 4100], gain: 0.8 }, // a sound effect at three moments
161
+ { file: 'sfx/thud.wav', at: landings.map((t) => t + 40) }, // or at every landing a script reports
162
+ ],
163
+ { output: 'build/mix.wav', duration: END, baseDir: here }
164
+ )
165
+ export default { /* … */ audio }
166
+ ```
167
+
168
+ Each layer has `start` (ms) or `at` (times for a sound effect), `gain`,
169
+ `fadeIn` and `fadeOut`, `loop` for a bed shorter than the film, and `duck:
170
+ { under, amount, attack, release }` to make way for another layer while it
171
+ sounds. The whole mix is soft-limited so peaks never clip. `mixAudio(layers,
172
+ { sampleRate, duration, master })` is the pure step on samples. For cuts and
173
+ dances on the music's beat, `detectTempo(samples, sampleRate)` finds the
174
+ grid; `snapShotsToBeats(shots, grid)` moves each cut to the nearest beat,
175
+ and `danceTracks(target, { bpm: grid.bpm, start: nextBeat(grid, t) })`
176
+ dances to it.
177
+
145
178
  ## Characters
146
179
 
147
180
  `@algorisys/tinyfly/characters` has a poseable stick figure. A pose is a set of
@@ -798,6 +831,12 @@ draw(ctx, frame) {
798
831
  stay put while the camera moves.
799
832
  - `drawingRate: 12` holds the timeline's poses for two frames of 24 fps ("on
800
833
  twos"), as hand-drawn animation is timed.
834
+ - `motionBlur: { samples: 4, shutter: 0.5 }` makes each frame the average of
835
+ four drawings spread over the shutter's open time (half the frame, a 180°
836
+ shutter): fast moves streak as a camera's do. Deterministic, `samples`
837
+ times the work.
838
+ - `supersample: 2` draws at twice the size and scales down: smoother edges
839
+ on thin lines and small text (four times the work).
801
840
 
802
841
  See [acting.md](acting.md) for camera shots, beat scripts and the rest of the
803
842
  cartoon acting tools.
@@ -822,6 +861,7 @@ await renderVideo(scene, {
822
861
  output: 'out.mp4',
823
862
  baseDir: '.', // relative audio and font paths resolve against this
824
863
  scale: 1, crf: 20, preset: 'medium',
864
+ codec: 'h264', // or 'prores' for a .mov
825
865
  onProgress: (done, total) => {},
826
866
  })
827
867
  await renderStills(scene, { dir: 'stills' })
@@ -878,5 +918,8 @@ room) was ported call for call to Canvas 2D and rendered at 1920×1080, 24 fps,
878
918
  rendering) and `ffmpeg`. Rendering defines `globalThis.Path2D` from the canvas
879
919
  package when it is missing, because path targets use it.
880
920
  - Output is H.264 MP4 (`yuv420p`, odd sizes padded to even), with AAC audio when
881
- `audio` is set; video stops at the shorter of picture and sound.
921
+ `audio` is set; video stops at the shorter of picture and sound. `codec:
922
+ 'prores'` (or `--codec prores`) writes ProRes 422 HQ (10-bit, PCM audio) in
923
+ a `.mov` for an editor; any size works, 1080p and 4K included; `renderStills`
924
+ gives a PNG sequence.
882
925
  - `image` targets need images loaded with the canvas package's `loadImage`.