pixi-effects 0.12.0 → 0.13.0

package/dist/loader.css

@@ -1,7 +1,7 @@
 /*
  * pixi-effects loader: one line of HTML on the page, a few lines of CSS, no JavaScript of your own.
  *
- *   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.12.0/dist/loader.css">
+ *   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.13.0/dist/loader.css">
  *   <div class="stage" style="position: relative">                      <!-- any box the canvas sits in, with position: relative -->
  *     <canvas id="stage" width="1280" height="720"></canvas>
  *     <div class="pe-loader" data-label="LOADING"></div>                <!-- or class="pe-loader pe-loader--bar" -->

package/dist/three.d.cts

@@ -1,6 +1,6 @@
-import { d as SequenceCommon, s as PropValue, S as SequenceSpec } from './types-mpqQO8MJ.cjs';
+import { d as SequenceCommon, s as PropValue, S as SequenceSpec } from './types-CBSiUKau.cjs';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-W3sQzGPO.cjs';
+import { S as Sequence, P as PathRouters } from './Base-C6ZnJ9pD.cjs';
 import 'pixi.js';
 import 'gsap';
 

package/dist/three.d.ts

@@ -1,6 +1,6 @@
-import { d as SequenceCommon, s as PropValue, S as SequenceSpec } from './types-mpqQO8MJ.js';
+import { d as SequenceCommon, s as PropValue, S as SequenceSpec } from './types-CBSiUKau.js';
 import { Scene, Camera, WebGLRenderer } from 'three';
-import { S as Sequence, P as PathRouters } from './Base-CYH9vPCH.js';
+import { S as Sequence, P as PathRouters } from './Base-CQOlB2VH.js';
 import 'pixi.js';
 import 'gsap';
 

package/dist/{types-mpqQO8MJ.d.cts → types-CBSiUKau.d.cts}

@@ -8,6 +8,11 @@ interface StopSpec {
     notes?: string;
     /** Move on by itself after this many seconds (a kiosk, a looping demo). */
     advance?: number;
+    /**
+     * 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
+     * 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.
+     */
+    pdf?: boolean;
 }
 /** A stop, normalised: its frame, and which page it belongs to. */
 interface Stop {
@@ -22,6 +27,7 @@ interface Stop {
     pageStart: boolean;
     notes?: string;
     advance?: number;
+    pdf?: boolean;
 }
 /**
  * The stops of a composition, checked and in order. Numbers are stops; with no `page` anywhere every stop is a page of its
@@ -29,6 +35,17 @@ interface Stop {
  * two stops on the same frame are one; anything outside the movie or not a number is dropped, with a warning that names it.
  */
 declare function normalizeStops(raw: ReadonlyArray<number | StopSpec> | undefined, duration: number, frameRate: number): Stop[];
+/**
+ * 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
+ * `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
+ * 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
+ * stops flagged `pdf: false`.
+ */
+declare function pictureStops(stops: readonly Stop[], opts?: {
+    which?: 'pages' | 'stops';
+    pick?: 'last' | 'first';
+    pdf?: boolean;
+}): Stop[];
 
 /**
  * pixi-effects public DSL types.
@@ -551,4 +568,4 @@ interface AudioDescriptor {
     }[];
 }
 
-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, type AudioDescriptor as M, type NullSequenceSpec as N, 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 };
+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/dist/{types-mpqQO8MJ.d.ts → types-CBSiUKau.d.ts}

@@ -8,6 +8,11 @@ interface StopSpec {
     notes?: string;
     /** Move on by itself after this many seconds (a kiosk, a looping demo). */
     advance?: number;
+    /**
+     * 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
+     * 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.
+     */
+    pdf?: boolean;
 }
 /** A stop, normalised: its frame, and which page it belongs to. */
 interface Stop {
@@ -22,6 +27,7 @@ interface Stop {
     pageStart: boolean;
     notes?: string;
     advance?: number;
+    pdf?: boolean;
 }
 /**
  * The stops of a composition, checked and in order. Numbers are stops; with no `page` anywhere every stop is a page of its
@@ -29,6 +35,17 @@ interface Stop {
  * two stops on the same frame are one; anything outside the movie or not a number is dropped, with a warning that names it.
  */
 declare function normalizeStops(raw: ReadonlyArray<number | StopSpec> | undefined, duration: number, frameRate: number): Stop[];
+/**
+ * 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
+ * `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
+ * 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
+ * stops flagged `pdf: false`.
+ */
+declare function pictureStops(stops: readonly Stop[], opts?: {
+    which?: 'pages' | 'stops';
+    pick?: 'last' | 'first';
+    pdf?: boolean;
+}): Stop[];
 
 /**
  * pixi-effects public DSL types.
@@ -551,4 +568,4 @@ interface AudioDescriptor {
     }[];
 }
 
-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, type AudioDescriptor as M, type NullSequenceSpec as N, 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 };
+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

@@ -253,10 +253,10 @@ The names are the ones an HTML5 `<video>` uses, so a player written for `<video>
 
 ### Presentations: `stops`, `next()`, `prev()`, `Presenter`
 
-A composition can say where a presentation pauses: `composition: { stops: [...] }`. A stop is a time in seconds or `{ at, page?, notes?, advance? }`; 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. Nothing changes for an ordinary player: playing a movie with stops just plays it.
+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.
 
 ```ts
-movie.stops                    // Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance? }
+movie.stops                    // Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance?, pdf? }
 await movie.next();            // play to the next stop and pause exactly on its frame; pressed again while playing, skip to that stop at once;
                                // after the last stop play to the end. Resolves when it has landed (or stopped for another reason).
 await movie.prev();            // jump back to the previous stop at once (no reverse playback); from the first stop, to the start
@@ -297,7 +297,7 @@ const pages = await movie.stopImages({ as: 'dataURL', type: 'image/jpeg', scale:
 const pdf = await movie.exportPDF({ title: 'My talk' });                                    // a Blob: one PDF page per page of the deck (JPEG at the canvas size)
 ```
 
-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). `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).
+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).
 
 ### Audio-reactive: `audioEnvelope()`, `react()`, `bpmEnvelope()`
 
@@ -381,6 +381,7 @@ interface ControllerOptions {
   showExportButton?: boolean;         // default true; hides ⬇ + popover
   enableKeyboardShortcuts?: boolean;  // default true
   present?: boolean;                  // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
+  pauseAtStops?: boolean;             // default true: with stops, play / Space / click on the picture play to the next stop and pause; false plays straight through
   clickToPlay?: boolean;              // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
   className?: string;                 // default 'movie-controller'
   theme?: ControllerTheme;            // colours / thickness / font of the bar, see Theme

package/docs/dsl.md

@@ -826,7 +826,7 @@ initial: { x: 'GW/2', y: 'GH * 0.96', anchorX: 0.5, anchorY: 1 }
 
 ## Stops (presentations)
 
-`composition.stops` says where a presentation pauses: seconds, or `{ at, page?, notes?, advance? }` (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. A plain player ignores them (`Controller` shows marks on the seek bar); `movie.next()` and `Presenter` pause on them. [`deck()`](#deck) builds the whole thing from pages.
+`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.
 
 ## Transitions
 
@@ -1279,7 +1279,7 @@ await movie.init({ canvas, width: 1280, height: 720, frameRate: 30, ...deck({
 | ------ | ----- |
 | `pages[]` | required: `{ name?, duration, sequences, stops?, notes?, advance?, initial?, keyframes?, filters?, … }` |
 | `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) |
-| `page.stops` | page-local times: 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) |
+| `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) |
 | `page.notes`, `page.advance` | notes stay on the page's first stop; `advance` (seconds) on its last |
 | `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 |
 | movie options | `width`, `height`, `frameRate`, `background`, `canvas`, `assets`, `poster`, `motionBlur`, `loader` pass through |

package/llms-full.txt

@@ -182,13 +182,13 @@ keyframes: followPath({ d: 'M 120 560 C 360 120 920 120 1160 560', duration: 4,
 ...particles({ count: 90, at: 2, emit: 0 /* 0 = burst; or seconds to spread births */, life: [1, 1.8], area: { x: 640, y: 330 /*, width, height */ }, angle: [0, 360] /* 0 right, 90 down, −90 up */,
                speed: [120, 420], gravity: 240, wind: 0, drag: 1.2, sway: { amp: 30, freq: 0.6 }, size: [2, 4.5], scale: [1, 0], fade: { in: 0.2, out: 0.6 },
                colors: ['#ffd166', '#ff6b9d'], shape: 'circle'|'rect'|'star', spin: [-200, 200], blendMode: 'add', seed: 1, name: 'burst', template: { type: 'image', asset } })   // seeded layers, paths baked into keyframes
-// a presentation: stops pause playback (`composition.stops: [2, { at: 5, page: 'Name', notes, advance }]`; a `page` stop begins a page, the others are steps); deck() lays pages out
+// a presentation: stops pause playback (`composition.stops: [2, { at: 5, page: 'Name', notes, advance, pdf }]`; `pdf: true` = the stop that pictures its page in a PDF, `pdf: false` = keep it out; default the page's last stop; a `page` stop begins a page, the others are steps); deck() lays pages out
 await movie.init({ canvas, width, height, frameRate, ...deck({ transition: { kind: 'slide', direction: 'left', duration: 0.6 },
   pages: [{ name: 'Hello', duration: 3.2 /* last stop + transition */, stops: [2.6] /* page-local */, notes, sequences: [ /* page-local time; a step = a layer starting at the previous stop */ ] }] }) });
 new Presenter(movie, { canvas });         // import { Presenter } from 'pixi-effects/presenter': → ↓ Space Enter click = next, ← = back, Home / End, number+Enter, B / W, F, ?
-movie.next() / prev() / goToStop(i) / goToPage(n) / movie.stops / movie.on('stop', …)   // Controller shows the stops on the seek bar + a Present button
+movie.next() / prev() / goToStop(i) / goToPage(n) / movie.stops / movie.on('stop', …)   // Controller: marks on the seek bar, play / Space / click = play to the next stop (pauseAtStops: false = straight through), a Present button, PDF in the download panel
 // Presenter extras: G = page overview (pictures), P = presenter view (a second window: live picture, next picture, notes, timer); start() makes the pictures before the audience sees anything
-await movie.stopImages({ as: 'dataURL', scale: 0.25 }) // [{ stop, page, image }] one per page (its last stop); { which: 'stops' } one per stop
+await movie.stopImages({ as: 'dataURL', scale: 0.25 }) // [{ stop, page, image }] one per page (its last stop); { which: 'stops' } one per stop (a page's picture honours `pdf` flags)
 await movie.exportPDF({ title })                       // Blob: a PDF page per page of the deck; CLI: pixi-effects-render talk.html -o talk.pdf (--all-stops)
 const env = await audioEnvelope('music.mp3', { frameRate: 30 })   // BEFORE movie.init: .series.level|bass|mid|treble (0–1 per frame), .beats [s], .bpm, .at(t, band); bands: { name: [Hz, Hz] }
 const env = bpmEnvelope(120, { duration: 12 })                     // no audio file: kick / snare / hats exactly on a tempo
@@ -309,8 +309,8 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 51. **Arcs and rings are `shape: 'arc'`** (`radius`, `innerRadius`, `startAngle`, `endAngle`, degrees; 0° = 3 o'clock, clockwise). A progress ring is an arc with `startAngle: -90` and an animated `endAngle` (−90 → 270); `strokeCap: 'round'` rounds BOTH ends. Fill it for a pie slice, add `innerRadius` for a donut slice (a 120-polygon donut is no longer needed). Style (`strokeColor`, `strokeWidth`, `fillColor`) goes in `initial`; `strokeCap` / `strokeJoin` may be top level. *(fixed)*
 52. **Measure and split text with `measureText` / `splitText`, not by hand.** `splitText(text, style, { by, x, y, align })` returns each piece's x / y / width in the renderer's own font metrics (kerning kept; verified: a whole line vs the same line in per-letter layers differs only by anti-aliasing). The pieces are for text layers with the default top-left anchor and the same `style`. Load a web font before measuring (`await document.fonts.load('24px "Name"')`) or the fallback font's widths are used. Size a pill from `measureText(...).width + padding` instead of `0.58 × fontSize × length`. *(fixed)*
 53. **Draw-on and typewriter need no masks or per-letter layers.** `trimStart` / `trimEnd` (0–1 of the outline, animatable, every shape but `arc`) draw a stroke on: `trimEnd: 0` plus a keyframe `to: { trimEnd: 1 }`. The fill is not trimmed, so fade `fillAlpha` in afterwards; use `strokeCap: 'round'`. Text changes over time with `set: { text }` (swap at a time) and `visibleChars` (typewriter; left-align it so it grows rightward). A `to: { text }` cannot tween a string and warns. *(fixed)*
-54. **A deck page lasts until its last stop plus the transition.** `deck()` lays pages out one after another in page-local time and a `transition` overlaps them: a page shorter than its last stop (or shorter than the transition) loses its final step or flashes. A step is a layer that starts at the previous stop (`at: <previous stop>`), so the thing that appears on a press is fully visible when the movie stops. The transition option is `kind`, not `type`.
-55. **Presenter and Controller both listen to click and keys.** Use the `Presenter` for a talk (or let the Controller's Present button start one); do not run both on the same canvas yourself. Ordinary `play()` ignores stops; `movie.next()` plays to the next stop (a second press skips to it), `prev()` jumps back (nothing plays in reverse).
+54. **A deck page lasts until its last stop plus the transition.** `deck()` lays pages out one after another in page-local time and a `transition` overlaps them: a page shorter than its last stop (or shorter than the transition) loses its final step or flashes. A step is a layer that starts at the previous stop (`at: <previous stop>`), so the thing that appears on a press is fully visible when the movie stops. The transition option is `kind`, not `type`. If the last stop is mid-exit on paper, flag the stop you want in the PDF: `{ at, pdf: true }` (in `deck()`: `stops: [1.2, { at: 3, pdf: true }]`), and `pdf: false` keeps one out.
+55. **Presenter and Controller both listen to click and keys.** Use the `Presenter` for a talk (or let the Controller's Present button start one); do not run both on the same canvas yourself. `movie.play()` ignores stops, but the Controller's play button / Space / click-on-picture play to the next stop and pause (`pauseAtStops: false` plays through); `movie.next()` plays to the next stop (a second press skips to it), `prev()` jumps back (nothing plays in reverse).
 56. **Analyse audio before `init`, and give it the movie's frame rate.** `const env = await audioEnvelope('music.mp3', { frameRate })` is async; `react()` is pure and bakes the keyframes, so there is no per-frame callback. A custom `bands` list replaces the defaults (include `bass` if you want it; beats are picked there). No file yet: `bpmEnvelope(120, { duration })` is a stand-in with a kick on every beat. Offset the music with `audioOffset` when the audio layer does not start at 0.
 57. **Review a deck by its stops, not by its timeline.** `pixi-effects-check` writes `stops.png` (one picture per stop, in order) for a page with `stops`; the picture at a stop is what the audience reads while it waits.
 
@@ -1863,7 +1863,7 @@ initial: { x: 'GW/2', y: 'GH * 0.96', anchorX: 0.5, anchorY: 1 }
 
 ## Stops (presentations)
 
-`composition.stops` says where a presentation pauses: seconds, or `{ at, page?, notes?, advance? }` (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. A plain player ignores them (`Controller` shows marks on the seek bar); `movie.next()` and `Presenter` pause on them. [`deck()`](#deck) builds the whole thing from pages.
+`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.
 
 ## Transitions
 
@@ -2316,7 +2316,7 @@ await movie.init({ canvas, width: 1280, height: 720, frameRate: 30, ...deck({
 | ------ | ----- |
 | `pages[]` | required: `{ name?, duration, sequences, stops?, notes?, advance?, initial?, keyframes?, filters?, … }` |
 | `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) |
-| `page.stops` | page-local times: 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) |
+| `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) |
 | `page.notes`, `page.advance` | notes stay on the page's first stop; `advance` (seconds) on its last |
 | `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 |
 | movie options | `width`, `height`, `frameRate`, `background`, `canvas`, `assets`, `poster`, `motionBlur`, `loader` pass through |
@@ -2624,10 +2624,10 @@ The names are the ones an HTML5 `<video>` uses, so a player written for `<video>
 
 ### Presentations: `stops`, `next()`, `prev()`, `Presenter`
 
-A composition can say where a presentation pauses: `composition: { stops: [...] }`. A stop is a time in seconds or `{ at, page?, notes?, advance? }`; 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. Nothing changes for an ordinary player: playing a movie with stops just plays it.
+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.
 
 ```ts
-movie.stops                    // Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance? }
+movie.stops                    // Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance?, pdf? }
 await movie.next();            // play to the next stop and pause exactly on its frame; pressed again while playing, skip to that stop at once;
                                // after the last stop play to the end. Resolves when it has landed (or stopped for another reason).
 await movie.prev();            // jump back to the previous stop at once (no reverse playback); from the first stop, to the start
@@ -2668,7 +2668,7 @@ const pages = await movie.stopImages({ as: 'dataURL', type: 'image/jpeg', scale:
 const pdf = await movie.exportPDF({ title: 'My talk' });                                    // a Blob: one PDF page per page of the deck (JPEG at the canvas size)
 ```
 
-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). `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).
+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).
 
 ### Audio-reactive: `audioEnvelope()`, `react()`, `bpmEnvelope()`
 
@@ -2752,6 +2752,7 @@ interface ControllerOptions {
   showExportButton?: boolean;         // default true; hides ⬇ + popover
   enableKeyboardShortcuts?: boolean;  // default true
   present?: boolean;                  // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
+  pauseAtStops?: boolean;             // default true: with stops, play / Space / click on the picture play to the next stop and pause; false plays straight through
   clickToPlay?: boolean;              // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
   className?: string;                 // default 'movie-controller'
   theme?: ControllerTheme;            // colours / thickness / font of the bar, see Theme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixi-effects",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Declarative composition and video rendering for the web. Built on PixiJS v8.",
   "type": "module",
   "exports": {