pixi-effects 0.30.0 → 0.31.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/CHANGELOG.md +25 -0
  2. package/README.md +6 -5
  3. package/ai/chat-template.html +3 -3
  4. package/ai/tools/check.mjs +42 -2
  5. package/ai/tools/lookup.mjs +12 -6
  6. package/ai/tools/render.mjs +15 -2
  7. package/ai/tools/varArgs.mjs +75 -0
  8. package/dist/{Base-CB1_FPZD.d.cts → Base-BKagtWc0.d.cts} +1 -1
  9. package/dist/{Base-Ne74ztNl.d.ts → Base-jRiMHcWT.d.ts} +1 -1
  10. package/dist/Composition-DQCPJPFE.js +7 -0
  11. package/dist/{Composition-RJGA7KDU.js.map → Composition-DQCPJPFE.js.map} +1 -1
  12. package/dist/Composition-V2XYSW6P.cjs +16 -0
  13. package/dist/{Composition-MUKR3FYD.cjs.map → Composition-V2XYSW6P.cjs.map} +1 -1
  14. package/dist/Controller.cjs +42 -1
  15. package/dist/Controller.cjs.map +1 -1
  16. package/dist/Controller.d.cts +10 -2
  17. package/dist/Controller.d.ts +10 -2
  18. package/dist/Controller.js +42 -1
  19. package/dist/Controller.js.map +1 -1
  20. package/dist/{Movie-DdnpLpw1.d.cts → Movie-BH81stkb.d.cts} +90 -3
  21. package/dist/{Movie-C2rZFkrO.d.ts → Movie-CfFPItoL.d.ts} +90 -3
  22. package/dist/{chunk-A3Q3SDSH.js → chunk-BGMCZA36.js} +3 -3
  23. package/dist/{chunk-A3Q3SDSH.js.map → chunk-BGMCZA36.js.map} +1 -1
  24. package/dist/{chunk-ZVUO325O.cjs → chunk-DJ5B7IKT.cjs} +9 -3
  25. package/dist/chunk-DJ5B7IKT.cjs.map +1 -0
  26. package/dist/{chunk-WHNADXXG.cjs → chunk-L73KRFXI.cjs} +61 -61
  27. package/dist/{chunk-WHNADXXG.cjs.map → chunk-L73KRFXI.cjs.map} +1 -1
  28. package/dist/{chunk-ZAXYPXKW.js → chunk-MMTESMJ5.js} +9 -4
  29. package/dist/chunk-MMTESMJ5.js.map +1 -0
  30. package/dist/{chunk-CRQFDY7E.js → chunk-UTIBYMIO.js} +461 -56
  31. package/dist/chunk-UTIBYMIO.js.map +1 -0
  32. package/dist/{chunk-HREBQAY4.cjs → chunk-X3WHETQ3.cjs} +485 -80
  33. package/dist/chunk-X3WHETQ3.cjs.map +1 -0
  34. package/dist/index.cjs +31 -31
  35. package/dist/index.d.cts +5 -5
  36. package/dist/index.d.ts +5 -5
  37. package/dist/index.js +3 -3
  38. package/dist/loader.css +1 -1
  39. package/dist/present.cjs +3 -3
  40. package/dist/present.d.cts +2 -2
  41. package/dist/present.d.ts +2 -2
  42. package/dist/present.js +3 -3
  43. package/dist/three.cjs +5 -5
  44. package/dist/three.d.cts +2 -2
  45. package/dist/three.d.ts +2 -2
  46. package/dist/three.js +1 -1
  47. package/dist/{types-BzIB65Vk.d.cts → types-CK_crNAI.d.cts} +2 -0
  48. package/dist/{types-BzIB65Vk.d.ts → types-CK_crNAI.d.ts} +2 -0
  49. package/docs/api.md +28 -1
  50. package/docs/dsl.md +32 -1
  51. package/llms-full.txt +145 -11
  52. package/package.json +83 -20
  53. package/skills/pixi-effects/SKILL.md +1 -1
  54. package/skills/pixi-effects/reference/cheatsheet.md +3 -0
  55. package/skills/pixi-effects/reference/pitfalls.md +4 -0
  56. package/skills/pixi-effects/reference/recipes.md +79 -8
  57. package/skills/pixi-effects/template.html +6 -6
  58. package/dist/Composition-MUKR3FYD.cjs +0 -16
  59. package/dist/Composition-RJGA7KDU.js +0 -7
  60. package/dist/chunk-CRQFDY7E.js.map +0 -1
  61. package/dist/chunk-HREBQAY4.cjs.map +0 -1
  62. package/dist/chunk-ZAXYPXKW.js.map +0 -1
  63. package/dist/chunk-ZVUO325O.cjs.map +0 -1
package/llms-full.txt CHANGED
@@ -6,7 +6,7 @@ Concatenation of the skill, cheatsheet, pitfalls, recipes and the DSL / API refe
6
6
 
7
7
  <!-- ===== skills/pixi-effects/SKILL.md ===== -->
8
8
 
9
- > Written for pixi-effects 0.30.0. Update this skill with `npx skills update`; the newest docs are at https://yjmtmtk.github.io/pixi-effects/
9
+ > Written for pixi-effects 0.31.0. Update this skill with `npx skills update`; the newest docs are at https://yjmtmtk.github.io/pixi-effects/
10
10
 
11
11
  # pixi-effects — write a video as data
12
12
 
@@ -138,6 +138,7 @@ Operators `+ - * /`, parentheses, unary `-`. Functions `min max abs floor ceil r
138
138
  | `w`, `h` | this layer's own size (image/video natural size, text size **after** its style is applied, shape bounds) |
139
139
  | `cover`, `contain` | scale that makes the layer cover / fit the parent (`scale: 'cover'`) |
140
140
  | `t`, `d`, `T` | layer start time, layer duration, parent duration |
141
+ | your own names | `movie.init({ vars: { shift: 0, title: 'NORD' } })`: a number is a name in an expression (`'W/2 + shift'`), any value is `{title}` inside a string (`text: '{title}'`, `fillColor: '{accent}'`). Reserved: the names above, `value`, the functions, `PI`. `await movie.setVars({ shift: 40 })` builds again at the same frame; `await movie.resize(w, h)` makes `W` / `H` follow a window. `render --var title=SÜD --size 1080x1920`, `check --size 1920x1080,1080x1920` |
141
142
 
142
143
  ## Common fields (every layer)
143
144
 
@@ -278,6 +279,8 @@ movie.play(); movie.pause();
278
279
  await movie.gotoFrame(n, true); // seek (frames; 30 fps => t = n/30)
279
280
  const blob = await movie.render({ format: 'mp4' }); // 'mp4' | 'webm' | 'mov' | 'mkv'; ~real-time. `format: 'wav'` / `'ogg'` writes only the movie's SOUND (a `music` score as an audio file). `video: { codec: 'hevc' | 'av1' | 'vp9' | 'avc', bitrate: '8M', hardware, keyFrameInterval }` (a codec this browser cannot encode names the one that works). Part of it: `range: [2, 5]` (seconds) or `range: 'title'` (a top-level layer's span; picture and sound); `scale: 0.5` / `draft: true` (half size, low quality, no motion blur: a smaller file, not a faster drawing). Fast motion: `movie.init({ motionBlur: true })` (8 samples, 180° shutter; or a number / { samples: 2–64, shutter: 0–1 }) blurs render / snapshot / contactSheet, not live playback; a render takes `samples`× as long
280
281
  movie.on('progress', e => e.progress /* 0–100 */);
282
+ await movie.setVars({ shift: 40 }); // declared variables → build again, same frame, sound mixed again only if it changed. `resize(w, h)`, `rebuild({ composition, vars, width, height })`; `movie.on('rebuilt', report => …)`; `movie.vars`
283
+ movie.loop = true // (or init({ loop: true })) playing goes back to the start at the end instead of stopping; the Controller bar has a loop button (L). playUntil() and render() ignore it
281
284
  movie.audioBuffer // mixed audio (after init), if any audio layers
282
285
  await movie.contactSheet({ count: 6, as: 'dataURL' }) // ONE image of several labelled frames — look at it. Options: frames | times | count, columns, cellWidth, as
283
286
  await movie.snapshot(60, { as: 'dataURL' }) // one frame, canvas only (no player bar) — use it for detail; sheet tiles are small
@@ -426,6 +429,9 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
426
429
  101. **A film built from one adjective looks like every other one.** Read `reference/direction.md` and write `brief.md` / `style-guide.md` / `shotlist.md` first: real assets with paths, the one sentence to remember, a row per beat with entry and exit state. If a real asset is missing, ask: a drawn fake (a logo, a dashboard, a figure) is the failure that matters. Judge the contact sheet cold: three defects, each with a timestamp, evidence and a local fix.
427
430
  102. **A vertical cut is a second composition, not a crop, and only when someone asked for it.** One source, a layout function, `?f=9x16`; `check` and `render` take `--query f=9x16` (recipe `two-formats`). Look at a contact sheet of each format: type that fits wide is tiny tall. Ask which formats are wanted; make one if the answer is open. In a 1080p film keep every line of text at 34 px or more; if you cannot read it in a sheet tile, a phone cannot.
428
431
  103. **Load a web font BEFORE you measure with it.** `measureText` / `splitText` / `animateText` measure once, when the composition is built. Measured in Chrome: "Respect the Local, Loop the Value." at 80 px Lato 900 is 1487 px wide before the Google font has arrived (the fallback) and 1231 px after; Japanese text in a similar fallback was within 3 px. Every box, line break and centred position built from the wrong width stays wrong. `await document.fonts.load('900 80px "Lato"', theTextYouUse)` first (the text argument loads exactly the glyphs you need), then build the composition.
432
+ 104. **A variable moves values, not timing, and it is read when the composition is built.** `at` and `duration` are plain numbers; `vars: { shift }` works in `x: 'W/2 + shift'` and `'{title}'` inside any string, not in `at: 'shift'`. `setVars` builds everything again (about 20 ms, plus the sound only if it changed): for a continuous input call it as often as you like, calls that overlap are joined, but do not use it for something that should move every frame (that is a keyframe).
433
+ 105. **Layout that follows the screen is written in `W` / `H` / `GW` / `GH`, never in pixels.** After `movie.resize(w, h)` an expression sees the new size; a literal `x: 960` stays at 960. A string variable cannot be read in an expression (`x: 'title'` is a number context): use `{title}` in a string, or declare the number. A name that is declared but never read, and a `{name}` that was not declared, are both said at `init` (usually a typo). Load a web font BEFORE the first `setVars` that changes a text (see 103): the text is measured again each rebuild.
434
+ 106. **A text outline used to spike; it is round-joined now.** `style: { stroke: { color: '#000', width: 12 } }` was drawn with PixiJS's default `miter` join, so the sharp corners of W, V, A, k and 4 grew spikes ("the outline sticks out"). The library now adds `join: 'round'` to an outline that names no join; say `join: 'miter'` or `'bevel'` if you want one. The stroke is centred on the glyph edge, so half of it eats into the letter: keep `width` to about a tenth of `fontSize`, or for a thick outline put a second copy of the text with the stroke UNDER the plain one.
429
435
 
430
436
 
431
437
  <!-- ===== skills/pixi-effects/reference/recipes.md ===== -->
@@ -622,6 +628,8 @@ const max = Math.max(...data.map(d => d[1]));
622
628
  const step = [1, 2, 2.5, 5, 10].map(m => m * 10 ** Math.floor(Math.log10(max / 4))).find(v => max / v <= 5) ?? 10;
623
629
  const NICE = Math.ceil(max / step) * step; // axis top, so the chart survives changed data
624
630
  const BASE = 600, CHART_H = 380, BAR_W = 90, GAP = 40, DUR = 0.9, EASE = 'power3.out';
631
+ const EACH = 0.12; // seconds between bars: 0.12 is a quick wave; EACH = DUR + 0.3 grows them one at a time
632
+ const PEAK_AT = Math.max(4, 0.4 + (data.length - 1) * EACH + DUR + 0.2); // the highlight and the callout come after the last bar has grown
625
633
  const X0 = (1280 - (data.length * BAR_W + (data.length - 1) * GAP)) / 2, X1 = X0 + data.length * BAR_W + (data.length - 1) * GAP;
626
634
  const sequences = [];
627
635
  for (let v = 0; v <= NICE; v += step) { // grid lines + tick labels
@@ -632,14 +640,14 @@ for (let v = 0; v <= NICE; v += step) { // grid lines + ti
632
640
  const best = data.findIndex(d => d[1] === max);
633
641
  data.forEach(([label, value], i) => {
634
642
  const x = X0 + i * (BAR_W + GAP) + BAR_W / 2;
635
- const at = 0.4 + i * 0.12;
643
+ const at = 0.4 + i * EACH;
636
644
  const h = CHART_H * value / NICE;
637
645
  sequences.push({
638
646
  type: 'shape', shape: 'rect', width: BAR_W, height: 0, cornerRadius: 8, anchorY: 1, at, colorSpace: 'oklab',
639
647
  initial: { x, y: BASE, fillColor: '#4f6df5' },
640
648
  keyframes: [
641
649
  { at: 0, to: { height: h }, duration: DUR, ease: EASE },
642
- ...(i === best ? [{ at: 4 - at, to: { fillColor: '#ffd166' }, duration: 0.5 }] : [{ at: 4 - at, to: { alpha: 0.45 }, duration: 0.5 }]), // highlight the maximum at t = 4 s
650
+ ...(i === best ? [{ at: PEAK_AT - at, to: { fillColor: '#ffd166' }, duration: 0.5 }] : [{ at: PEAK_AT - at, to: { alpha: 0.45 }, duration: 0.5 }]), // highlight the maximum at t = 4 s
643
651
  ],
644
652
  });
645
653
  sequences.push({ // value label: counts up while riding the bar's top
@@ -653,11 +661,11 @@ data.forEach(([label, value], i) => {
653
661
  // callout: a pill sized from its text (~0.58 x fontSize per glyph + padding), a pointer triangle, clamped inside the plot
654
662
  const text = 'Peak: ' + data[best][0] + ' ' + max, FS = 26;
655
663
  const PW = text.length * FS * 0.58 + 44, cx = Math.min(Math.max(X0 + best * (BAR_W + GAP) + BAR_W / 2, X0 + PW / 2), X1 - PW / 2), cy = BASE - CHART_H - 70;
656
- sequences.push({ type: 'shape', shape: 'rect', width: PW, height: 52, cornerRadius: 26, at: 4.2, initial: { x: cx, y: cy, fillColor: '#ffd166', alpha: 0 },
664
+ sequences.push({ type: 'shape', shape: 'rect', width: PW, height: 52, cornerRadius: 26, at: PEAK_AT + 0.2, initial: { x: cx, y: cy, fillColor: '#ffd166', alpha: 0 },
657
665
  keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
658
- sequences.push({ type: 'shape', shape: 'polygon', points: [[-10, 0], [10, 0], [0, 12]], at: 4.2, initial: { x: cx, y: cy + 32, fillColor: '#ffd166', alpha: 0 },
666
+ sequences.push({ type: 'shape', shape: 'polygon', points: [[-10, 0], [10, 0], [0, 12]], at: PEAK_AT + 0.2, initial: { x: cx, y: cy + 32, fillColor: '#ffd166', alpha: 0 },
659
667
  keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
660
- sequences.push({ type: 'text', text, at: 4.2, style: { fontSize: FS, fontWeight: 'bold', fill: '#1b1b2f' }, initial: { x: cx, y: cy, anchorX: 0.5, anchorY: 0.5, alpha: 0 },
668
+ sequences.push({ type: 'text', text, at: PEAK_AT + 0.2, style: { fontSize: FS, fontWeight: 'bold', fill: '#1b1b2f' }, initial: { x: cx, y: cy, anchorX: 0.5, anchorY: 0.5, alpha: 0 },
661
669
  keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
662
670
  return sequences;
663
671
  ```
@@ -788,6 +796,23 @@ return { sequences, transitions, duration: total };
788
796
 
789
797
  Source images should be at least canvas-sized (`kenBurns` zooms in): draw generated images at 1920×1080 for a 1280×720 movie.
790
798
 
799
+ **A plain cut instead of a transition, generated images, music with no file:** scenes are layers one after the other (`at` = `i × L`) with no `transitions`; the images are the assets `p1…p3` (draw them with `placeholderPhoto`, recipe `placeholder-images`). The tune is written as text: at 96 bpm a beat is 0.625 s, so 24 beats are 15 s and every track has to add up to 24 (the check's `music` read-back shows each track's length).
800
+
801
+ ```js
802
+ // @recipe slideshow-cuts
803
+ const N = 3, L = 5, total = N * L;
804
+ const sequences = Array.from({ length: N }, (_, i) =>
805
+ kenBurns({ asset: 'p' + (i + 1), name: 'scene' + i, at: i * L, duration: L, motion: i % 2 ? 'position' : 'scale' }));
806
+ sequences.push({ type: 'audio', at: 0, volume: 0.7, duration: total, music: {
807
+ bpm: 96,
808
+ tracks: [
809
+ { inst: 'pad', notes: 'Am:4 F:4 C:4 G:4 Am:4 F:4' }, // 6 chords x 4 beats = 24 beats = 15 s
810
+ { inst: 'bass', notes: 'a1:4 f1:4 c2:4 g1:4 a1:4 f1:4' },
811
+ ],
812
+ } });
813
+ return { sequences, duration: total };
814
+ ```
815
+
791
816
  ---
792
817
 
793
818
  ## Music with no file (`music`)
@@ -1088,7 +1113,7 @@ return { duration: d.duration, sequences: d.composition.sequences, transitions:
1088
1113
  ```
1089
1114
 
1090
1115
  ```js
1091
- // @docs-only
1116
+ // @docs-only deck-in-page
1092
1117
  // in the page: the deck is spread into init; the Presenter (or the Controller, which then shows the stops and a Present button) plays it
1093
1118
  import { Movie } from 'pixi-effects';
1094
1119
  import { deck, Presenter } from 'pixi-effects/present'; // (add "pixi-effects/present" to the import map)
@@ -1457,7 +1482,7 @@ return [{ type: 'composition', name: 'film', width: 'GW', height: 'GH', sequence
1457
1482
  Draw on a canvas and register `canvas.toDataURL()` as an asset (`data:` URLs work). Make the image at least canvas-sized (1920×1080 for a 1280×720 movie) so `kenBurns` zooms stay sharp.
1458
1483
 
1459
1484
  ```js
1460
- // @docs-only
1485
+ // @docs-only placeholder-images
1461
1486
  function placeholderPhoto(name, hueA, hueB, w = 1920, h = 1080) {
1462
1487
  const c = Object.assign(document.createElement('canvas'), { width: w, height: h });
1463
1488
  const g = c.getContext('2d');
@@ -1476,7 +1501,7 @@ function placeholderPhoto(name, hueA, hueB, w = 1920, h = 1080) {
1476
1501
  `ctx.renderer` is a normal `WebGLRenderer`, so an environment map works; lights alone make `metalness: 1` look black. `three/addons` is not in the importmap: build the environment yourself. Size the layer to the area you want (it clips at its own rectangle) and pull the camera back (`z ≈ 5.4` for a radius-1 torus knot at fov 50).
1477
1502
 
1478
1503
  ```js
1479
- // @docs-only
1504
+ // @docs-only metallic-three
1480
1505
  // registerThree(); const THREE = await import('three');
1481
1506
  three({
1482
1507
  type: 'three', width: 'GW * 0.56', height: 'GH * 0.9', initial: { x: 'GW * 0.77', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
@@ -1588,6 +1613,57 @@ while IFS=, read -r name score; do
1588
1613
  done < table.csv
1589
1614
  ```
1590
1615
 
1616
+ ---
1617
+
1618
+ ## One film, several languages and colours (variables)
1619
+
1620
+ Declare what changes as `vars` and write `{name}` in the strings and the names as identifiers in the expressions. One page then makes every variant: `pixi-effects render film.html --var lang=ja --var accent=#3949ab -o film-ja.mp4`, and a page can switch live with `movie.setVars(...)`. Load the fonts of every language before the first build (pitfall 103); `check` says a variable nothing reads, and a `{name}` nobody declared.
1621
+
1622
+ ```js
1623
+ // @docs-only variants
1624
+ const COPY = { en: { head: 'Spring sale', sub: 'Up to 40% off' }, ja: { head: '春のセール', sub: '最大40%オフ' } };
1625
+ const lang = new URLSearchParams(location.search).get('lang') ?? 'en';
1626
+ await movie.init({
1627
+ canvas, width: 1920, height: 1080, duration: 5,
1628
+ vars: { head: COPY[lang].head, sub: COPY[lang].sub, accent: '#e5399a', lift: 0 }, // numbers can be read in expressions, any value in {name}
1629
+ composition: { sequences: [
1630
+ { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#12151f' } },
1631
+ { type: 'text', text: '{head}', at: 0.3, duration: 4.7, style: { fontSize: 120, fontWeight: 'bold', fill: '{accent}' },
1632
+ initial: { x: 'GW/2', y: 'GH/2 - 40 - lift', anchorX: 0.5, anchorY: 0.5 }, keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.6 }] },
1633
+ { type: 'text', text: '{sub}', at: 0.9, duration: 4.1, style: { fontSize: 56, fill: '#ffffff' },
1634
+ initial: { x: 'GW/2', y: 'GH/2 + 80', anchorX: 0.5, anchorY: 0.5 }, keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.6 }] },
1635
+ ] },
1636
+ });
1637
+ // later, from a button: await movie.setVars({ head: COPY.ja.head, sub: COPY.ja.sub, accent: '#3949ab' }); // same frame, sound untouched
1638
+ ```
1639
+
1640
+ ---
1641
+
1642
+ ## A layout that follows the window (liquid)
1643
+
1644
+ `resize(w, h)` builds the composition again at that size, and every expression sees it as `W` / `H` / `GW` / `GH`: write the layout in those, never in pixels. For a different arrangement per shape (wide / tall) write the composition in a function of the size and hand it to `rebuild`. Watch a **box** that you size with CSS (`#box { width: 100vw; height: 100vh }`, the canvas inside it `width: 100%; height: 100%`), not the canvas: the movie sets the canvas's pixel size, and an observer on the canvas would see its own change and grow it again. `check --size 1920x1080,1080x1920` makes a contact sheet and a layout review for each size without a browser window.
1645
+
1646
+ ```js
1647
+ // @docs-only liquid-layout
1648
+ const layout = (w, h) => {
1649
+ const tall = h > w;
1650
+ return { sequences: [
1651
+ { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#12151f' } },
1652
+ { type: 'text', text: 'Headline', style: { fontSize: tall ? 'GW * 0.12' : 'GH * 0.14', fontWeight: 'bold', fill: '#ffffff' },
1653
+ initial: { x: tall ? 'GW * 0.08' : 'GW/2', y: tall ? 'GH * 0.7' : 'GH/2', anchorX: tall ? 0 : 0.5, anchorY: 0.5 } },
1654
+ ] };
1655
+ };
1656
+ // <div id="box" style="width:100vw;height:100vh"><canvas id="stage" style="width:100%;height:100%;display:block"></canvas></div>
1657
+ const box = document.getElementById('box');
1658
+ const pixels = () => [Math.round(box.clientWidth * devicePixelRatio), Math.round(box.clientHeight * devicePixelRatio)];
1659
+ const [w0, h0] = pixels();
1660
+ await movie.init({ canvas, width: w0, height: h0, duration: 6, composition: layout(w0, h0) });
1661
+ new ResizeObserver(() => {
1662
+ const [w, h] = pixels();
1663
+ movie.rebuild({ composition: layout(w, h), width: w, height: h }).catch(console.error); // overlapping calls are joined: only the latest size is built
1664
+ }).observe(box);
1665
+ ```
1666
+
1591
1667
 
1592
1668
  <!-- ===== skills/pixi-effects/reference/direction.md ===== -->
1593
1669
 
@@ -1806,7 +1882,7 @@ A layer is **not removed** when its lifespan `[at, at + duration)` ends: it is o
1806
1882
 
1807
1883
  ### `text`
1808
1884
 
1809
- Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content can change over time (see *Changing text* below): a `{value}` placeholder prints an animatable number (counters), a keyframe `set: { text: '…' }` swaps the string, and `visibleChars` types it out. Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
1885
+ Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time (an outline `stroke: { color, width }` is **round-joined** unless you give `join`: PixiJS's own default, `miter`, grows spikes on the sharp corners of W, V, A, k; the stroke is centred on the glyph edge, so half its width covers the fill: keep `width` to about a tenth of `fontSize`, or put a second, stroked copy of the text under the plain one for a thick outline) — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content can change over time (see *Changing text* below): a `{value}` placeholder prints an animatable number (counters), a keyframe `set: { text: '…' }` swaps the string, and `visibleChars` types it out. Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
1810
1886
 
1811
1887
  ```ts
1812
1888
  {
@@ -2819,6 +2895,8 @@ No comparison, conditional, bitwise, or string operators — keep it numeric (`s
2819
2895
 
2820
2896
  ### Scope variables
2821
2897
 
2898
+ (Your own names, set from outside, are [Variables](#variables) below.)
2899
+
2822
2900
  Each sequence has its own scope, computed at build time:
2823
2901
 
2824
2902
  | Name | Meaning |
@@ -2854,6 +2932,35 @@ style: { fontSize: 'min(GW, GH) * 0.06' }
2854
2932
  initial: { x: 'GW/2', y: 'GH * 0.96', anchorX: 0.5, anchorY: 1 }
2855
2933
  ```
2856
2934
 
2935
+ ### Variables
2936
+
2937
+ A **variable** is a name with a value you can change after the movie is built: the language of a title, a brand colour, an offset, the screen size. Declare them once in `movie.init`; the composition reads them by name.
2938
+
2939
+ ```ts
2940
+ await movie.init({
2941
+ vars: { title: 'NORD', accent: '#e5399a', shift: 0 }, // a number or a string; no booleans (write 0 / 1)
2942
+ composition: { sequences: [
2943
+ { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '{accent}' } },
2944
+ { type: 'text', text: '{title}', initial: { x: 'W/2 + shift', y: 'H/2' } },
2945
+ ] },
2946
+ });
2947
+ await movie.setVars({ title: 'SÜD', shift: 40 }); // builds the composition again, at the same frame
2948
+ ```
2949
+
2950
+ | Where | How it reads a variable |
2951
+ | --- | --- |
2952
+ | a numeric expression (`x`, `scale`, `width`, `fontSize` … any value that takes an [expression](#expressions)) | the **name**, like `W` or `GW`: `'W/2 + shift'`. Only number variables. |
2953
+ | any string anywhere in the composition (`text`, a colour, `asset`, a layer `name`, nested layers) | **`{name}`**: `'{title}'`, `'#{hex}'`, `'{lang}-logo'`. The text is replaced before the layer is built. A `{name}` that was not declared stays as written (`{value}` is the [counter](#counters-value) of a text layer, so it is also a name no variable can take). `$` is not used: it is a price (`'$5'`). |
2954
+
2955
+ Rules, all checked when the movie is built (each warning says what to change):
2956
+ - A name is letters, digits and `_`, not starting with a digit. These are **reserved** and are refused: `w h W H GW GH t d T contain cover value`, every expression function (`min max abs … step rand noise lerp clamp smoothstep mod`) and `PI`.
2957
+ - A variable that nothing reads (no `{name}` in a string, no use in an expression) is said: it is usually a typo on one side. A `{name}` that was not declared says the declared name it looks like.
2958
+ - Values are read **when the composition is built**, once (not every frame). `at` and `duration` are plain numbers, so a variable moves values, not timing; to change the structure in time, call `movie.rebuild({ composition })` with a composition made by your own function.
2959
+ - `setVars` of a name that was not declared is ignored with a did-you-mean; `setVars` of the values it already has does nothing.
2960
+ - Everything is built again, the playhead stays at the same frame, a playing movie keeps playing, and the sound is mixed again **only if** the sound changed. See [`movie.rebuild`](api.md#movie-variables-and-rebuilding-vars-setvars-resize-rebuild).
2961
+ - A video file is a function of the script **and** the variables: `pixi-effects render page.html --var title=SÜD --var shift=40`, `check --size 1920x1080,1080x1920` (a contact sheet per size).
2962
+ - Layout that should follow the screen size uses `W` / `H` / `GW` / `GH`, not pixels: after `movie.resize(w, h)` they are the new size.
2963
+
2857
2964
  ---
2858
2965
 
2859
2966
  ## Stops (presentations)
@@ -3454,6 +3561,8 @@ interface MovieOptions {
3454
3561
  canvas?: HTMLCanvasElement; // existing canvas to render into; otherwise PixiJS creates one
3455
3562
  assets?: AssetSpec[]; // [{ name, src }]
3456
3563
  composition?: CompositionSpec; // root composition (see DSL reference)
3564
+ vars?: Record<string, number | string>; // named values the composition reads: a number as a name in an expression, any as {name} in a string (see Variables)
3565
+ loop?: boolean; // start with movie.loop on: playing goes back to the start at the end (default false, like a <video>)
3457
3566
  poster?: number; // seconds: the frame shown before play (negative: from the end), see movie.poster
3458
3567
  motionBlur?: boolean | number | { samples?: number; shutter?: number }; // blur for render() / snapshot() / contactSheet(), not live playback; see Motion blur
3459
3568
  loader?: HTMLElement | string | false; // the page's loader (see pixi-effects/loader.css): shows how far init is (a bar, "BUILDING LAYERS 62%"), faded out when ready, stopped if init fails; default: a .pe-loader next to the canvas
@@ -3490,6 +3599,25 @@ Play, and pause exactly at `seconds` (the frame `round(seconds × frameRate)`).
3490
3599
 
3491
3600
  Look around and put the movie back: pauses, runs `fn` (seek, take pictures with `snapshot()`; the seeks made inside are not reported as `seeking` / `seeked`), then puts the playhead (or the poster) back where it was, whatever `fn` did, and returns what `fn` returned. `stopImages()` and `inspectStops()` (`pixi-effects/present`) are made with it.
3492
3601
 
3602
+ ### Movie variables and rebuilding: `vars`, `setVars()`, `resize()`, `rebuild()`
3603
+
3604
+ Variables are declared in `init({ vars: { title: 'NORD', shift: 0 } })` and read by the composition (see [Variables](dsl.md#variables)). Changing one builds the composition again: the new one is built off the stage first and swapped in when it is whole, at the same frame; a failure leaves the old one in place.
3605
+
3606
+ ```ts
3607
+ movie.vars // the current values (a copy)
3608
+ await movie.setVars({ shift: 40 }); // the declared names only (others: ignored with a did-you-mean); the same values: nothing happens
3609
+ await movie.resize(1080, 1920); // the movie's size; W / H / GW / GH follow. Beats a width / height the composition names
3610
+ await movie.rebuild({ composition, vars, width, height }); // the general form: any of the four; `composition` replaces the whole spec (your layout function, called again)
3611
+ // all three resolve to a report, and fire 'rebuilt' with it:
3612
+ interface RebuildReport { reason: 'vars' | 'resize' | 'rebuild'; ms: number; audio: 'reused' | 'mixed' | 'none'; frame: number; playing: boolean; unchanged?: true }
3613
+ ```
3614
+
3615
+ - The new composition is built while the old one goes on; at the swap the movie keeps doing what it is doing at that moment: the same frame, playing or paused (a `pause()`, a seek or a `play()` you made during the build is kept), the poster if it was shown. A playing movie whose sound is unchanged (`audio: 'reused'`) is not stopped at all: the frame clock and the sound go on and only the picture is swapped, so rebuilds in a row (a pointer) do not hold the playhead back. When the sound changed, the movie stops and plays on from the same frame with the new sound. A `playUntil()` in flight ends. The canvas changes size at the swap, not before. A `render()` or `peek()` in flight is not interrupted: the swap waits for it.
3616
+ - The sound is mixed only when it changed: `audio: 'reused'` means the same mix as before (the mix is the slow part, 0.6 to 0.8 s for a film; the rest takes about 20 ms). A time remap (`warp` / `sourceMap`) turns the cache off.
3617
+ - Calls that arrive during a rebuild are joined: at most one rebuild runs and one waits, with the latest values. Safe to call from `pointermove` or `scroll`: a rebuild that leaves the sound alone takes tens of milliseconds (11 to 42 ms on four gallery pieces), one that mixes the sound again 0.6 to 0.8 s, so a slider that changes the sound will lag behind the hand.
3618
+ - A rebuild that fails (a bad expression, a missing asset, a size that is not pixels) rejects, emits `error` with `where: 'rebuild'`, and the movie goes on with what it had. A `destroy()` during a rebuild ends it the same way.
3619
+ - To follow a window: observe a CSS-sized box around the canvas, not the canvas itself (the movie sets the canvas's pixel size): `new ResizeObserver(() => movie.resize(Math.round(box.clientWidth * devicePixelRatio), Math.round(box.clientHeight * devicePixelRatio))).observe(box)` (the `liquid-layout` recipe).
3620
+
3493
3621
  ### `movie.snapshot(frame?, options?): Promise<Blob | string>`
3494
3622
 
3495
3623
  ```ts
@@ -3673,7 +3801,9 @@ movie.off(event, fn): this
3673
3801
  | `'seeking'` / `'seeked'` | `{ frame, totalFrames }` (the frame it lands on) | a `gotoFrame()` to another frame starts / has finished. NOT emitted for playback ticks, `render()`, `snapshot()` or `contactSheet()` |
3674
3802
  | `'ended'` | none | playback ran off the end (after `'pause'`); pausing by hand does not emit it |
3675
3803
  | `'volumechange'` | `{ volume: number; muted: boolean }` | `volume` or `muted` really changed (clamping counts) |
3676
- | `'error'` | `{ where: 'init' \| 'render' \| 'playback'; message: string; error: unknown }` | `init()` / `render()` failed (the call still rejects), or a frame failed during playback |
3804
+ | `'loopchange'` | `{ loop: boolean }` | `movie.loop` really changed (the first value from `init({ loop })` is not a change) |
3805
+ | `'error'` | `{ where: 'init' \| 'render' \| 'playback' \| 'rebuild'; message: string; error: unknown }` | `init()` / `render()` / a rebuild failed (the call still rejects), or a frame failed during playback |
3806
+ | `'rebuilt'` | `RebuildReport` (see above) | a `setVars()` / `resize()` / `rebuild()` built the composition again (not for a call that changed nothing) |
3677
3807
 
3678
3808
  The names are the ones an HTML5 `<video>` uses, so a player written for `<video>` ports over.
3679
3809
 
@@ -3692,8 +3822,10 @@ The names are the ones an HTML5 `<video>` uses, so a player written for `<video>
3692
3822
  | `background` | string | CSS color |
3693
3823
  | `volume` | number | 0..1 getter/setter; immediate. Setter clamps and applies to active audio |
3694
3824
  | `muted` | boolean | getter/setter; immediate |
3825
+ | `loop` | boolean | getter/setter, default `false`. When true, an ordinary `play()` that reaches the end goes back to the start and plays on: no `ended`, no `pause` / `play` events at the wrap, the sound starts again (a short gap). `playUntil()` and `render()` ignore it. Say `loopchange` when it changes |
3695
3826
  | `app` | `pixi.js Application \| null` | PIXI Application instance (advanced/escape hatch) |
3696
3827
  | `timeline` | `Timeline \| null` | the movie's timeline (advanced): `time(t)`, `duration()`, `segments()` |
3828
+ | `vars` | `Record<string, number \| string>` | the current variable values (a copy) |
3697
3829
  | `stops` | `Stop[]` | the composition's stops: named times (see Presentations); empty for an ordinary movie |
3698
3830
 
3699
3831
  ### Presentations: `stops` and `pixi-effects/present`
@@ -3867,6 +3999,7 @@ interface ControllerOptions {
3867
3999
  exportButton?: boolean; // default true; false hides ⬇ + popover
3868
4000
  keyboard?: boolean; // default true
3869
4001
  presentButton?: boolean; // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
4002
+ loopButton?: boolean; // default true: a loop button next to the volume (and the L key) that flips movie.loop
3870
4003
  pauseAtStops?: boolean; // default true: with stops, play / Space / click on the picture play to the next stop and pause; false plays straight through
3871
4004
  clickToPlay?: boolean; // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
3872
4005
  className?: string; // default 'movie-controller'
@@ -3935,6 +4068,7 @@ Active when `keyboard: true` and the key target is not `<input>`/`<textarea>`/`<
3935
4068
  | `←` / `→` | step ±1 frame |
3936
4069
  | `↑` / `↓` | volume ±5% (clears mute when increasing past zero) |
3937
4070
  | `M` | toggle mute |
4071
+ | `L` | toggle loop (`movie.loop`) |
3938
4072
  | `Shift+E` | export with current settings (skips the popover) |
3939
4073
  | `F` | toggle fullscreen |
3940
4074
  | `Esc` | close the export popover or exit fullscreen (browser) |
package/package.json CHANGED
@@ -1,42 +1,99 @@
1
1
  {
2
2
  "name": "pixi-effects",
3
- "version": "0.30.0",
3
+ "version": "0.31.0",
4
4
  "description": "Declarative composition and video rendering for the web. Built on PixiJS v8.",
5
5
  "type": "module",
6
6
  "exports": {
7
7
  ".": {
8
- "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
9
- "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
8
+ "import": {
9
+ "types": "./dist/index.d.ts",
10
+ "default": "./dist/index.js"
11
+ },
12
+ "require": {
13
+ "types": "./dist/index.d.cts",
14
+ "default": "./dist/index.cjs"
15
+ }
10
16
  },
11
17
  "./controller": {
12
- "import": { "types": "./dist/Controller.d.ts", "default": "./dist/Controller.js" },
13
- "require": { "types": "./dist/Controller.d.cts", "default": "./dist/Controller.cjs" }
18
+ "import": {
19
+ "types": "./dist/Controller.d.ts",
20
+ "default": "./dist/Controller.js"
21
+ },
22
+ "require": {
23
+ "types": "./dist/Controller.d.cts",
24
+ "default": "./dist/Controller.cjs"
25
+ }
14
26
  },
15
27
  "./loader.css": "./dist/loader.css",
16
28
  "./present": {
17
- "import": { "types": "./dist/present.d.ts", "default": "./dist/present.js" },
18
- "require": { "types": "./dist/present.d.cts", "default": "./dist/present.cjs" }
29
+ "import": {
30
+ "types": "./dist/present.d.ts",
31
+ "default": "./dist/present.js"
32
+ },
33
+ "require": {
34
+ "types": "./dist/present.d.cts",
35
+ "default": "./dist/present.cjs"
36
+ }
19
37
  },
20
38
  "./three": {
21
- "import": { "types": "./dist/three.d.ts", "default": "./dist/three.js" },
22
- "require": { "types": "./dist/three.d.cts", "default": "./dist/three.cjs" }
39
+ "import": {
40
+ "types": "./dist/three.d.ts",
41
+ "default": "./dist/three.js"
42
+ },
43
+ "require": {
44
+ "types": "./dist/three.d.cts",
45
+ "default": "./dist/three.cjs"
46
+ }
23
47
  }
24
48
  },
25
49
  "main": "./dist/index.cjs",
26
50
  "module": "./dist/index.js",
27
51
  "types": "./dist/index.d.ts",
28
- "bin": { "pixi-effects": "ai/tools/pixi-effects.mjs" },
29
- "files": ["dist", "ai", "skills", "docs/dsl.md", "docs/api.md", "llms.txt", "llms-full.txt", "CHANGELOG.md", "README.md", "LICENSE"],
52
+ "bin": {
53
+ "pixi-effects": "ai/tools/pixi-effects.mjs"
54
+ },
55
+ "files": [
56
+ "dist",
57
+ "ai",
58
+ "skills",
59
+ "docs/dsl.md",
60
+ "docs/api.md",
61
+ "llms.txt",
62
+ "llms-full.txt",
63
+ "CHANGELOG.md",
64
+ "README.md",
65
+ "LICENSE"
66
+ ],
30
67
  "keywords": [
31
- "pixi", "pixijs", "video", "composition", "compositing", "rendering",
32
- "after-effects", "motion-graphics", "timeline", "webgl", "keyframe", "typescript",
33
- "three", "threejs"
68
+ "pixi",
69
+ "pixijs",
70
+ "video",
71
+ "composition",
72
+ "compositing",
73
+ "rendering",
74
+ "after-effects",
75
+ "motion-graphics",
76
+ "timeline",
77
+ "webgl",
78
+ "keyframe",
79
+ "typescript",
80
+ "three",
81
+ "threejs"
34
82
  ],
35
83
  "license": "MIT",
36
- "author": { "name": "tefista", "email": "tefista.dev@gmail.com", "url": "https://x.com/t_yjm" },
37
- "repository": { "type": "git", "url": "git+https://github.com/yjmtmtk/pixi-effects.git" },
84
+ "author": {
85
+ "name": "tefista",
86
+ "email": "tefista.dev@gmail.com",
87
+ "url": "https://x.com/t_yjm"
88
+ },
89
+ "repository": {
90
+ "type": "git",
91
+ "url": "git+https://github.com/yjmtmtk/pixi-effects.git"
92
+ },
38
93
  "homepage": "https://github.com/yjmtmtk/pixi-effects#readme",
39
- "bugs": { "url": "https://github.com/yjmtmtk/pixi-effects/issues" },
94
+ "bugs": {
95
+ "url": "https://github.com/yjmtmtk/pixi-effects/issues"
96
+ },
40
97
  "sideEffects": [
41
98
  "./dist/loader.css"
42
99
  ],
@@ -67,8 +124,12 @@
67
124
  "pixi-filters": "^6.1.0"
68
125
  },
69
126
  "peerDependenciesMeta": {
70
- "three": { "optional": true },
71
- "pixi-filters": { "optional": true }
127
+ "three": {
128
+ "optional": true
129
+ },
130
+ "pixi-filters": {
131
+ "optional": true
132
+ }
72
133
  },
73
134
  "devDependencies": {
74
135
  "tsup": "^8.0.0",
@@ -82,5 +143,7 @@
82
143
  "three": "^0.185.1",
83
144
  "@types/three": "^0.185.0"
84
145
  },
85
- "engines": { "node": ">=18" }
146
+ "engines": {
147
+ "node": ">=18"
148
+ }
86
149
  }
@@ -3,7 +3,7 @@ name: pixi-effects
3
3
  description: Use when asked to make, animate, preview or export a video, motion graphics, an animated title, a lower third, kinetic type, a promo, a slideshow with transitions, an animated chart or data story, a social clip, a 2.5D / depth scene, or music and sound for a video, written as code in JavaScript or HTML. pixi-effects is a JS library where a video is a plain-object composition (text, shape, image, video, audio and file-free sfx / music, camera, light and shader layers with keyframes) that plays in the browser, is checked by a tool the agent can run, and exports MP4 / WebM / MOV with no server. Not for a project that already uses another video tool (Remotion, Motion Canvas, ffmpeg); follow that tool instead.
4
4
  ---
5
5
 
6
- > Written for pixi-effects 0.30.0. Update this skill with `npx skills update`; the newest docs are at https://yjmtmtk.github.io/pixi-effects/
6
+ > Written for pixi-effects 0.31.0. Update this skill with `npx skills update`; the newest docs are at https://yjmtmtk.github.io/pixi-effects/
7
7
 
8
8
  # pixi-effects — write a video as data
9
9
 
@@ -29,6 +29,7 @@ Operators `+ - * /`, parentheses, unary `-`. Functions `min max abs floor ceil r
29
29
  | `w`, `h` | this layer's own size (image/video natural size, text size **after** its style is applied, shape bounds) |
30
30
  | `cover`, `contain` | scale that makes the layer cover / fit the parent (`scale: 'cover'`) |
31
31
  | `t`, `d`, `T` | layer start time, layer duration, parent duration |
32
+ | your own names | `movie.init({ vars: { shift: 0, title: 'NORD' } })`: a number is a name in an expression (`'W/2 + shift'`), any value is `{title}` inside a string (`text: '{title}'`, `fillColor: '{accent}'`). Reserved: the names above, `value`, the functions, `PI`. `await movie.setVars({ shift: 40 })` builds again at the same frame; `await movie.resize(w, h)` makes `W` / `H` follow a window. `render --var title=SÜD --size 1080x1920`, `check --size 1920x1080,1080x1920` |
32
33
 
33
34
  ## Common fields (every layer)
34
35
 
@@ -169,6 +170,8 @@ movie.play(); movie.pause();
169
170
  await movie.gotoFrame(n, true); // seek (frames; 30 fps => t = n/30)
170
171
  const blob = await movie.render({ format: 'mp4' }); // 'mp4' | 'webm' | 'mov' | 'mkv'; ~real-time. `format: 'wav'` / `'ogg'` writes only the movie's SOUND (a `music` score as an audio file). `video: { codec: 'hevc' | 'av1' | 'vp9' | 'avc', bitrate: '8M', hardware, keyFrameInterval }` (a codec this browser cannot encode names the one that works). Part of it: `range: [2, 5]` (seconds) or `range: 'title'` (a top-level layer's span; picture and sound); `scale: 0.5` / `draft: true` (half size, low quality, no motion blur: a smaller file, not a faster drawing). Fast motion: `movie.init({ motionBlur: true })` (8 samples, 180° shutter; or a number / { samples: 2–64, shutter: 0–1 }) blurs render / snapshot / contactSheet, not live playback; a render takes `samples`× as long
171
172
  movie.on('progress', e => e.progress /* 0–100 */);
173
+ await movie.setVars({ shift: 40 }); // declared variables → build again, same frame, sound mixed again only if it changed. `resize(w, h)`, `rebuild({ composition, vars, width, height })`; `movie.on('rebuilt', report => …)`; `movie.vars`
174
+ movie.loop = true // (or init({ loop: true })) playing goes back to the start at the end instead of stopping; the Controller bar has a loop button (L). playUntil() and render() ignore it
172
175
  movie.audioBuffer // mixed audio (after init), if any audio layers
173
176
  await movie.contactSheet({ count: 6, as: 'dataURL' }) // ONE image of several labelled frames — look at it. Options: frames | times | count, columns, cellWidth, as
174
177
  await movie.snapshot(60, { as: 'dataURL' }) // one frame, canvas only (no player bar) — use it for detail; sheet tiles are small
@@ -131,3 +131,7 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
131
131
  101. **A film built from one adjective looks like every other one.** Read `reference/direction.md` and write `brief.md` / `style-guide.md` / `shotlist.md` first: real assets with paths, the one sentence to remember, a row per beat with entry and exit state. If a real asset is missing, ask: a drawn fake (a logo, a dashboard, a figure) is the failure that matters. Judge the contact sheet cold: three defects, each with a timestamp, evidence and a local fix.
132
132
  102. **A vertical cut is a second composition, not a crop, and only when someone asked for it.** One source, a layout function, `?f=9x16`; `check` and `render` take `--query f=9x16` (recipe `two-formats`). Look at a contact sheet of each format: type that fits wide is tiny tall. Ask which formats are wanted; make one if the answer is open. In a 1080p film keep every line of text at 34 px or more; if you cannot read it in a sheet tile, a phone cannot.
133
133
  103. **Load a web font BEFORE you measure with it.** `measureText` / `splitText` / `animateText` measure once, when the composition is built. Measured in Chrome: "Respect the Local, Loop the Value." at 80 px Lato 900 is 1487 px wide before the Google font has arrived (the fallback) and 1231 px after; Japanese text in a similar fallback was within 3 px. Every box, line break and centred position built from the wrong width stays wrong. `await document.fonts.load('900 80px "Lato"', theTextYouUse)` first (the text argument loads exactly the glyphs you need), then build the composition.
134
+ 104. **A variable moves values, not timing, and it is read when the composition is built.** `at` and `duration` are plain numbers; `vars: { shift }` works in `x: 'W/2 + shift'` and `'{title}'` inside any string, not in `at: 'shift'`. `setVars` builds everything again (about 20 ms, plus the sound only if it changed): for a continuous input call it as often as you like, calls that overlap are joined, but do not use it for something that should move every frame (that is a keyframe).
135
+ 105. **Layout that follows the screen is written in `W` / `H` / `GW` / `GH`, never in pixels.** After `movie.resize(w, h)` an expression sees the new size; a literal `x: 960` stays at 960. A string variable cannot be read in an expression (`x: 'title'` is a number context): use `{title}` in a string, or declare the number. A name that is declared but never read, and a `{name}` that was not declared, are both said at `init` (usually a typo). Load a web font BEFORE the first `setVars` that changes a text (see 103): the text is measured again each rebuild.
136
+ 106. **A text outline used to spike; it is round-joined now.** `style: { stroke: { color: '#000', width: 12 } }` was drawn with PixiJS's default `miter` join, so the sharp corners of W, V, A, k and 4 grew spikes ("the outline sticks out"). The library now adds `join: 'round'` to an outline that names no join; say `join: 'miter'` or `'bevel'` if you want one. The stroke is centred on the glyph edge, so half of it eats into the letter: keep `width` to about a tenth of `fontSize`, or for a thick outline put a second copy of the text with the stroke UNDER the plain one.
137
+