pixi-effects 0.11.0 → 0.13.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 (41) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +11 -8
  3. package/ai/SKILL.md +2 -1
  4. package/ai/reference/cheatsheet.md +12 -1
  5. package/ai/reference/pitfalls.md +4 -0
  6. package/ai/reference/recipes.md +57 -0
  7. package/ai/template.html +8 -4
  8. package/ai/tools/check.mjs +17 -1
  9. package/ai/tools/render.mjs +13 -9
  10. package/dist/{Base-CwUxTfja.d.cts → Base-C6ZnJ9pD.d.cts} +1 -1
  11. package/dist/{Base-CyvSLoCP.d.ts → Base-CQOlB2VH.d.ts} +1 -1
  12. package/dist/Controller.cjs +132 -15
  13. package/dist/Controller.cjs.map +1 -1
  14. package/dist/Controller.d.cts +25 -3
  15. package/dist/Controller.d.ts +25 -3
  16. package/dist/Controller.js +132 -15
  17. package/dist/Controller.js.map +1 -1
  18. package/dist/{Movie-DSSNOF3T.d.cts → Movie-DnR4H1OO.d.ts} +93 -2
  19. package/dist/{Movie-nzmWsxWX.d.ts → Movie-Tl5dRLJl.d.cts} +93 -2
  20. package/dist/Presenter.cjs +671 -0
  21. package/dist/Presenter.cjs.map +1 -0
  22. package/dist/Presenter.d.cts +123 -0
  23. package/dist/Presenter.d.ts +123 -0
  24. package/dist/Presenter.js +669 -0
  25. package/dist/Presenter.js.map +1 -0
  26. package/dist/index.cjs +665 -36
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +165 -5
  29. package/dist/index.d.ts +165 -5
  30. package/dist/index.js +659 -37
  31. package/dist/index.js.map +1 -1
  32. package/dist/loader.css +1 -1
  33. package/dist/three.d.cts +2 -2
  34. package/dist/three.d.ts +2 -2
  35. package/dist/{types-BXu28nJj.d.cts → types-CBSiUKau.d.cts} +56 -1
  36. package/dist/{types-BXu28nJj.d.ts → types-CBSiUKau.d.ts} +56 -1
  37. package/docs/api.md +80 -0
  38. package/docs/dsl.md +48 -0
  39. package/llms-full.txt +203 -2
  40. package/llms.txt +3 -3
  41. package/package.json +5 -1
package/dist/loader.css CHANGED
@@ -1,7 +1,7 @@
1
1
  /*
2
2
  * pixi-effects loader: one line of HTML on the page, a few lines of CSS, no JavaScript of your own.
3
3
  *
4
- * <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.11.0/dist/loader.css">
4
+ * <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.13.0/dist/loader.css">
5
5
  * <div class="stage" style="position: relative"> <!-- any box the canvas sits in, with position: relative -->
6
6
  * <canvas id="stage" width="1280" height="720"></canvas>
7
7
  * <div class="pe-loader" data-label="LOADING"></div> <!-- or class="pe-loader pe-loader--bar" -->
package/dist/three.d.cts CHANGED
@@ -1,6 +1,6 @@
1
- import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-BXu28nJj.cjs';
1
+ import { d as SequenceCommon, s as PropValue, S as SequenceSpec } from './types-CBSiUKau.cjs';
2
2
  import { Scene, Camera, WebGLRenderer } from 'three';
3
- import { S as Sequence, P as PathRouters } from './Base-CwUxTfja.cjs';
3
+ import { S as Sequence, P as PathRouters } from './Base-C6ZnJ9pD.cjs';
4
4
  import 'pixi.js';
5
5
  import 'gsap';
6
6
 
package/dist/three.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { b as SequenceCommon, q as PropValue, S as SequenceSpec } from './types-BXu28nJj.js';
1
+ import { d as SequenceCommon, s as PropValue, S as SequenceSpec } from './types-CBSiUKau.js';
2
2
  import { Scene, Camera, WebGLRenderer } from 'three';
3
- import { S as Sequence, P as PathRouters } from './Base-CyvSLoCP.js';
3
+ import { S as Sequence, P as PathRouters } from './Base-CQOlB2VH.js';
4
4
  import 'pixi.js';
5
5
  import 'gsap';
6
6
 
@@ -1,3 +1,52 @@
1
+ /** What an author writes in `composition.stops`: a time in seconds, or an object. */
2
+ interface StopSpec {
3
+ /** Where playback stops, in seconds (negative counts back from the end). */
4
+ at: number;
5
+ /** This stop is the settled state of a new page. A name (shown in the page list), or `true` for an unnamed page. Without it the stop is a step of the page before. */
6
+ page?: string | true;
7
+ /** Speaker notes for this stop. */
8
+ notes?: string;
9
+ /** Move on by itself after this many seconds (a kiosk, a looping demo). */
10
+ advance?: number;
11
+ /**
12
+ * Which picture stands for a page in a PDF (and in the page overview). `true`: this stop's picture IS the page's picture (use it when the
13
+ * last stop is mid-exit or a step you do not want on paper). `false`: never use this stop's picture for the PDF. Default: the page's last stop.
14
+ */
15
+ pdf?: boolean;
16
+ }
17
+ /** A stop, normalised: its frame, and which page it belongs to. */
18
+ interface Stop {
19
+ index: number;
20
+ at: number;
21
+ frame: number;
22
+ /** The name of the page this stop belongs to (null if it has none). */
23
+ page: string | null;
24
+ /** Which page (0-based) this stop belongs to. */
25
+ pageIndex: number;
26
+ /** True for the stop that begins its page. */
27
+ pageStart: boolean;
28
+ notes?: string;
29
+ advance?: number;
30
+ pdf?: boolean;
31
+ }
32
+ /**
33
+ * The stops of a composition, checked and in order. Numbers are stops; with no `page` anywhere every stop is a page of its
34
+ * own, otherwise only the stops that say `page` start one (the first stop always does). Negative times count back from the end;
35
+ * two stops on the same frame are one; anything outside the movie or not a number is dropped, with a warning that names it.
36
+ */
37
+ declare function normalizeStops(raw: ReadonlyArray<number | StopSpec> | undefined, duration: number, frameRate: number): Stop[];
38
+ /**
39
+ * The stops whose pictures stand for the pages (`which: 'pages'`, default) or for every stop. A page's picture is, in order: the stop flagged
40
+ * `pdf: true` (the last such one, or the first with `pick: 'first'`), else the last (or first) stop not flagged `pdf: false`, else, for a page
41
+ * list, its last (or first) stop, and for a PDF (`pdf: true` here) nothing: the page is left out. With `which: 'stops'` a PDF leaves out the
42
+ * stops flagged `pdf: false`.
43
+ */
44
+ declare function pictureStops(stops: readonly Stop[], opts?: {
45
+ which?: 'pages' | 'stops';
46
+ pick?: 'last' | 'first';
47
+ pdf?: boolean;
48
+ }): Stop[];
49
+
1
50
  /**
2
51
  * pixi-effects public DSL types.
3
52
  *
@@ -483,6 +532,12 @@ interface CompositionSpec extends SequenceCommon {
483
532
  height?: number;
484
533
  sequences?: SequenceSpec[];
485
534
  transitions?: TransitionSpec[];
535
+ /**
536
+ * Where a presentation pauses: seconds, or `{ at, page?, notes?, advance? }` (see `StopSpec`). A stop with `page` begins a page, the others
537
+ * are steps of it; with no `page` anywhere each stop is a page. Nothing changes for an ordinary player: `Presenter` (and `movie.next()`)
538
+ * stop at them, `Controller` shows them as marks on the seek bar.
539
+ */
540
+ stops?: Array<number | StopSpec>;
486
541
  }
487
542
  /** Resolved parent / root composition shape used for scope and sizing. */
488
543
  interface CompositionShape {
@@ -513,4 +568,4 @@ interface AudioDescriptor {
513
568
  }[];
514
569
  }
515
570
 
516
- export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, NullSequenceSpec as N, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };
571
+ export { type ArcShapeSpec as A, type StopSpec as B, type CompositionShape as C, type DipTransition as D, type EllipseShapeSpec as E, type FilterSpec as F, type GradientSpec as G, type TransitionCommon as H, type ImageSequenceSpec as I, normalizeStops as J, type Keyframe as K, type LineShapeSpec as L, pictureStops as M, type NullSequenceSpec as N, type AudioDescriptor as O, type Props as P, type RectShapeSpec as R, type SequenceSpec as S, type TextSequenceSpec as T, type VideoSequenceSpec as V, type WipeTransition as W, type ZoomTransition as Z, type CameraSequenceSpec as a, type TransitionSpec as b, type CompositionSpec as c, type SequenceCommon as d, type AssetSpec as e, type AudioAssetSpec as f, type AudioSequenceSpec as g, type AudioSfxSpec as h, type ChromaKeyFilterSpec as i, type CircleShapeSpec as j, type CompositionSequenceSpec as k, type CrossfadeTransition as l, type CustomFilterSpec as m, type DissolveTransition as n, type Expr as o, type IrisTransition as p, type PathShapeSpec as q, type PolygonShapeSpec as r, type PropValue as s, type SfxKnobs as t, type SfxOptions as u, type SfxPreset as v, type SfxVoice as w, type ShapeSequenceSpec as x, type SlideTransition as y, type Stop as z };
@@ -1,3 +1,52 @@
1
+ /** What an author writes in `composition.stops`: a time in seconds, or an object. */
2
+ interface StopSpec {
3
+ /** Where playback stops, in seconds (negative counts back from the end). */
4
+ at: number;
5
+ /** This stop is the settled state of a new page. A name (shown in the page list), or `true` for an unnamed page. Without it the stop is a step of the page before. */
6
+ page?: string | true;
7
+ /** Speaker notes for this stop. */
8
+ notes?: string;
9
+ /** Move on by itself after this many seconds (a kiosk, a looping demo). */
10
+ advance?: number;
11
+ /**
12
+ * Which picture stands for a page in a PDF (and in the page overview). `true`: this stop's picture IS the page's picture (use it when the
13
+ * last stop is mid-exit or a step you do not want on paper). `false`: never use this stop's picture for the PDF. Default: the page's last stop.
14
+ */
15
+ pdf?: boolean;
16
+ }
17
+ /** A stop, normalised: its frame, and which page it belongs to. */
18
+ interface Stop {
19
+ index: number;
20
+ at: number;
21
+ frame: number;
22
+ /** The name of the page this stop belongs to (null if it has none). */
23
+ page: string | null;
24
+ /** Which page (0-based) this stop belongs to. */
25
+ pageIndex: number;
26
+ /** True for the stop that begins its page. */
27
+ pageStart: boolean;
28
+ notes?: string;
29
+ advance?: number;
30
+ pdf?: boolean;
31
+ }
32
+ /**
33
+ * The stops of a composition, checked and in order. Numbers are stops; with no `page` anywhere every stop is a page of its
34
+ * own, otherwise only the stops that say `page` start one (the first stop always does). Negative times count back from the end;
35
+ * two stops on the same frame are one; anything outside the movie or not a number is dropped, with a warning that names it.
36
+ */
37
+ declare function normalizeStops(raw: ReadonlyArray<number | StopSpec> | undefined, duration: number, frameRate: number): Stop[];
38
+ /**
39
+ * The stops whose pictures stand for the pages (`which: 'pages'`, default) or for every stop. A page's picture is, in order: the stop flagged
40
+ * `pdf: true` (the last such one, or the first with `pick: 'first'`), else the last (or first) stop not flagged `pdf: false`, else, for a page
41
+ * list, its last (or first) stop, and for a PDF (`pdf: true` here) nothing: the page is left out. With `which: 'stops'` a PDF leaves out the
42
+ * stops flagged `pdf: false`.
43
+ */
44
+ declare function pictureStops(stops: readonly Stop[], opts?: {
45
+ which?: 'pages' | 'stops';
46
+ pick?: 'last' | 'first';
47
+ pdf?: boolean;
48
+ }): Stop[];
49
+
1
50
  /**
2
51
  * pixi-effects public DSL types.
3
52
  *
@@ -483,6 +532,12 @@ interface CompositionSpec extends SequenceCommon {
483
532
  height?: number;
484
533
  sequences?: SequenceSpec[];
485
534
  transitions?: TransitionSpec[];
535
+ /**
536
+ * Where a presentation pauses: seconds, or `{ at, page?, notes?, advance? }` (see `StopSpec`). A stop with `page` begins a page, the others
537
+ * are steps of it; with no `page` anywhere each stop is a page. Nothing changes for an ordinary player: `Presenter` (and `movie.next()`)
538
+ * stop at them, `Controller` shows them as marks on the seek bar.
539
+ */
540
+ stops?: Array<number | StopSpec>;
486
541
  }
487
542
  /** Resolved parent / root composition shape used for scope and sizing. */
488
543
  interface CompositionShape {
@@ -513,4 +568,4 @@ interface AudioDescriptor {
513
568
  }[];
514
569
  }
515
570
 
516
- export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, NullSequenceSpec as N, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };
571
+ export { type ArcShapeSpec as A, type StopSpec as B, type CompositionShape as C, type DipTransition as D, type EllipseShapeSpec as E, type FilterSpec as F, type GradientSpec as G, type TransitionCommon as H, type ImageSequenceSpec as I, normalizeStops as J, type Keyframe as K, type LineShapeSpec as L, pictureStops as M, type NullSequenceSpec as N, type AudioDescriptor as O, type Props as P, type RectShapeSpec as R, type SequenceSpec as S, type TextSequenceSpec as T, type VideoSequenceSpec as V, type WipeTransition as W, type ZoomTransition as Z, type CameraSequenceSpec as a, type TransitionSpec as b, type CompositionSpec as c, type SequenceCommon as d, type AssetSpec as e, type AudioAssetSpec as f, type AudioSequenceSpec as g, type AudioSfxSpec as h, type ChromaKeyFilterSpec as i, type CircleShapeSpec as j, type CompositionSequenceSpec as k, type CrossfadeTransition as l, type CustomFilterSpec as m, type DissolveTransition as n, type Expr as o, type IrisTransition as p, type PathShapeSpec as q, type PolygonShapeSpec as r, type PropValue as s, type SfxKnobs as t, type SfxOptions as u, type SfxPreset as v, type SfxVoice as w, type ShapeSequenceSpec as x, type SlideTransition as y, type Stop as z };
package/docs/api.md CHANGED
@@ -224,6 +224,7 @@ movie.off(event, fn): this
224
224
  | `'pause'` | none | when `pause()` actually transitions from playing |
225
225
  | `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame |
226
226
  | `'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()` |
227
+ | `'stop'` | `{ index: number; stop: Stop; pageIndex: number }` | a presentation is on a stop: `next()` played to it, or `prev()` / `goToStop()` / `goToPage()` jumped to it |
227
228
  | `'ended'` | none | playback ran off the end (after `'pause'`); pausing by hand does not emit it |
228
229
  | `'volumechange'` | `{ volume: number; muted: boolean }` | `volume` or `muted` really changed (clamping counts) |
229
230
  | `'error'` | `{ where: 'init' \| 'render' \| 'playback'; message: string; error: unknown }` | `init()` / `render()` failed (the call still rejects), or a frame failed during playback |
@@ -247,6 +248,83 @@ The names are the ones an HTML5 `<video>` uses, so a player written for `<video>
247
248
  | `muted` | boolean | getter/setter; immediate |
248
249
  | `app` | `pixi.js Application \| null` | PIXI Application instance (advanced/escape hatch) |
249
250
  | `timeline` | GSAP Timeline `\| null` | underlying GSAP timeline (advanced) |
251
+ | `stops` | `Stop[]` | the composition's stops (see Presentations); empty for an ordinary movie |
252
+ | `stopIndex`, `pageIndex`, `pageCount`, `currentStop` | number, number, number, `Stop \| null` | where the playhead is among the stops and pages (`-1` / `null` before the first stop) |
253
+
254
+ ### Presentations: `stops`, `next()`, `prev()`, `Presenter`
255
+
256
+ A composition can say where a presentation pauses: `composition: { stops: [...] }`. A stop is a time in seconds or `{ at, page?, notes?, advance?, pdf? }`; a stop with `page` (a name, or `true`) begins a page, the others are steps of it; with no `page` anywhere each stop is a page; the first stop always begins one. A negative `at` counts back from the end; two stops on one frame are one; a stop outside the movie is ignored with a warning. `movie.play()` ignores the stops and plays to the end; the `Controller`'s play button, Space and a click on the picture play to the next stop and pause there (see `pauseAtStops`). `pdf: true` marks the stop whose picture stands for its page in a PDF (and in the page overview); `pdf: false` keeps a stop's picture out of the PDF (a last stop that is mid-exit, a step you do not want on paper). Without flags a page is pictured by its last stop.
257
+
258
+ ```ts
259
+ movie.stops // Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance?, pdf? }
260
+ await movie.next(); // play to the next stop and pause exactly on its frame; pressed again while playing, skip to that stop at once;
261
+ // after the last stop play to the end. Resolves when it has landed (or stopped for another reason).
262
+ await movie.prev(); // jump back to the previous stop at once (no reverse playback); from the first stop, to the start
263
+ await movie.goToStop(i); // 0-based
264
+ await movie.goToPage(n); // 0-based: the first stop of page n
265
+ movie.stopIndex / movie.pageIndex / movie.pageCount / movie.currentStop
266
+ movie.on('stop', ({ index, stop, pageIndex }) => …)
267
+ ```
268
+
269
+ `deck({ pages, transition? })` builds such a movie from pages (see the DSL reference). **`Presenter`** (`pixi-effects/presenter`) is the player for it:
270
+
271
+ ```ts
272
+ import { Presenter } from 'pixi-effects/presenter';
273
+ const presenter = new Presenter(movie, { canvas }); // instead of Controller; await presenter.start() to go fullscreen and play to the first stop
274
+ ```
275
+
276
+ | Option | Default | Notes |
277
+ | ------ | ------- | ----- |
278
+ | `canvas` | required | |
279
+ | `keyboard` | `true` | **next**: → ↓ Space Enter PageDown · **back**: ← ↑ Backspace PageUp · Home (first page) · End (last stop) · a page number then Enter · **G** the page overview · **P** the presenter view · B or `.` black screen · W or `,` white screen · F fullscreen · `?` / H the list of keys · Esc closes / leaves |
280
+ | `clickToAdvance` | `true` | a click or tap on the picture is next |
281
+ | `swipe` | `true` | a swipe to the left is next, to the right is back |
282
+ | `indicator` | `true` | a page counter (`3 / 8`), the page name and a progress line along the bottom; they fade out when nothing happens, and the pointer hides with them |
283
+ | `autoAdvance` | `true` | a stop with `advance: seconds` moves on by itself |
284
+ | `loop` | `false` | run off the end: go back to the start and play again |
285
+ | `accent` | white | the progress line's colour |
286
+ | `onExit` | none | Escape with nothing left to close, or fullscreen left |
287
+
288
+ **The page overview (`G`)** is a grid of every page with its picture, the current page marked: arrows choose, Enter or a click goes there, `G` or Esc closes. **The presenter view (`P`)** opens a second window for the speaker: the picture that is on screen (live), the picture of the next stop, the notes of the page, a timer (with reset), the page counter and Back / Next buttons; the keys work there too. Both use a picture of every stop that `start()` makes **before** the audience sees anything (behind a "Preparing…" cover; taking them moves the playhead through the stops and back, so it must not happen on screen); `presenter.ensureThumbs()` makes them on demand (an overview opened before that does it on the spot, with a flicker). A browser needs a click or key press to open a popup: `P` is one; if it is blocked a warning says so.
289
+
290
+ `presenter.start()`, `presenter.openPresenterView()`, `presenter.closePresenterView()`, `presenter.next()`, `presenter.prev()`, `presenter.setCover('black' \| 'white' \| 'off')`, `presenter.exit()`, `presenter.destroy()`. It uses the canvas's positioned parent, or wraps the canvas like `Controller` does. A movie with stops shown through a **`Controller`** gets a mark per stop on the seek bar and a Present button (`present: false` leaves the marks only) that hands the page to a `Presenter` (fullscreen, keys, click and swipe move through the stops; Esc gives the bar back).
291
+
292
+ ### Pictures of the stops and the deck as a PDF: `movie.stopImages()`, `movie.exportPDF()`
293
+
294
+ ```ts
295
+ const pages = await movie.stopImages({ as: 'dataURL', type: 'image/jpeg', scale: 0.25 }); // one picture per PAGE: its last stop, fully built
296
+ // [{ stop, page, image }, …]; { which: 'stops' } is one per stop, { pick: 'first' } the first stop of each page; onImage(img) is called as each one is ready
297
+ const pdf = await movie.exportPDF({ title: 'My talk' }); // a Blob: one PDF page per page of the deck (JPEG at the canvas size)
298
+ ```
299
+
300
+ Both pause the movie and leave the playhead where it was; a movie with no stops returns an empty list / throws (a PDF needs pages). The picture of a page is, in order: its last stop flagged `pdf: true`, else its last (with `pick: 'first'`, first) stop that is not `pdf: false`; a page whose stops are all `pdf: false` is left out of a PDF (a page list still shows it by its last stop); `which: 'stops'` makes a page of every stop that is not `pdf: false`. `exportPDF` options: `which`, `pick`, `scale`, `quality` (JPEG, default 0.92), `title`, `motionBlur`, `onImage`. A transparent background comes out black in a JPEG: give the movie a `background`. From a script, `npx pixi-effects-render my-talk.html -o my-talk.pdf` (add `--all-stops` for a page per stop).
301
+
302
+ ### Audio-reactive: `audioEnvelope()`, `react()`, `bpmEnvelope()`
303
+
304
+ Make things follow the sound, deterministically (playback, seeking and export agree): analyse the sound **before** `movie.init`, then bake what it does into keyframes.
305
+
306
+ ```ts
307
+ import { audioEnvelope, bpmEnvelope, react } from 'pixi-effects';
308
+
309
+ const env = await audioEnvelope('music.mp3', { frameRate: 30 }); // a URL, Blob / File, ArrayBuffer or AudioBuffer
310
+ // env.series.level / bass / mid / treble: one value per frame, 0–1 on a log (perceptual) scale, measured against the loudest of them
311
+ // env.beats: times of the beats (seconds); env.bpm: the tempo (null with too few beats); env.at(time, 'bass')
312
+ await movie.init({ /* … */ composition: { sequences: [
313
+ { type: 'shape', shape: 'circle', radius: 120, initial: { x: 640, y: 360 },
314
+ keyframes: react(env, { duration: 12, props: { scale: { base: 1, amount: 0.4, band: 'bass', attack: 0.02, release: 0.2 } } }) },
315
+ { type: 'audio', asset: 'music', loop: true },
316
+ ] } });
317
+ ```
318
+
319
+ | `audioEnvelope(source, options)` | |
320
+ | --- | --- |
321
+ | `frameRate` | one value per video frame: use the movie's (default 30) |
322
+ | `bands` | `{ name: [fromHz, toHz] }`. Default `{ bass: [20, 150], mid: [150, 2000], treble: [2000, 10000] }`; give your own for a spectrum (24 log-spaced bands) and the beat detector looks in `bass` (set `beatBand` if you have no such band) |
323
+ | `beatSensitivity` | above 1 finds more beats, below 1 fewer |
324
+
325
+ `react(env, options)` returns keyframes (one linear step per frame): `{ at?, duration, props, audioOffset?, loop?, frameRate? }`. Each prop is `{ base, amount, band?, beats?, decay?, attack?, release?, invert?, curve? }`: the value is `base + amount × level`. `band` picks a series (default `level`); `beats: true` follows the beats instead (a jump to full on each, falling off with `decay` seconds); `attack` / `release` smooth the rise and fall in seconds like a level meter (a quick rise and a slow fall bounces); `curve` above 1 lets only the loud parts move it. `audioOffset` is where in the sound the layer's start is (a layer that begins 2 s after the music: `audioOffset: 2`); `loop: true` for a looping music layer. It refuses to bake more than 4000 steps (lower `frameRate`).
326
+
327
+ `bpmEnvelope(120, { duration, frameRate })` is a stand-in with no audio file: a kick on every beat (`bass`), a snare on 2 and 4 (`mid`), hats on the eighths (`treble`), exactly on the tempo. Use it to try an idea, or to make visuals that match sound effects you place on the same tempo. The analysis is the same code the check tool trusts: pure and deterministic.
250
328
 
251
329
  ### `movie.toggleMute(): boolean`
252
330
 
@@ -302,6 +380,8 @@ interface ControllerOptions {
302
380
  canvas: HTMLCanvasElement; // required
303
381
  showExportButton?: boolean; // default true; hides ⬇ + popover
304
382
  enableKeyboardShortcuts?: boolean; // default true
383
+ present?: boolean; // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
384
+ pauseAtStops?: boolean; // default true: with stops, play / Space / click on the picture play to the next stop and pause; false plays straight through
305
385
  clickToPlay?: boolean; // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
306
386
  className?: string; // default 'movie-controller'
307
387
  theme?: ControllerTheme; // colours / thickness / font of the bar, see Theme
package/docs/dsl.md CHANGED
@@ -824,6 +824,10 @@ initial: { x: 'GW/2', y: 'GH * 0.96', anchorX: 0.5, anchorY: 1 }
824
824
 
825
825
  ---
826
826
 
827
+ ## Stops (presentations)
828
+
829
+ `composition.stops` says where a presentation pauses: seconds, or `{ at, page?, notes?, advance?, pdf? }` (see [Presentations in the API reference](api.md#presentations-stops-next-prev-presenter)). A stop with `page` begins a page (a name, or `true`), the others are steps of it; with no `page` anywhere each stop is a page. `movie.play()` ignores them; the `Controller` shows marks on the seek bar and its play button plays to the next stop (`pauseAtStops: false` plays through), and `movie.next()` and `Presenter` pause on them. **`pdf: true` / `pdf: false`** on a stop chooses which moment stands for a page in a PDF: `true` = this stop is the page's picture, `false` = never use it (default: the page's last stop). Use it when the last stop is mid-exit. [`deck()`](#deck) builds the whole thing from pages.
830
+
827
831
  ## Transitions
828
832
 
829
833
  A composition can declare scene-to-scene `transitions` that compress paired keyframes into a single line and add visual effects (mask wipes, iris reveals) that aren't expressible at the keyframe level.
@@ -1238,6 +1242,50 @@ import { followPath } from 'pixi-effects';
1238
1242
 
1239
1243
  It returns `Keyframe[]`: spread it next to other keyframes, but not another `x`, `y` or `rotation` during the trip.
1240
1244
 
1245
+ ### `react`
1246
+
1247
+ Keyframes that follow a sound: `base + amount × level`, sampled once per frame from an envelope. Analyse the sound first (`await audioEnvelope(url)`, or `bpmEnvelope(bpm, { duration })` with no file), then:
1248
+
1249
+ ```ts
1250
+ import { audioEnvelope, react } from 'pixi-effects';
1251
+
1252
+ const env = await audioEnvelope('music.mp3', { frameRate: 30 });
1253
+ { type: 'shape', shape: 'circle', radius: 120, initial: { x: 640, y: 360 },
1254
+ keyframes: react(env, { duration: 12, props: {
1255
+ scale: { base: 1, amount: 0.4, band: 'bass', attack: 0.02, release: 0.2 }, // swells with the low end, falls back slowly
1256
+ alpha: { base: 0.5, amount: 0.5, beats: true, decay: 0.15 }, // flashes on every beat
1257
+ } }) }
1258
+ ```
1259
+
1260
+ See [the API reference](api.md#audio-reactive-audioenvelope-react-bpmenvelope) for the options. A bar equaliser is one layer per band with `height: { base: 6, amount: 220, band: 'b7' }`.
1261
+
1262
+ ### `deck`
1263
+
1264
+ A deck of pages as one movie, for a `Presenter`. Each page is a nested composition laid out after the one before (so its layers are written in the page's own time), the stops come from the pages, and an optional `transition` joins them with the existing transitions.
1265
+
1266
+ ```ts
1267
+ import { deck } from 'pixi-effects';
1268
+
1269
+ await movie.init({ canvas, width: 1280, height: 720, frameRate: 30, ...deck({
1270
+ transition: { kind: 'slide', direction: 'left', duration: 0.6, ease: 'power3.inOut' },
1271
+ pages: [
1272
+ { name: 'Hello', duration: 3.2, stops: [2.6], sequences: [ /* the title, at: 0 = the start of the page */ ] },
1273
+ { name: 'Why', duration: 5.2, stops: [1.5, 3.0, 4.6], sequences: [ /* three bullets, each starting at the previous stop */ ] },
1274
+ ],
1275
+ }) });
1276
+ ```
1277
+
1278
+ | Option | Notes |
1279
+ | ------ | ----- |
1280
+ | `pages[]` | required: `{ name?, duration, sequences, stops?, notes?, advance?, initial?, keyframes?, filters?, … }` |
1281
+ | `page.duration` | seconds; **a page should last its last stop plus the transition** (after the last stop the next press plays the rest of the page and the slide) |
1282
+ | `page.stops` | page-local times, or `{ at, pdf? }`: the first is the page settled, the others are steps (a bullet, a growing chart: **a step is a layer that starts at the previous stop and ends at this one**). Default: where the transition begins (the end for the last page) |
1283
+ | `page.notes`, `page.advance` | notes stay on the page's first stop; `advance` (seconds) on its last |
1284
+ | `transition` | `{ kind, duration, … }`: any [transition](#transitions) without `from` / `to` / `at`; the next page starts `duration` seconds early and the transition plays across the overlap. It must be shorter than every page |
1285
+ | movie options | `width`, `height`, `frameRate`, `background`, `canvas`, `assets`, `poster`, `motionBlur`, `loader` pass through |
1286
+
1287
+ It returns `{ duration, composition: { sequences, transitions?, stops }, …your movie options }`, ready to spread into `movie.init`. The page layers are named `page-1`, `page-2`, …
1288
+
1241
1289
  ### `stagger`
1242
1290
 
1243
1291
  Delays for a wave of items, in the style of GSAP's `stagger`. Pure and seeded, so playback and export agree.