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.
- package/CHANGELOG.md +25 -0
- package/README.md +6 -5
- package/ai/chat-template.html +3 -3
- package/ai/tools/check.mjs +42 -2
- package/ai/tools/lookup.mjs +12 -6
- package/ai/tools/render.mjs +15 -2
- package/ai/tools/varArgs.mjs +75 -0
- package/dist/{Base-CB1_FPZD.d.cts → Base-BKagtWc0.d.cts} +1 -1
- package/dist/{Base-Ne74ztNl.d.ts → Base-jRiMHcWT.d.ts} +1 -1
- package/dist/Composition-DQCPJPFE.js +7 -0
- package/dist/{Composition-RJGA7KDU.js.map → Composition-DQCPJPFE.js.map} +1 -1
- package/dist/Composition-V2XYSW6P.cjs +16 -0
- package/dist/{Composition-MUKR3FYD.cjs.map → Composition-V2XYSW6P.cjs.map} +1 -1
- package/dist/Controller.cjs +42 -1
- package/dist/Controller.cjs.map +1 -1
- package/dist/Controller.d.cts +10 -2
- package/dist/Controller.d.ts +10 -2
- package/dist/Controller.js +42 -1
- package/dist/Controller.js.map +1 -1
- package/dist/{Movie-DdnpLpw1.d.cts → Movie-BH81stkb.d.cts} +90 -3
- package/dist/{Movie-C2rZFkrO.d.ts → Movie-CfFPItoL.d.ts} +90 -3
- package/dist/{chunk-A3Q3SDSH.js → chunk-BGMCZA36.js} +3 -3
- package/dist/{chunk-A3Q3SDSH.js.map → chunk-BGMCZA36.js.map} +1 -1
- package/dist/{chunk-ZVUO325O.cjs → chunk-DJ5B7IKT.cjs} +9 -3
- package/dist/chunk-DJ5B7IKT.cjs.map +1 -0
- package/dist/{chunk-WHNADXXG.cjs → chunk-L73KRFXI.cjs} +61 -61
- package/dist/{chunk-WHNADXXG.cjs.map → chunk-L73KRFXI.cjs.map} +1 -1
- package/dist/{chunk-ZAXYPXKW.js → chunk-MMTESMJ5.js} +9 -4
- package/dist/chunk-MMTESMJ5.js.map +1 -0
- package/dist/{chunk-CRQFDY7E.js → chunk-UTIBYMIO.js} +461 -56
- package/dist/chunk-UTIBYMIO.js.map +1 -0
- package/dist/{chunk-HREBQAY4.cjs → chunk-X3WHETQ3.cjs} +485 -80
- package/dist/chunk-X3WHETQ3.cjs.map +1 -0
- package/dist/index.cjs +31 -31
- package/dist/index.d.cts +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +3 -3
- package/dist/loader.css +1 -1
- package/dist/present.cjs +3 -3
- package/dist/present.d.cts +2 -2
- package/dist/present.d.ts +2 -2
- package/dist/present.js +3 -3
- package/dist/three.cjs +5 -5
- package/dist/three.d.cts +2 -2
- package/dist/three.d.ts +2 -2
- package/dist/three.js +1 -1
- package/dist/{types-BzIB65Vk.d.cts → types-CK_crNAI.d.cts} +2 -0
- package/dist/{types-BzIB65Vk.d.ts → types-CK_crNAI.d.ts} +2 -0
- package/docs/api.md +28 -1
- package/docs/dsl.md +32 -1
- package/llms-full.txt +145 -11
- package/package.json +83 -20
- package/skills/pixi-effects/SKILL.md +1 -1
- package/skills/pixi-effects/reference/cheatsheet.md +3 -0
- package/skills/pixi-effects/reference/pitfalls.md +4 -0
- package/skills/pixi-effects/reference/recipes.md +79 -8
- package/skills/pixi-effects/template.html +6 -6
- package/dist/Composition-MUKR3FYD.cjs +0 -16
- package/dist/Composition-RJGA7KDU.js +0 -7
- package/dist/chunk-CRQFDY7E.js.map +0 -1
- package/dist/chunk-HREBQAY4.cjs.map +0 -1
- package/dist/chunk-ZAXYPXKW.js.map +0 -1
- 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.
|
|
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 *
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
| `'
|
|
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.
|
|
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": {
|
|
9
|
-
|
|
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": {
|
|
13
|
-
|
|
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": {
|
|
18
|
-
|
|
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": {
|
|
22
|
-
|
|
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": {
|
|
29
|
-
|
|
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",
|
|
32
|
-
"
|
|
33
|
-
"
|
|
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": {
|
|
37
|
-
|
|
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": {
|
|
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": {
|
|
71
|
-
|
|
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": {
|
|
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.
|
|
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
|
+
|