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.
- package/CHANGELOG.md +28 -0
- package/README.md +11 -8
- package/ai/SKILL.md +2 -1
- package/ai/reference/cheatsheet.md +12 -1
- package/ai/reference/pitfalls.md +4 -0
- package/ai/reference/recipes.md +57 -0
- package/ai/template.html +8 -4
- package/ai/tools/check.mjs +17 -1
- package/ai/tools/render.mjs +13 -9
- package/dist/{Base-CwUxTfja.d.cts → Base-C6ZnJ9pD.d.cts} +1 -1
- package/dist/{Base-CyvSLoCP.d.ts → Base-CQOlB2VH.d.ts} +1 -1
- package/dist/Controller.cjs +132 -15
- package/dist/Controller.cjs.map +1 -1
- package/dist/Controller.d.cts +25 -3
- package/dist/Controller.d.ts +25 -3
- package/dist/Controller.js +132 -15
- package/dist/Controller.js.map +1 -1
- package/dist/{Movie-DSSNOF3T.d.cts → Movie-DnR4H1OO.d.ts} +93 -2
- package/dist/{Movie-nzmWsxWX.d.ts → Movie-Tl5dRLJl.d.cts} +93 -2
- package/dist/Presenter.cjs +671 -0
- package/dist/Presenter.cjs.map +1 -0
- package/dist/Presenter.d.cts +123 -0
- package/dist/Presenter.d.ts +123 -0
- package/dist/Presenter.js +669 -0
- package/dist/Presenter.js.map +1 -0
- package/dist/index.cjs +665 -36
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +165 -5
- package/dist/index.d.ts +165 -5
- package/dist/index.js +659 -37
- package/dist/index.js.map +1 -1
- package/dist/loader.css +1 -1
- package/dist/three.d.cts +2 -2
- package/dist/three.d.ts +2 -2
- package/dist/{types-BXu28nJj.d.cts → types-CBSiUKau.d.cts} +56 -1
- package/dist/{types-BXu28nJj.d.ts → types-CBSiUKau.d.ts} +56 -1
- package/docs/api.md +80 -0
- package/docs/dsl.md +48 -0
- package/llms-full.txt +203 -2
- package/llms.txt +3 -3
- 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.
|
|
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 {
|
|
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-
|
|
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 {
|
|
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-
|
|
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
|
|
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
|
|
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.
|