pixi-effects 0.7.0 → 0.8.0

package/dist/three.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunk6I55T4OH_cjs = require('./chunk-6I55T4OH.cjs');
+var chunkAGMNSJJH_cjs = require('./chunk-AGMNSJJH.cjs');
 require('./chunk-UQBGW5DO.cjs');
 var pixi_js = require('pixi.js');
 var three$1 = require('three');
 
-var ThreeSequence = class extends chunk6I55T4OH_cjs.Sequence {
+var ThreeSequence = class extends chunkAGMNSJJH_cjs.Sequence {
   _renderer = null;
   _scene = null;
   _camera = null;
@@ -24,7 +24,7 @@ var ThreeSequence = class extends chunk6I55T4OH_cjs.Sequence {
     if (this.duration === void 0) {
       this.duration = this.parent?.duration ?? this.root.duration;
     }
-    const scope = chunk6I55T4OH_cjs.buildScope(this, this.parent, this.root);
+    const scope = chunkAGMNSJJH_cjs.buildScope(this, this.parent, this.root);
     const width = resolveDim(spec.width, scope) ?? this.parent?.width ?? this.root.width;
     const height = resolveDim(spec.height, scope) ?? this.parent?.height ?? this.root.height;
     const resolution = spec.resolution ?? 1;
@@ -144,12 +144,12 @@ var ThreeSequence = class extends chunk6I55T4OH_cjs.Sequence {
 function resolveDim(v, scope) {
   if (v === void 0) return void 0;
   if (typeof v === "number") return v;
-  return chunk6I55T4OH_cjs.evaluateExpr(v, scope);
+  return chunkAGMNSJJH_cjs.evaluateExpr(v, scope);
 }
 
 // src/three/index.ts
 function registerThree() {
-  chunk6I55T4OH_cjs.registerSequenceType("three", ThreeSequence);
+  chunkAGMNSJJH_cjs.registerSequenceType("three", ThreeSequence);
 }
 function three(spec) {
   return spec;

package/dist/three.js

@@ -1,4 +1,4 @@
-import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-4O2NYDJG.js';
+import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-FNKSXBKB.js';
 import './chunk-DKGG7WD4.js';
 import { Texture, Sprite } from 'pixi.js';
 import { WebGLRenderer, Scene, PerspectiveCamera } from 'three';

package/docs/api.md

@@ -163,6 +163,8 @@ interface RenderOptions {
 }
 ```
 
+**Audio codec fallback:** unless you name `audio.codec`, the first codec this browser can actually encode is used (mp4: `aac`, then `opus`, `mp3`, `flac`; webm: `opus`, `vorbis`). Chrome on Linux has no AAC encoder, so there an mp4 with sound carries Opus and a warning says so (before, the export failed with a message about encoder configurations). A codec you name is never swapped: if it cannot be encoded the error says which one would work.
+
 Returns a `Blob` whose `type` is the container's MIME (e.g. `video/mp4`). Emits `'progress'` repeatedly during the render.
 
 The renderer also forces a keyframe every ~2 seconds so the resulting file scrubs efficiently in standard players.
@@ -191,6 +193,12 @@ movie.off(event, fn): this
 | `'play'`    | none                                              | when `play()` actually transitions from paused        |
 | `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
 | `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
+| `'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()` |
+| `'ended'`   | none                                              | playback ran off the end (after `'pause'`); pausing by hand does not emit it |
+| `'volumechange'` | `{ volume: number; muted: boolean }`         | `volume` or `muted` really changed (clamping counts) |
+| `'error'`   | `{ where: 'init' \| 'render' \| 'playback'; message: string; error: unknown }` | `init()` / `render()` failed (the call still rejects), or a frame failed during playback |
+
+The names are the ones an HTML5 `<video>` uses, so a player written for `<video>` ports over.
 
 `progress` is `0..100` (rounded integer percent).
 
@@ -216,6 +224,24 @@ Flips `muted` and returns the new value.
 
 ---
 
+## Building your own player
+
+`Controller` is one optional player; everything it does is public on the movie, so a player of your own is plain HTML + CSS + a few handlers (`examples/15-custom-player.html` is a complete one):
+
+```js
+const el = id => document.getElementById(id);
+movie.on('ready', () => { el('seek').max = movie.totalFrames; });
+movie.on('frame', ({ frame }) => { el('seek').value = frame; el('time').textContent = (frame / movie.frameRate).toFixed(1) + ' s'; });
+movie.on('play',  () => { el('play').textContent = '❚❚'; });
+movie.on('pause', () => { el('play').textContent = '▶'; });
+movie.on('ended', () => { el('play').textContent = '↻'; });                 // play() at the end starts again from 0
+movie.on('volumechange', ({ volume, muted }) => { el('vol').value = muted ? 0 : volume; });
+el('play').onclick = () => (movie.isPlaying ? movie.pause() : movie.play());
+el('seek').oninput = e => movie.gotoFrame(+e.target.value);
+```
+
+What you have: `play()`, `pause()`, `gotoFrame(frame)`, `volume`, `muted` / `toggleMute()`; the state `currentFrame`, `totalFrames`, `frameRate`, `duration`, `isPlaying`, `isReady`; the events above; `render()` for a download button; `snapshot()` for a thumbnail; `timelineData()` / `timelineSvg()` for a timeline like `pixi-effects-view`'s. Keep the movie's `canvas` wherever your layout wants it (the page's CSS sizes it). To only change how `Controller` looks, see **Theme** below.
+
 ## `Controller`
 
 Imported from `pixi-effects/controller`.
@@ -247,6 +273,7 @@ interface ControllerOptions {
   showExportButton?: boolean;         // default true; hides ⬇ + popover
   enableKeyboardShortcuts?: boolean;  // default true
   className?: string;                 // default 'movie-controller'
+  theme?: ControllerTheme;            // colours / thickness / font of the bar, see Theme
 }
 ```
 
@@ -255,6 +282,30 @@ Mounting strategy:
 - If `canvas.parentElement` already has a non-static `position`, the controller is appended directly into it.
 - Otherwise the canvas is wrapped in a `<div class="movie-controller-wrap">` (with `position: relative`). The wrapper is removed on `destroy()`.
 
+### Theme: change the colours of the bar
+
+The bar is blue by default. Every colour and the track thickness are CSS custom properties with the old values as defaults, so there are two ways to change them:
+
+```js
+new Controller(movie, { canvas, theme: { accent: '#ff4d6d', foreground: '#ffe9a8', trackHeight: 5 } });   // in code
+controller.setTheme({ accent: '#7bd88f' });          // later, live; only the keys you give change
+controller.setTheme({ accent: null });               // null = back to the default
+```
+```css
+:root { --mc-accent: #ff4d6d; }                      /* or in your page CSS: the canvas's parent, or :root */
+```
+
+| `theme` key | CSS property | What | Default |
+|---|---|---|---|
+| `accent` | `--mc-accent` | progress bar, its thumb, focus rings, the export button | `#007AFF` |
+| `foreground` | `--mc-fg` | icons, the time, the volume slider | `#fff` |
+| `track` | `--mc-track` | the unfilled part of the progress / volume bars | `rgba(255,255,255,0.25)` |
+| `barBackground` | `--mc-bar-bg` | the background behind the buttons (any CSS background, e.g. a gradient) | black fading to transparent upward |
+| `trackHeight` | `--mc-track-height` | thickness of the progress bar (a number is px) | `3px` |
+| `font` | `--mc-font` | `font-family` of the bar | system UI font |
+
+A misspelt key warns with the valid ones. The default stylesheet is exported as `CONTROLLER_CSS` (from `pixi-effects/controller`) if you want to copy and restyle more.
+
 ### `controller.destroy(): void`
 
 Idempotent. Removes:

package/docs/dsl.md

@@ -944,7 +944,7 @@ A filter by name, as plain data. `type` is the filter's class name without `Filt
   keyframes: [{ at: 0, to: { 'filters.halo.outerStrength': 6 }, duration: 1 }] }       // animate any scalar option by name
 ```
 
-Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `blur`, `noise`, `alpha` and `colorMatrix` come from pixi.js. All the others come from the **`pixi-filters`** package, which is loaded the first time a layer uses one (add `"pixi-filters": "https://esm.sh/pixi-filters@6.1.5?external=pixi.js"` to the import map, or `npm i pixi-filters`; `ai/template.html` already has it). A misspelt type says what you probably meant. Verified rendering and exporting in a real browser (`examples/_checks/named-filters.html`, 24 filters):
+Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `blur`, `noise`, `alpha` and `colorMatrix` come from pixi.js. All the others come from the **`pixi-filters`** package, which is loaded the first time a layer uses one (add `"pixi-filters": "https://esm.sh/pixi-filters@6.1.5?external=pixi.js"` to the import map, or `npm i pixi-filters`; `ai/template.html` already has it). A misspelt type says what you probably meant. Rendering and exporting were verified in a real browser for 40 of them (`examples/_checks/named-filters.html` and `named-filters-2.html`); `colorMap` and `simpleLightmap` need a texture, which JSON cannot hold, so use `custom` for those two:
 
 | `type` | Options (the useful ones) | What it does |
 |---|---|---|
@@ -972,13 +972,25 @@ Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `bl
 | `ascii` | `size color replaceColor` | Text-art |
 | `colorOverlay` | `color alpha` | Tint over everything |
 | `advancedBloom` / `bloom` | `threshold bloomScale brightness blur` | Bloom |
-| `bevel`, `dot`, `crossHatch`, `tiltShift`, `reflection`, `shockwave`, `godray`, `simplexNoise`, `colorGradient`, `colorMap`, `colorReplace`, `multiColorReplace`, `convolution`, `backdropBlur`, `simpleLightmap`, `tiltShiftAxis` | see the [pixi-filters docs](https://pixijs.io/filters/docs/) | Other pixi-filters |
+| `bevel` | `thickness rotation lightColor lightAlpha shadowColor shadowAlpha` | Raised edge |
+| `dot` / `crossHatch` | `scale angle grayscale` / – | Halftone / hatching |
+| `godray` | `angle gain lacunarity alpha parallel time` | Light shafts (animate `time`) |
+| `reflection` | `mirror boundary amplitude waveLength alpha time` (ranges are `[start, end]`) | Water reflection |
+| `simplexNoise` | `strength scale offset` | Cloudy noise over the layer |
+| `colorGradient` | `gradientType: 'linear' 'radial' 'conic'` (the filter's own option is `type`, which the DSL uses), `stops: [{ offset, color, alpha }]`, `angle` | A gradient laid over the layer |
+| `colorReplace` / `multiColorReplace` | `originalColor targetColor tolerance` / `replacements: [[from, to], …] tolerance` | Swap colours |
+| `convolution` | `matrix` (9 numbers), `width height` | Sharpen, edge detect |
+| `tiltShift` / `tiltShiftAxis` | `blur gradientBlur start end` (canvas pixels) | Miniature blur |
+| `shockwave` | `center amplitude wavelength brightness speed radius time` (animate `time` 0 → 1) | A ripple from a point |
+| `backdropBlur` | `strength` | Blurs what is BEHIND the layer, so alone it shows nothing |
+| the rest of pixi-filters (`colorMap`, `simpleLightmap`) | need a texture: `{ type: 'custom' }` | see the [pixi-filters docs](https://pixijs.io/filters/docs/) |
 
 Gotchas, all measured:
 
 - **Centres and offsets are in canvas pixels, not the layer's:** `twist.offset`, `bulgePinch.center`, `zoomBlur.center`, `radialBlur.center`, `shockwave.center` default to the canvas's top-left corner, so a layer in the middle looks unaffected. Put the centre on the layer: `{ type: 'twist', offset: { x: 640, y: 360 } }` for a layer centred on a 1280×720 canvas.
 - **A filter works inside the layer's bounds.** Glow, dropShadow, outline and blur draw outside it and are clipped unless you widen the area (`filterArea: { x: -24, y: -24, width: w + 48, height: h + 48 }`, in the layer's own coordinates). Do not widen it for `grayscale`, `oldFilm` or other filters that paint the whole area: they fill the extra margin with black.
 - **Animate scalars by name** (`'filters.halo.outerStrength'`). Options that are points (`rgbSplit.red`, `dropShadow.offset`) do not tween as a whole; animate `'filters.<name>.red.x'` if the filter exposes it, or swap the filter. `pixelate` animates through `sizeX` / `sizeY`, not `size`.
+- `shockwave` and `godray` are driven by `time` (a still frame at `time: 0` looks like nothing): animate it. `radialBlur`, `shockwave` and `tiltShift` positions are canvas pixels too.
 - Some filters take their value as one argument; the DSL hides that (`{ type: 'pixelate', size: 8 }`, `{ type: 'emboss', strength: 6 }`).
 
 ### `custom`

package/llms-full.txt

@@ -139,9 +139,13 @@ Style (`initial` / keyframes): `fillColor fillAlpha strokeColor strokeAlpha stro
 
 Add `threeD: true` to any visual layer, then use `z`, `rotationX`, `rotationY` (centre rotation with `anchorX/Y: 0.5` or `pivotX/Y`). Add a `{ type: 'camera' }` layer for a view. A `threeD` layer at `z: 0` with the default camera looks identical to a 2D one. Consecutive `threeD` layers are drawn farthest-first (equal `z` keeps array order); non-`threeD` layers ignore the camera and keep array order. Layers at/behind the camera plane are hidden. Not supported on `threeD` layers: masks, transitions, `filterArea`.
 
+## Player
+
+`new Controller(movie, { canvas, theme: { accent: '#ff4d6d' } })` (import from `pixi-effects/controller`; theme keys `accent foreground track barBackground trackHeight font`, or CSS `--mc-accent` …; `controller.setTheme(…)`). Your own player: `movie.play() pause() gotoFrame(f) volume muted toggleMute()`, state `currentFrame totalFrames frameRate duration isPlaying`, events `ready frame play pause ended seeking seeked volumechange error progress` (`<video>` names). `examples/15-custom-player.html` is a complete one.
+
 ## Filters by name (no import)
 
-`filters: [{ type: 'glow', name: 'halo', outerStrength: 3, color: '#ffd166' }]` — `type` = the pixi / pixi-filters class name without `Filter`, camelCase (`glow dropShadow outline blur noise alpha adjustment hslAdjustment grayscale pixelate crt rgbSplit oldFilm glitch bulgePinch twist zoomBlur kawaseBlur radialBlur motionBlur emboss ascii colorOverlay advancedBloom bevel dot crossHatch tiltShift …`), the other keys are its options. `colorMatrix` takes `preset: 'sepia'|'grayscale'|'negative'|'polaroid'|'technicolor'|'vintage'|'kodachrome'|'browni'`. Name it to animate: `'filters.halo.outerStrength'` (scalars only; `pixelate` via `sizeX`/`sizeY`). Options: `glow` distance outerStrength innerStrength color alpha · `dropShadow` offset{x,y} blur alpha color · `outline` thickness color · `blur` strength · `adjustment` gamma contrast saturation brightness · `hslAdjustment` hue lightness saturation · `pixelate` size · `crt` curvature lineWidth noise vignetting · `rgbSplit` red/green/blue {x,y} · `oldFilm` sepia noise scratch vignetting · `glitch` slices offset · `twist` radius angle offset · `bulgePinch` center radius strength · `zoomBlur` strength center innerRadius · `colorOverlay` color alpha. **Centres/offsets are CANVAS pixels** (default top-left corner): put them on the layer. Glow / shadow / blur draw outside the layer: widen `filterArea` (not for `grayscale` / `oldFilm`, which fill the margin black). Full table: `docs/dsl.md` → Named filters.
+`filters: [{ type: 'glow', name: 'halo', outerStrength: 3, color: '#ffd166' }]` — `type` = the pixi / pixi-filters class name without `Filter`, camelCase (`glow dropShadow outline blur noise alpha adjustment hslAdjustment grayscale pixelate crt rgbSplit oldFilm glitch bulgePinch twist zoomBlur kawaseBlur radialBlur motionBlur emboss ascii colorOverlay advancedBloom bevel dot crossHatch tiltShift …`), the other keys are its options. `colorMatrix` takes `preset: 'sepia'|'grayscale'|'negative'|'polaroid'|'technicolor'|'vintage'|'kodachrome'|'browni'`. Name it to animate: `'filters.halo.outerStrength'` (scalars only; `pixelate` via `sizeX`/`sizeY`). Options: `glow` distance outerStrength innerStrength color alpha · `dropShadow` offset{x,y} blur alpha color · `outline` thickness color · `blur` strength · `adjustment` gamma contrast saturation brightness · `hslAdjustment` hue lightness saturation · `pixelate` size · `crt` curvature lineWidth noise vignetting · `rgbSplit` red/green/blue {x,y} · `oldFilm` sepia noise scratch vignetting · `glitch` slices offset · `twist` radius angle offset · `bulgePinch` center radius strength · `zoomBlur` strength center innerRadius · `colorOverlay` color alpha · `colorGradient` gradientType('linear'|'radial'|'conic') stops[{offset,color,alpha}] angle · `colorReplace` originalColor targetColor tolerance · `convolution` matrix(9) · `shockwave` / `godray` are driven by `time` (animate it) · `colorMap` / `simpleLightmap` need a texture (use `custom`). **Centres/offsets are CANVAS pixels** (default top-left corner): put them on the layer. Glow / shadow / blur draw outside the layer: widen `filterArea` (not for `grayscale` / `oldFilm`, which fill the margin black). Full table: `docs/dsl.md` → Named filters.
 
 ## Transitions (on the parent composition)
 
@@ -1757,7 +1761,7 @@ A filter by name, as plain data. `type` is the filter's class name without `Filt
   keyframes: [{ at: 0, to: { 'filters.halo.outerStrength': 6 }, duration: 1 }] }       // animate any scalar option by name
 ```
 
-Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `blur`, `noise`, `alpha` and `colorMatrix` come from pixi.js. All the others come from the **`pixi-filters`** package, which is loaded the first time a layer uses one (add `"pixi-filters": "https://esm.sh/pixi-filters@6.1.5?external=pixi.js"` to the import map, or `npm i pixi-filters`; `ai/template.html` already has it). A misspelt type says what you probably meant. Verified rendering and exporting in a real browser (`examples/_checks/named-filters.html`, 24 filters):
+Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `blur`, `noise`, `alpha` and `colorMatrix` come from pixi.js. All the others come from the **`pixi-filters`** package, which is loaded the first time a layer uses one (add `"pixi-filters": "https://esm.sh/pixi-filters@6.1.5?external=pixi.js"` to the import map, or `npm i pixi-filters`; `ai/template.html` already has it). A misspelt type says what you probably meant. Rendering and exporting were verified in a real browser for 40 of them (`examples/_checks/named-filters.html` and `named-filters-2.html`); `colorMap` and `simpleLightmap` need a texture, which JSON cannot hold, so use `custom` for those two:
 
 | `type` | Options (the useful ones) | What it does |
 |---|---|---|
@@ -1785,13 +1789,25 @@ Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `bl
 | `ascii` | `size color replaceColor` | Text-art |
 | `colorOverlay` | `color alpha` | Tint over everything |
 | `advancedBloom` / `bloom` | `threshold bloomScale brightness blur` | Bloom |
-| `bevel`, `dot`, `crossHatch`, `tiltShift`, `reflection`, `shockwave`, `godray`, `simplexNoise`, `colorGradient`, `colorMap`, `colorReplace`, `multiColorReplace`, `convolution`, `backdropBlur`, `simpleLightmap`, `tiltShiftAxis` | see the [pixi-filters docs](https://pixijs.io/filters/docs/) | Other pixi-filters |
+| `bevel` | `thickness rotation lightColor lightAlpha shadowColor shadowAlpha` | Raised edge |
+| `dot` / `crossHatch` | `scale angle grayscale` / – | Halftone / hatching |
+| `godray` | `angle gain lacunarity alpha parallel time` | Light shafts (animate `time`) |
+| `reflection` | `mirror boundary amplitude waveLength alpha time` (ranges are `[start, end]`) | Water reflection |
+| `simplexNoise` | `strength scale offset` | Cloudy noise over the layer |
+| `colorGradient` | `gradientType: 'linear' 'radial' 'conic'` (the filter's own option is `type`, which the DSL uses), `stops: [{ offset, color, alpha }]`, `angle` | A gradient laid over the layer |
+| `colorReplace` / `multiColorReplace` | `originalColor targetColor tolerance` / `replacements: [[from, to], …] tolerance` | Swap colours |
+| `convolution` | `matrix` (9 numbers), `width height` | Sharpen, edge detect |
+| `tiltShift` / `tiltShiftAxis` | `blur gradientBlur start end` (canvas pixels) | Miniature blur |
+| `shockwave` | `center amplitude wavelength brightness speed radius time` (animate `time` 0 → 1) | A ripple from a point |
+| `backdropBlur` | `strength` | Blurs what is BEHIND the layer, so alone it shows nothing |
+| the rest of pixi-filters (`colorMap`, `simpleLightmap`) | need a texture: `{ type: 'custom' }` | see the [pixi-filters docs](https://pixijs.io/filters/docs/) |
 
 Gotchas, all measured:
 
 - **Centres and offsets are in canvas pixels, not the layer's:** `twist.offset`, `bulgePinch.center`, `zoomBlur.center`, `radialBlur.center`, `shockwave.center` default to the canvas's top-left corner, so a layer in the middle looks unaffected. Put the centre on the layer: `{ type: 'twist', offset: { x: 640, y: 360 } }` for a layer centred on a 1280×720 canvas.
 - **A filter works inside the layer's bounds.** Glow, dropShadow, outline and blur draw outside it and are clipped unless you widen the area (`filterArea: { x: -24, y: -24, width: w + 48, height: h + 48 }`, in the layer's own coordinates). Do not widen it for `grayscale`, `oldFilm` or other filters that paint the whole area: they fill the extra margin with black.
 - **Animate scalars by name** (`'filters.halo.outerStrength'`). Options that are points (`rgbSplit.red`, `dropShadow.offset`) do not tween as a whole; animate `'filters.<name>.red.x'` if the filter exposes it, or swap the filter. `pixelate` animates through `sizeX` / `sizeY`, not `size`.
+- `shockwave` and `godray` are driven by `time` (a still frame at `time: 0` looks like nothing): animate it. `radialBlur`, `shockwave` and `tiltShift` positions are canvas pixels too.
 - Some filters take their value as one argument; the DSL hides that (`{ type: 'pixelate', size: 8 }`, `{ type: 'emboss', strength: 6 }`).
 
 ### `custom`
@@ -2115,6 +2131,8 @@ interface RenderOptions {
 }
 ```
 
+**Audio codec fallback:** unless you name `audio.codec`, the first codec this browser can actually encode is used (mp4: `aac`, then `opus`, `mp3`, `flac`; webm: `opus`, `vorbis`). Chrome on Linux has no AAC encoder, so there an mp4 with sound carries Opus and a warning says so (before, the export failed with a message about encoder configurations). A codec you name is never swapped: if it cannot be encoded the error says which one would work.
+
 Returns a `Blob` whose `type` is the container's MIME (e.g. `video/mp4`). Emits `'progress'` repeatedly during the render.
 
 The renderer also forces a keyframe every ~2 seconds so the resulting file scrubs efficiently in standard players.
@@ -2143,6 +2161,12 @@ movie.off(event, fn): this
 | `'play'`    | none                                              | when `play()` actually transitions from paused        |
 | `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
 | `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
+| `'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()` |
+| `'ended'`   | none                                              | playback ran off the end (after `'pause'`); pausing by hand does not emit it |
+| `'volumechange'` | `{ volume: number; muted: boolean }`         | `volume` or `muted` really changed (clamping counts) |
+| `'error'`   | `{ where: 'init' \| 'render' \| 'playback'; message: string; error: unknown }` | `init()` / `render()` failed (the call still rejects), or a frame failed during playback |
+
+The names are the ones an HTML5 `<video>` uses, so a player written for `<video>` ports over.
 
 `progress` is `0..100` (rounded integer percent).
 
@@ -2168,6 +2192,24 @@ Flips `muted` and returns the new value.
 
 ---
 
+## Building your own player
+
+`Controller` is one optional player; everything it does is public on the movie, so a player of your own is plain HTML + CSS + a few handlers (`examples/15-custom-player.html` is a complete one):
+
+```js
+const el = id => document.getElementById(id);
+movie.on('ready', () => { el('seek').max = movie.totalFrames; });
+movie.on('frame', ({ frame }) => { el('seek').value = frame; el('time').textContent = (frame / movie.frameRate).toFixed(1) + ' s'; });
+movie.on('play',  () => { el('play').textContent = '❚❚'; });
+movie.on('pause', () => { el('play').textContent = '▶'; });
+movie.on('ended', () => { el('play').textContent = '↻'; });                 // play() at the end starts again from 0
+movie.on('volumechange', ({ volume, muted }) => { el('vol').value = muted ? 0 : volume; });
+el('play').onclick = () => (movie.isPlaying ? movie.pause() : movie.play());
+el('seek').oninput = e => movie.gotoFrame(+e.target.value);
+```
+
+What you have: `play()`, `pause()`, `gotoFrame(frame)`, `volume`, `muted` / `toggleMute()`; the state `currentFrame`, `totalFrames`, `frameRate`, `duration`, `isPlaying`, `isReady`; the events above; `render()` for a download button; `snapshot()` for a thumbnail; `timelineData()` / `timelineSvg()` for a timeline like `pixi-effects-view`'s. Keep the movie's `canvas` wherever your layout wants it (the page's CSS sizes it). To only change how `Controller` looks, see **Theme** below.
+
 ## `Controller`
 
 Imported from `pixi-effects/controller`.
@@ -2199,6 +2241,7 @@ interface ControllerOptions {
   showExportButton?: boolean;         // default true; hides ⬇ + popover
   enableKeyboardShortcuts?: boolean;  // default true
   className?: string;                 // default 'movie-controller'
+  theme?: ControllerTheme;            // colours / thickness / font of the bar, see Theme
 }
 ```
 
@@ -2207,6 +2250,30 @@ Mounting strategy:
 - If `canvas.parentElement` already has a non-static `position`, the controller is appended directly into it.
 - Otherwise the canvas is wrapped in a `<div class="movie-controller-wrap">` (with `position: relative`). The wrapper is removed on `destroy()`.
 
+### Theme: change the colours of the bar
+
+The bar is blue by default. Every colour and the track thickness are CSS custom properties with the old values as defaults, so there are two ways to change them:
+
+```js
+new Controller(movie, { canvas, theme: { accent: '#ff4d6d', foreground: '#ffe9a8', trackHeight: 5 } });   // in code
+controller.setTheme({ accent: '#7bd88f' });          // later, live; only the keys you give change
+controller.setTheme({ accent: null });               // null = back to the default
+```
+```css
+:root { --mc-accent: #ff4d6d; }                      /* or in your page CSS: the canvas's parent, or :root */
+```
+
+| `theme` key | CSS property | What | Default |
+|---|---|---|---|
+| `accent` | `--mc-accent` | progress bar, its thumb, focus rings, the export button | `#007AFF` |
+| `foreground` | `--mc-fg` | icons, the time, the volume slider | `#fff` |
+| `track` | `--mc-track` | the unfilled part of the progress / volume bars | `rgba(255,255,255,0.25)` |
+| `barBackground` | `--mc-bar-bg` | the background behind the buttons (any CSS background, e.g. a gradient) | black fading to transparent upward |
+| `trackHeight` | `--mc-track-height` | thickness of the progress bar (a number is px) | `3px` |
+| `font` | `--mc-font` | `font-family` of the bar | system UI font |
+
+A misspelt key warns with the valid ones. The default stylesheet is exported as `CONTROLLER_CSS` (from `pixi-effects/controller`) if you want to copy and restyle more.
+
 ### `controller.destroy(): void`
 
 Idempotent. Removes:

package/package.json

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

package/dist/Composition-3KHQPRBA.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var chunk4VSIJLU3_cjs = require('./chunk-4VSIJLU3.cjs');
-require('./chunk-6I55T4OH.cjs');
-require('./chunk-UQBGW5DO.cjs');
-
-
-
-Object.defineProperty(exports, "CompositionSequence", {
-  enumerable: true,
-  get: function () { return chunk4VSIJLU3_cjs.CompositionSequence; }
-});
-//# sourceMappingURL=Composition-3KHQPRBA.cjs.map
-//# sourceMappingURL=Composition-3KHQPRBA.cjs.map

package/dist/Composition-DT657FO5.js

@@ -1,5 +0,0 @@
-export { CompositionSequence } from './chunk-36Z4RIRK.js';
-import './chunk-4O2NYDJG.js';
-import './chunk-DKGG7WD4.js';
-//# sourceMappingURL=Composition-DT657FO5.js.map
-//# sourceMappingURL=Composition-DT657FO5.js.map