pixi-effects 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.16.1
+
+**Added**
+
+- **`musicBuffer(music, { sampleRate?, duration?, loop? })`**: the sound of `music` as a Web Audio `AudioBuffer`, to play without a movie.
+- **`examples/music-lab.html`**: eight tunes written as text (a lo-fi loop, a launch build, a jingle, a thriller opening, three Christmas pieces, and the first test tune), each with its brief, a play / stop button, its score shown as source, Copy score and Save as WAV. Seven of them were written by fresh Claude sessions from the notation guide and a one-line brief. Linked from the guide's Audio page, the README and the examples page.
+
+## 0.16.0
+
+**Added**
+
+- **Music written as text.** `{ type: 'audio', music: { bpm, tracks, drums } }` plays a tune with no audio file: notes (`c4:2`), chords by name (`Am7`, `Cmaj7`, `G7sus4`, `Bm7b5`, `C@4`, `Am7/e`), rests, holds and accents as strings, counted in beats, played by a small built-in synthesiser. Eight instruments (`keys` electric piano, `pluck`, `pad`, `bass`, `sub`, `lead`, `bell`, `musicbox`) and ten drums (`kick snare hat openhat clap rim tom crash shaker sleigh`) as step patterns, with `swing`, `reverb`, a `grid` for 6/8 and triplet feels, `humanize`, `transpose`, per-track `vol` points (a fade or a swell), `pan`, `tone`, `reverb` send, `attack` / `release` / `ring`, drum sections (`from` / `to`), and a tempo that changes (`bpm: [[0, 96], [28, 96], [32, 60]]`, a ritardando). Deterministic, in the exported file at the same moment, its own chunk (movies without music never load it). It lasts its notes plus a tail and ends with the movie; `loop: true` repeats it; at `volume: 1` it peaks at −6 dBFS. Mistakes warn with "did you mean" (an instrument, a drum, an option, a note it cannot read names the track and the token). The sound was approved by ear from a spike: eight tunes written by AI sessions from the notation alone (lo-fi, a heroic build, a jingle, a dark opening, three Christmas pieces).
+- **`musicEnvelope(music, { frameRate })`**: the envelope of that music for `react()`: `level` / `bass` / `mid` / `treble` from analysing the very sound the layer plays, exact beats (the kick hits, or every beat) and the starting tempo.
+- A gallery piece with a score and no audio file, `christmas-eve` (38 pieces), guide section "Music written as text" in Audio, a recipe, `ai/CHAT.md` section with a tested example, and DSL / API / cheatsheet / pitfalls entries.
+
 ## 0.15.0
 
 **Added**

package/README.md

@@ -1,8 +1,8 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.15.0`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.15.0` adds a way in for an AI in a browser chat (`ai/CHAT.md` and `ai/chat-template.html`), `0.14.0` adds `movie.inspectStops()` (and a check review) for stops that land mid-animation, `0.13.1` fixes decks starting past their first stop in the guide and gallery and draws the stop marks as dots, `0.13.0` makes the player bar play a deck stop by stop (`pauseAtStops`), marks the stops more clearly, adds PDF to the download panel and a `pdf` flag on stops, `0.12.0` adds presentations (`stops`, `Presenter`, `deck()`, page overview, presenter view, PDF export) and audio-reactive visuals (`audioEnvelope()`, `react()`), `0.11.0` adds particles, motion blur, a shared loader and a much faster build for pieces with many layers, `0.10.0` adds seeded randomness, `wiggle` and `stagger`, null layers with `parent`, `animateText`, `followPath` and path morphing, and click-to-play in the player, `0.9.0` adds a poster time (`movie.init({ poster })`) and a guide site, `0.8.0` adds events and a theme for building your own player, `0.7.0` adds filters by name, the `pixi-effects-render` and `pixi-effects-view` commands and the timeline chart, `0.6.0` adds draw-on strokes (`trimEnd`) and text that changes over time, `0.5.0` adds synthesised sound effects (`sfx`, no files) and the `check` tool, `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
+> **Status**: experimental — current release `0.16.1`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.16.1` adds `musicBuffer()` and a music lab page with eight tunes, `0.16.0` adds music written as text (`{ type: 'audio', music }`, `musicEnvelope()`), `0.15.0` adds a way in for an AI in a browser chat (`ai/CHAT.md` and `ai/chat-template.html`), `0.14.0` adds `movie.inspectStops()` (and a check review) for stops that land mid-animation, `0.13.1` fixes decks starting past their first stop in the guide and gallery and draws the stop marks as dots, `0.13.0` makes the player bar play a deck stop by stop (`pauseAtStops`), marks the stops more clearly, adds PDF to the download panel and a `pdf` flag on stops, `0.12.0` adds presentations (`stops`, `Presenter`, `deck()`, page overview, presenter view, PDF export) and audio-reactive visuals (`audioEnvelope()`, `react()`), `0.11.0` adds particles, motion blur, a shared loader and a much faster build for pieces with many layers, `0.10.0` adds seeded randomness, `wiggle` and `stagger`, null layers with `parent`, `animateText`, `followPath` and path morphing, and click-to-play in the player, `0.9.0` adds a poster time (`movie.init({ poster })`) and a guide site, `0.8.0` adds events and a theme for building your own player, `0.7.0` adds filters by name, the `pixi-effects-render` and `pixi-effects-view` commands and the timeline chart, `0.6.0` adds draw-on strokes (`trimEnd`) and text that changes over time, `0.5.0` adds synthesised sound effects (`sfx`, no files) and the `check` tool, `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
 
-**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 37 portfolio pieces written as plain data by AI models · **[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
+**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 38 portfolio pieces written as plain data by AI models · **[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
 
 **Make a video with an AI chat** (no install): paste this to ChatGPT or Claude in the browser, then open the file it gives you and use the download button in the player bar for the MP4:
 
@@ -20,6 +20,7 @@ Declarative composition and video rendering for the web. After Effects-style tim
 - **Masks, transitions, chroma key** — inline masks; chroma key; seven scene transitions (`crossfade`, `wipe`, `iris`, `slide`, `dip`, `zoom`, `dissolve`).
 - **Presets** — `kenBurns` for stills, `withFade` for fade-in/out; `wiggle`, `stagger`, `animateText`, `followPath`, `particles` and `react` return keyframes or layers (seeded, so every render is the same).
 - **Presentations** — `stops` in the composition pause the movie where you say; `Presenter` (`pixi-effects/presenter`) moves on with arrow keys, a click or a swipe, with a page overview (G), a presenter view with notes and a timer (P), and `deck()` to lay out pages and steps. Export a deck as PDF (`movie.exportPDF()`, `pixi-effects-render talk.html -o talk.pdf`). See the [Presenting guide](https://yjmtmtk.github.io/pixi-effects/guide/presenting.html).
+- **Music written as text** — `{ type: 'audio', music: { bpm: 96, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }], drums: { kick: 'x...x...' } } }`: a tune with no audio file, played by a small built-in synthesiser (keys, pluck, pad, bass, lead, bell, music box, drums; chords by name, swing, fades, a ritardando). Deterministic, in the exported file at the same moment; an AI writes it as easily as a title.
 - **Audio-reactive visuals** — `audioEnvelope('music.mp3')` analyses loudness, bass / mid / treble and the beats per frame; `react()` turns them into keyframes, so the picture follows the music and still renders identically.
 - **2.5D layers & camera** — add `threeD: true`, `z`, `rotationX/Y` and a `{ type: 'camera' }` layer for parallax, flips and dolly zooms; no three.js needed.
 - **three.js layer** *(optional)* — drop a real three.js scene in as a layer via `pixi-effects/three`; keyframes drive its objects (`three.cube.rotation.y`).
@@ -48,8 +49,8 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
     "gsap":                    "https://esm.sh/gsap@3.12.5",
     "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
     "mediabunny":              "https://esm.sh/mediabunny",
-    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Controller.js"
   }
 }
 </script>
@@ -60,7 +61,7 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
 </script>
 ```
 
-Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.15.0/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.16.1/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
 
 > **Using three.js?** Add two more entries (`three` and `pixi-effects/three`) to this importmap — see [Adding three.js](#adding-threejs-optional) below.
 >
@@ -76,7 +77,7 @@ Add two more entries to the importmap above: three.js itself, and the `pixi-effe
   "imports": {
     "...":                     "(everything from the importmap above)",
     "three":                   "https://esm.sh/three@0.178.0",
-    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/three.js"
   }
 }
 </script>
@@ -200,6 +201,7 @@ They ship in the npm package (`node_modules/pixi-effects/ai/`).
   - `13-sfx.html` — synthesised sound effects (no audio files), a riser into a hit, a custom voice
   - `15-custom-player.html` — a complete player of your own in about 40 lines (play, seek, volume, replay) using the movie's events
   - `14-draw-on.html` — draw-on strokes (`trimStart` / `trimEnd`) and text that changes over time (`visibleChars`, `set: { text }`)
+  - `music-lab.html` — eight tunes written as text (no audio files): press play, read each score; `musicBuffer()` plays music with no movie
   - `playground.html` — in-browser editor with preset dropdown
 
 ## Browser support

package/ai/CHAT.md

@@ -56,11 +56,42 @@ That is a complete, working video (the block between the two markers). Change th
 - **Shapes:** `shape: 'rect' | 'circle' | 'ellipse' | 'arc' | 'line' | 'polygon' | 'path'`. `rect`: `width height cornerRadius`; `circle`: `radius`; `line`: `from: [x, y], to: [x, y]` (canvas coordinates, no `x, y`); `path`: `d` (SVG path data). Style: `fillColor strokeColor strokeWidth fillAlpha`.
 - **Text:** `style` is a PixiJS text style (`fontSize fontFamily fontWeight fill letterSpacing align wordWrap wordWrapWidth lineHeight`). Use fonts that exist everywhere (`Georgia, serif`, `Arial, sans-serif`, `ui-monospace, monospace`); this page loads no web fonts. Estimate a text's width at about 0.6 × `fontSize` per character, keep important text 5 % away from the edges, and keep the bottom 60 px free (the player bar covers it in the preview, not in the file).
 - **Scenes.** Stack layers with `at` / `duration` over an opaque background rect. Do not remove layers.
-- **Sound with no files:** `{ type: 'audio', sfx: 'swoosh', at: 2 }`. Presets: `click pop swoosh swipe hit riser chime beep coin glitch typewriter`; optional `pitch`, `brightness`. A `riser` is loudest at its **end**: start it `duration` seconds before the hit. This page cannot load music or images from your own files; use shapes, text and sfx.
+- **Sound with no files:** `{ type: 'audio', sfx: 'swoosh', at: 2 }`. Presets: `click pop swoosh swipe hit riser chime beep coin glitch typewriter`; optional `pitch`, `brightness`. A `riser` is loudest at its **end**: start it `duration` seconds before the hit. This page cannot load music or images from your own files; use shapes, text, sfx and `music` (below).
 - **Repeat with code, never by copying:** `Array.from({ length: 12 }, (_, i) => ({ type: 'shape', shape: 'circle', radius: 20, at: i * 0.15, duration: DURATION - i * 0.15, initial: { x: 120 + i * 90, y: 360, fillColor: '#ffd166' }, keyframes: [{ at: 0, from: { scale: 0 }, to: { scale: 1 }, duration: 0.4, ease: 'back.out(2)' }] }))` returns twelve layers: spread them into `sequences` with `...`.
 - **Helpers already imported** in the template: `kenBurns` (slow zoom for an image layer), `withFade`, `wiggle` (seeded shake as keyframes), `stagger`, `animateText` (per letter / word entrances), `followPath`, `particles` (seeded confetti / snow / sparks as layers), `deck` (slides). Each returns keyframes or layers: `keyframes: wiggle(...)`, `...particles(...)`. The full signatures are in `https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/reference/cheatsheet.md` (22 KB; read it only if you need a helper).
 - **Not available on this page:** named filters beyond `blur`, `noise`, `alpha`, `colorMatrix` (the other 38 need the `pixi-filters` package), three.js layers, your own image / video / music files. Say so rather than guessing.
 
+## Music with no file
+
+Write the tune as text: an audio layer with `music`. Tracks of notes and chords, optional drums, a tempo. The unit is the **beat** (a quarter note; a 4/4 bar is 4 beats; make every track the same length).
+
+```js
+// @chat-music
+const W = 1280, H = 720, FPS = 30, DURATION = 22;
+const BACKGROUND = '#0e1a2b';
+
+const sequences = [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: BACKGROUND } },
+  {
+    type: 'text', text: 'Snowfall', name: 'title', at: 1, duration: DURATION - 1,
+    style: { fontFamily: 'Georgia, serif', fontSize: 120, fill: '#e8f1ff', letterSpacing: 6 },
+    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+    keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 2.5 }],
+  },
+  { type: 'audio', volume: 0.8, music: {                 // a slow 6/8 lullaby in F major: 8 bars of 3 beats
+    bpm: 72, grid: 2, reverb: 0.3, seed: 5,
+    tracks: [
+      { inst: 'musicbox', vol: 0.8, notes: 'a5:1.5 c6:1.5 | a5:1 g5:0.5 f5:1.5 | d6:1.5 a5:1.5 | bb5:1 a5:0.5 g5:1.5 | g5:1.5 d6:1.5 | e6:1 d6:0.5 c6:1.5 | a5:1 c6:0.5 f6:1.5 | f6:3' },
+      { inst: 'pluck', vol: 0.45, pan: -0.2, step: 0.5, notes: 'f3 a3 c4 a3 c4 a3 | f3 a3 c4 a3 c4 a3 | d3 f3 a3 f3 a3 f3 | bb2 d3 f3 d3 f3 d3 | g3 bb3 d4 bb3 d4 bb3 | c3 e3 g3 e3 g3 e3 | f3 a3 c4 a3 c4 a3 | f3 a3 c4 g4 c4 a3' },
+      { inst: 'pad', vol: [[0, 0], [6, 0.5]], attack: 1.2, notes: '[f3 a3 c4]:6 [d3 f3 a3 c4]:3 [bb2 d3 f3 a3]:3 [g2 bb2 d3 f3]:3 [c3 e3 g3 bb3]:3 [f3 a3 c4]:3 [f3 g3 a3 c4]:3' },
+    ],
+  } },
+];
+const POSTER = 8;
+```
+
+Every token is a note (`c4`, `f#3`, `Bb2`) with its length in beats after a colon, a chord by name (`Am7`, `Dsus4`, `C@4`, `Am7/e`) or written out (`[c4 e4 g4]:2`), a rest `_`, or a hold `~`; `|` is ignored. Instruments: `keys pluck pad bass sub lead bell musicbox`. Drums: `drums: [{ from: 8, kick: 'x.......x.x.....', snare: '....x.......x...', hat: 'x.x.x.x.x.x.x.xo' }]` (16 steps = one 4/4 bar; `from` is a beat; `x` hit, `o` soft, `.` nothing; also `openhat clap rim tom crash shaker sleigh`). Shape it with `swing: 0.16` (a lilt), `reverb`, a track's `vol: [[0, 0], [8, 0.7]]` (a fade-in over 8 beats), `tone` (darker when lower), `transpose`, and a slowing tempo `bpm: [[0, 96], [28, 96], [32, 60]]`. Use `loop: true` on the layer to repeat a short tune under a long video. A mistake prints a warning in the red box that names the track and the token. Keep 3 to 6 tracks, vary the bars, end on the home chord.
+
 ## Check your own work before you answer
 
 Read your file once for these: every layer has a `type`; every keyframe `at` is inside its layer's lifetime; text is anchored where you meant; layer `duration`s reach the end of their scene; colours have enough contrast; nothing important sits near the edges. A mistake in the data prints a warning in the red box; the person's paste is your test run.

package/ai/SKILL.md

@@ -33,7 +33,7 @@ You describe a video as a tree of plain objects; the library plays it in a canva
 - **Masks live in the parent's coordinates and don't follow the masked layer.** **`filterArea` is in the layer's own coordinates.**
 - **2.5D needs `threeD: true`** on each layer plus a `{ type: 'camera' }` layer; camera props go in `initial`/keyframes; keep every `z` below the camera distance (≈ 989 at 720p, fov 40); under a dolly zoom only `z = 0` stays fixed.
 - **Group / parent layers = `{ type: 'null', name: 'rig' }`** (draws nothing, only moves) + `parent: 'rig'` on the layers that should follow it: their `x`/`y` are then measured from the null's origin, and the null's position / rotation / scale / alpha carry them (orbits, clock hands, grouped fades). Nulls chain. Only `null` layers can be parents; not for `threeD` layers.
-- **Built in:** `animateText()` (per-letter / per-word / per-line entrances and exits in one call: `...animateText('Title', style, { x, y, align: 'center', at: 0.5, duration: 5, in: 'rise', out: 'fade', stagger: { each: 0.05 } })`), `splitText()` / `measureText()` (per-letter / per-word layers, exact positions, by hand), `shape: 'arc'` (progress rings, pie / donut slices: animate `endAngle`), `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`, seeded randomness (`rand(seed)` / `noise(x, seed)` in expressions, `random(seed)` in JS, never `Math.random()`) `wiggle()` (a seeded shake as keyframes) `audioEnvelope()` / `bpmEnvelope()` + `react()` (visuals that follow music: `const env = await audioEnvelope('music.mp3', { frameRate })` before `movie.init`, then `keyframes: react(env, { duration, props: { scale: { base: 1, amount: 0.4, band: 'bass', release: 0.2 } } })`; `beats: true` pulses on the beats; `bpmEnvelope(120, …)` when there is no file), `deck()` + `Presenter` (a talk as one movie: pages, steps, stops that pause playback, arrow keys / click / swipe to move on: `...deck({ transition: { kind: 'slide', duration: 0.6 }, pages: [{ name, duration, stops, sequences }] })`, `new Presenter(movie, { canvas })` from `pixi-effects/presenter`; G = page overview, P = presenter view with notes and a timer; `pixi-effects-render talk.html -o talk.pdf` = a PDF of the pages), `particles()` (bursts, snow, confetti, sparks as seeded layers: `...particles({ count: 90, at: 2, life: [1, 1.8], area: { x: 640, y: 330 }, speed: [120, 420], gravity: 240, fade: { out: 0.6 } })`), `followPath()` (a layer along an SVG path: `keyframes: followPath({ d, duration, orient: true })`), path morphing (`{ shape: 'path', d, morphTo, initial/keyframes: morph 0 → 1 }`) and `stagger()` (delays for a wave of layers: `stagger(letters, { each: 0.05, from: 'center' })`, or `stagger(n, …)` for numbers; GSAP-style `each` / `amount` / `from` / `grid` / `ease`). **Not in the DSL (hand-roll with a JS loop):** other per-frame curves (waves, spirals: sample them into short linear keyframes), shared masks. (Draw-on strokes `trimEnd`, text that changes over time `set: { text }` / `visibleChars`, shake `wiggle()` and particles are built in.)
+- **Built in:** `animateText()` (per-letter / per-word / per-line entrances and exits in one call: `...animateText('Title', style, { x, y, align: 'center', at: 0.5, duration: 5, in: 'rise', out: 'fade', stagger: { each: 0.05 } })`), `splitText()` / `measureText()` (per-letter / per-word layers, exact positions, by hand), `shape: 'arc'` (progress rings, pie / donut slices: animate `endAngle`), `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`, seeded randomness (`rand(seed)` / `noise(x, seed)` in expressions, `random(seed)` in JS, never `Math.random()`) `wiggle()` (a seeded shake as keyframes) `music` (a tune with no file: `{ type: 'audio', music: { bpm, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }, { inst: 'bass', notes: 'c2:2 g1:2' }], drums: { from: 8, kick: 'x...x...' } } }`: notes and chords as text, counted in beats; instruments `keys pluck pad bass sub lead bell musicbox`; `musicEnvelope(music)` feeds `react()`), `audioEnvelope()` / `bpmEnvelope()` + `react()` (visuals that follow music: `const env = await audioEnvelope('music.mp3', { frameRate })` before `movie.init`, then `keyframes: react(env, { duration, props: { scale: { base: 1, amount: 0.4, band: 'bass', release: 0.2 } } })`; `beats: true` pulses on the beats; `bpmEnvelope(120, …)` when there is no file), `deck()` + `Presenter` (a talk as one movie: pages, steps, stops that pause playback, arrow keys / click / swipe to move on: `...deck({ transition: { kind: 'slide', duration: 0.6 }, pages: [{ name, duration, stops, sequences }] })`, `new Presenter(movie, { canvas })` from `pixi-effects/presenter`; G = page overview, P = presenter view with notes and a timer; `pixi-effects-render talk.html -o talk.pdf` = a PDF of the pages), `particles()` (bursts, snow, confetti, sparks as seeded layers: `...particles({ count: 90, at: 2, life: [1, 1.8], area: { x: 640, y: 330 }, speed: [120, 420], gravity: 240, fade: { out: 0.6 } })`), `followPath()` (a layer along an SVG path: `keyframes: followPath({ d, duration, orient: true })`), path morphing (`{ shape: 'path', d, morphTo, initial/keyframes: morph 0 → 1 }`) and `stagger()` (delays for a wave of layers: `stagger(letters, { each: 0.05, from: 'center' })`, or `stagger(n, …)` for numbers; GSAP-style `each` / `amount` / `from` / `grid` / `ease`). **Not in the DSL (hand-roll with a JS loop):** other per-frame curves (waves, spirals: sample them into short linear keyframes), shared masks. (Draw-on strokes `trimEnd`, text that changes over time `set: { text }` / `visibleChars`, shake `wiggle()` and particles are built in.)
 - **Blend modes:** `blendMode: 'add' | 'screen' | 'multiply'` on any layer (glows, light leaks).
 - **One `Movie` per page.** A sound effect needs no `duration` (it lasts as long as its clip). Seeking is safe: counters, colours and growing shapes are right after any jump.
 

package/ai/chat-template.html

@@ -61,9 +61,9 @@
       "gsap":                    "https://cdn.jsdelivr.net/npm/gsap@3.12.5/+esm",
       "gsap/PixiPlugin":         "https://cdn.jsdelivr.net/npm/gsap@3.12.5/PixiPlugin/+esm",
       "mediabunny":              "https://cdn.jsdelivr.net/npm/mediabunny@1.61.3/+esm",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/Presenter.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Presenter.js"
     }
   }
   </script>

package/ai/reference/cheatsheet.md

@@ -56,6 +56,7 @@ Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate t
 
 **audio** — a file: `asset`, `loop`, `volume`; `volume` (top level, or in `initial` like every other layer's starting values); fade with volume keyframes (`{ at: -2, to: { volume: 0 }, duration: 2 }` fades the last 2 s). Omit `duration` for a one-shot clip: it lasts exactly as long as the clip. With `loop: true` and no `duration` it lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true`.
 **Or a sound effect with no file — `sfx`:** `{ type: 'audio', sfx: 'swoosh', at: 2 }` is the whole thing. Presets, default length in s: `click` 0.04 · `pop` 0.12 · `swoosh` 0.5 (loudest 0.16 s in, moves left → right) · `swipe` 0.22 · `hit` 0.7 · `riser` 1 (loudest at its END: `at = hit − duration`) · `chime` 1.4 · `beep` 0.16 · `coin` 0.4 · `glitch` 0.35 · `typewriter` 0.06. Knobs: `sfx: { preset, pitch /* semitones ±24 */, brightness /* −1 dark … 1 bright */, seed /* another take */ }`. **The layer's `duration` IS the sound's length** (omit it; set it to stretch, e.g. a riser); `volume` is its level (1 = the preset's standard level, peaking at −12 … −18 dBFS by preset). No `loop`: one layer per hit (a JS loop). Custom sound: `sfx: { voices: [{ wave: 'noise' | 'sine' | 'square' | 'saw' | 'triangle', freq: 440 | [from, to], filter: { type: 'lowpass' | 'highpass' | 'bandpass', freq: [from, to] }, envelope: 'fall' | 'bell' | 'swell' | 'hold', pan: [-1, 1] }] }`. The export (mp4 / webm / mov) encodes this same mix (lossy AAC / Opus), on time within a few ms.
+**Or music with no file — `music`:** `{ type: 'audio', music: { bpm: 96, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4 Dm7:4 G7:4' }, { inst: 'bass', notes: 'c2:2 g1:2 …' }], drums: { kick: 'x...x...', snare: '....x...', hat: 'x.x.x.x.' } } }` — a tune written as text (notes `c4:2` in beats, chords `Am7` `C@4` `Am7/e`, `[c4 e4 g4]`, rest `_`, hold `~`, `!` accent; `|` ignored). Instruments `keys pluck pad bass sub lead bell musicbox`; drums `kick snare hat openhat clap rim tom crash shaker sleigh` as 16th-note step strings (`x` hit, `o` soft, `.` none; a list of `{ from, to, … }` for sections). Score options `bpm` (or `[[beat, bpm], …]` for a ritardando) `swing reverb humanize drumVol grid transpose tail seed`; track options `vol` (or `[[beat, level], …]` for a fade) `pan step strum legato tone reverb attack release ring transpose`. Lasts its notes + tail, ends with the movie, `loop: true` repeats; peaks −6 dBFS at `volume: 1`. `await musicEnvelope(music, { frameRate })` → an envelope for `react()`; `await musicBuffer(music)` → a Web Audio `AudioBuffer` to play yourself.
 
 **shape** — `shape: 'rect' | 'circle' | 'ellipse' | 'arc' | 'line' | 'polygon' | 'path'`:
 
@@ -110,7 +111,7 @@ transitions: [{ kind: 'crossfade' | 'wipe' | 'iris' | 'slide' | 'dip' | 'zoom' |
 ## Presets
 
 ```js
-import { kenBurns, withFade, wiggle, stagger, followPath, particles, deck, audioEnvelope, bpmEnvelope, react, random } from 'pixi-effects';
+import { kenBurns, withFade, wiggle, stagger, followPath, particles, deck, audioEnvelope, bpmEnvelope, musicEnvelope, react, random } from 'pixi-effects';
 kenBurns({ asset, name, at, duration, motion: 'still'|'scale'|'rotation'|'position',
            fit: 'cover'|'contain', ease, /* scale */ origin, zoom, direction, /* rotation */ angle, /* position */ from, to })
 withFade(spec, { in: 0.5, out: 0.5 })   // alpha fade; `out` needs spec.duration

package/ai/reference/pitfalls.md

@@ -82,3 +82,9 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 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. A stop that lands a few frames before an animation ends shows it half-finished (also in the PDF): `movie.inspectStops()` / the check's review list names such stops; give an animation a little more time than its step (e.g. the next stop 0.3 s after it ends).
+58. **`music` counts BEATS, and every track has to add up.** A token's `:n` is beats (a quarter note), a 4/4 bar is 4: a bar of `c4:1 e4:1 g4:1` is a beat short and every later bar drifts. Keep all tracks the same length (the music lasts the longest; a track of rests `'_:16'` sets a length) and check the printed length with `movie.inspectAudio()`. 6/8 is a bar of 3 beats (dotted quarter `:1.5`, eighth `:0.5`) with `grid: 2`; `grid: 3` is triplet eighths in 4/4.
+59. **A groove that must enter late needs `from`, not a long string.** `drums: [{ kick: 'x...' }, { from: 8, snare: '....x...' }]`. Patterns repeat; a drum object is a loop of its longest string. A `crash` on the last bar: its own section `{ from: 28, crash: 'x' }`.
+60. **Build-ups are layers and `vol` points, not louder notes.** A track's `vol` can be `[[0, 0], [8, 0.7]]` (a fade over 8 beats); the pad's `attack` can be 2–3 s; enter instruments with rests. Per-note `!` and `,` only accent and soften.
+61. **Music is a bed: `volume` 0.5–0.8 under speech or sfx.** At `volume: 1` it peaks at −6 dBFS (an sfx peaks at −12). A layer shorter than the music cuts it with a fade; longer is silent after it unless `loop: true`. Do not also add an mp3 bed.
+62. **Chord names are voiced close around octave 3**: use `[c3 g3 e4]` for an exact voicing or `Am7/e` for a bass note; `swing` only moves notes that start on an off-beat eighth (`.5`) or sixteenth (`.75`); the bell and music box ring for `ring` seconds whatever the written length (shorten `ring` for fast bell lines); the synth is a handy bed, not an orchestra: keep tracks to 3–6, vary the bars, and end on the tonic.
+

package/ai/reference/recipes.md

@@ -280,6 +280,31 @@ Source images should be at least canvas-sized (`kenBurns` zooms in): draw genera
 
 ---
 
+## Music with no file (`music`)
+
+A tune written as text: tracks of notes and chords (`c4:2`, `Am7:4`, `_` rest), drum patterns, a tempo. Count the beats (a 4/4 bar is 4); keep every track the same length; give the drums `from` so they enter after the intro; fade a track in with `vol` points. It lasts its notes plus a reverb tail and ends with the movie; `loop: true` repeats it. The mix sits at −6 dBFS peak at `volume: 1`: use 0.5–0.8 under speech or sound effects.
+
+```js
+// @recipe music-lofi
+return [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1b1a2e' } },
+  { type: 'text', text: 'evening', at: 0.5, style: { fontFamily: 'Georgia, serif', fontSize: 96, fill: '#f3eee4' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+    keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 1.2 }] },
+  { type: 'audio', at: 0, volume: 0.8, music: {
+      bpm: 84, swing: 0.16, reverb: 0.26, seed: 7,
+      tracks: [
+        { inst: 'keys',  vol: 0.7, pan: -0.15, strum: 0.012, notes: 'Cmaj7:4 Am7:4 Dm7:4 G7:4 | Cmaj7:4 Am7:4 Dm7:2 G7:2 Cmaj7:4' },
+        { inst: 'bass',  vol: 0.85, notes: 'c2:1.5 _:0.5 g2:1 c2:1 | a1:1.5 _:0.5 e2:1 a1:1 | d2:1.5 _:0.5 a2:1 d2:1 | g1:1.5 _:0.5 d2:1 g1:1 | c2:1.5 _:0.5 g2:1 c2:1 | a1:1.5 _:0.5 e2:1 a1:1 | d2:2 f2:1 a1:1 | g1:2 b1:1 d2:1 | c2:4' },
+        { inst: 'pluck', vol: [[0, 0], [8, 0.55]], pan: 0.25, step: 0.5, notes: '_:8 | e5:1 d5:0.5 c5:0.5 e5:2 | c5:1 a4:1 e5:2 | f5:1 e5:0.5 d5:0.5 a4:2 | d5:1.5 b4:0.5 g4:2 | e5:1 g5:1 e5:1 d5:1 | c5:1 a4:1 c5:2 | d5:1 f5:1 e5:1 d5:1 | b4:2 d5:2 | c5:4' },
+        { inst: 'pad',   vol: 0.5, notes: '[c3 g3 e4]:8 [a2 e3 c4]:8 [d3 a3 f4]:8 [g2 d3 b3]:8' },
+      ],
+      drums: [{ from: 8, kick: 'x.......x.x.....', snare: '....x.......x...', hat: 'x.x.x.x.x.x.x.xo' }],
+  } },
+];
+```
+
+Other feels: a 6/8 lullaby is `bpm: 72`, `grid: 2`, bars of 3 beats (a dotted quarter `:1.5`, an eighth `:0.5`), instruments `musicbox` + `pluck` + `pad`; a build-up is layers entering with rests and `vol` points on the pad, drums from a later `from`; a ritardando is `bpm: [[0, 96], [28, 96], [32, 60]]`; a bright jingle is `lead` + `bell` + `sleigh` / `shaker` over a bouncy `bass`.
+
 ## Sound effects without files
 
 No `assets`, no files: a sound effect is one audio layer with `sfx`. It lasts as long as the sound.

package/ai/template.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>pixi-effects video</title>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/loader.css" />   <!-- the loader: HTML + CSS only, so it is on screen at once and keeps moving while the page builds the video -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/loader.css" />   <!-- the loader: HTML + CSS only, so it is on screen at once and keeps moving while the page builds the video -->
   <style>
     body { background: #0d1220; margin: 0; padding: 16px; }
     .stage { position: relative; width: min(960px, 100%); }                 /* the player and the loader both sit inside this box */
@@ -39,10 +39,10 @@
       "gsap":                    "https://esm.sh/gsap@3.12.5",
       "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
       "mediabunny":              "https://esm.sh/mediabunny",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/Presenter.js",
-      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.15.0/dist/three.js",
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Presenter.js",
+      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/three.js",
       "pixi-filters":            "https://esm.sh/pixi-filters@6.1.5?external=pixi.js",
       "three":                   "https://esm.sh/three@0.178.0"
     }

package/dist/{Base-CQOlB2VH.d.ts → Base-DPEqyeB0.d.cts}

@@ -1,5 +1,5 @@
 import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
-import { S as SequenceSpec, C as CompositionShape, O as AudioDescriptor } from './types-CBSiUKau.js';
+import { S as SequenceSpec, C as CompositionShape, a0 as AudioDescriptor } from './types-C8XEUoqe.cjs';
 import { gsap } from 'gsap';
 
 /**

package/dist/{Base-C6ZnJ9pD.d.cts → Base-qvqNxvyt.d.ts}

@@ -1,5 +1,5 @@
 import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
-import { S as SequenceSpec, C as CompositionShape, O as AudioDescriptor } from './types-CBSiUKau.cjs';
+import { S as SequenceSpec, C as CompositionShape, a0 as AudioDescriptor } from './types-C8XEUoqe.js';
 import { gsap } from 'gsap';
 
 /**

package/dist/Composition-X2VZSVPD.js

@@ -0,0 +1,5 @@
+export { CompositionSequence } from './chunk-I2YXLHIU.js';
+import './chunk-7D7RAQWM.js';
+import './chunk-DKGG7WD4.js';
+//# sourceMappingURL=Composition-X2VZSVPD.js.map
+//# sourceMappingURL=Composition-X2VZSVPD.js.map

package/dist/{Composition-HIISJAX2.js.map → Composition-X2VZSVPD.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-HIISJAX2.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-X2VZSVPD.js"}

package/dist/Composition-ZZGSMQ4E.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var chunkV54NBCWG_cjs = require('./chunk-V54NBCWG.cjs');
+require('./chunk-SPPNTV7E.cjs');
+require('./chunk-UQBGW5DO.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkV54NBCWG_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-ZZGSMQ4E.cjs.map
+//# sourceMappingURL=Composition-ZZGSMQ4E.cjs.map

package/dist/{Composition-7TEKHZNQ.cjs.map → Composition-ZZGSMQ4E.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-7TEKHZNQ.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-ZZGSMQ4E.cjs"}

package/dist/Controller.d.cts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-qmgOU4in.cjs';
+import { f as Movie } from './Movie-CJMfAizW.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-CBSiUKau.cjs';
+import './types-C8XEUoqe.cjs';
 
 /** The bar's default stylesheet. Its colours and sizes are CSS custom properties (`--mc-accent`, `--mc-fg`, `--mc-track`, `--mc-bar-bg`, `--mc-track-height`, `--mc-font`): set them in your page CSS, or with the `theme` option. */
 declare const CONTROLLER_CSS = "\n.movie-controller-wrap { position: relative; display: inline-block; line-height: 0; }\n.movie-controller {\n  position: absolute;\n  pointer-events: none;\n  font-family: var(--mc-font, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif);\n  display: flex;\n  flex-direction: column;\n  justify-content: flex-end;\n  opacity: 1;\n  transition: opacity 200ms ease;\n}\n.movie-controller[data-state=\"hidden\"] { opacity: 0; }\n.movie-controller > * { pointer-events: auto; }\n\n.mc-progress {\n  position: relative;\n  width: 100%;\n  height: 16px;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  outline: none;\n}\n.mc-progress:focus-visible {\n  outline: 2px solid var(--mc-accent, #007AFF);\n  outline-offset: 2px;\n}\n.mc-progress::before {\n  content: \"\"; position: absolute; left: 12px; right: 12px;\n  height: var(--mc-track-height, 3px); background: var(--mc-track, rgba(255,255,255,0.25));\n  transition: height 120ms ease;\n}\n.mc-progress:hover::before, .mc-progress.mc-scrubbing::before { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-stops { position: absolute; left: 12px; right: 12px; top: 0; bottom: 0; pointer-events: none; }\n.mc-stop-tick { position: absolute; top: 50%; width: 7px; height: 7px; transform: translate(-50%, -50%); border-radius: 50%; background: var(--mc-fg, #fff); box-shadow: 0 0 0 1.5px rgba(0,0,0,0.5); }\n.mc-stop-page { width: 11px; height: 11px; box-shadow: 0 0 0 2.5px var(--mc-accent, #007AFF), 0 0 0 4px rgba(0,0,0,0.35); }\n.mc-progress-fill {\n  position: absolute; left: 12px; top: 50%;\n  height: var(--mc-track-height, 3px);\n  width: calc((100% - 24px) * var(--mc-fill, 0));\n  background: var(--mc-accent, #007AFF);\n  transform: translateY(-50%);\n  transition: height 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-fill,\n.mc-progress.mc-scrubbing .mc-progress-fill { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-progress-thumb {\n  position: absolute; top: 50%;\n  left: calc(12px + (100% - 24px) * var(--mc-fill, 0));\n  width: 12px; height: 12px; border-radius: 50%;\n  background: var(--mc-accent, #007AFF);\n  transform: translate(-50%, -50%) scale(0);\n  transition: transform 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-thumb,\n.mc-progress.mc-scrubbing .mc-progress-thumb { transform: translate(-50%, -50%) scale(1); }\n\n.mc-bar {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 6px 12px 8px 12px;\n  background: var(--mc-bar-bg, linear-gradient(to top, rgba(0,0,0,0.75) 0%, rgba(0,0,0,0) 100%));\n  color: var(--mc-fg, #fff);\n  line-height: 1;\n}\n.mc-btn {\n  background: none; border: 0; padding: 0; margin: 0;\n  width: 28px; height: 28px;\n  display: inline-flex; align-items: center; justify-content: center;\n  color: var(--mc-fg, #fff); opacity: 0.85; cursor: pointer;\n  transition: opacity 120ms ease;\n}\n.mc-btn:hover { opacity: 1; }\n.mc-btn:disabled { opacity: 0.4; cursor: not-allowed; }\n.mc-time {\n  font-size: 12px; font-family: Menlo, Monaco, monospace;\n  color: var(--mc-fg, #fff); opacity: 0.85;\n  min-width: 90px;\n}\n.mc-spacer { flex: 1; }\n\n.mc-volume { display: flex; align-items: center; }\n.mc-vol-slider {\n  position: relative;\n  width: 0;\n  height: 28px;\n  display: flex;\n  align-items: center;\n  cursor: pointer;\n  margin-left: 0;\n  outline: none;\n  transition: width 200ms ease, margin-left 200ms ease;\n  overflow: hidden;\n}\n.mc-volume:hover .mc-vol-slider,\n.mc-volume:focus-within .mc-vol-slider,\n.mc-vol-slider.mc-scrubbing {\n  width: 70px;\n  margin-left: 6px;\n}\n.mc-vol-slider:focus-visible { outline: 2px solid var(--mc-accent, #007AFF); outline-offset: 2px; }\n.mc-vol-slider::before {\n  content: \"\"; position: absolute; left: 4px; right: 4px;\n  height: 3px; background: var(--mc-track, rgba(255,255,255,0.25)); border-radius: 2px;\n}\n.mc-vol-fill {\n  position: absolute; left: 4px; top: 50%;\n  height: 3px;\n  width: calc((100% - 8px) * var(--mc-volume, 1));\n  background: var(--mc-fg, #fff);\n  transform: translateY(-50%);\n  border-radius: 2px;\n  pointer-events: none;\n}\n.mc-vol-thumb {\n  position: absolute; top: 50%;\n  left: calc(4px + (100% - 8px) * var(--mc-volume, 1));\n  width: 10px; height: 10px; border-radius: 50%;\n  background: var(--mc-fg, #fff);\n  transform: translate(-50%, -50%);\n  pointer-events: none;\n}\n\n[data-mc-wrap]:fullscreen {\n  width: 100vw; height: 100vh;\n  display: flex; align-items: center; justify-content: center;\n  background: #000;\n}\n[data-mc-wrap]:fullscreen > canvas {\n  width: 100% !important;\n  height: 100% !important;\n  max-width: none !important;\n  max-height: none !important;\n  object-fit: contain;\n  border-radius: 0;\n}\n\n.mc-settings-popover {\n  position: absolute;\n  bottom: calc(100% + 8px);\n  right: 12px;\n  background: rgba(20, 20, 20, 0.96);\n  border-radius: 8px;\n  padding: 10px 12px;\n  min-width: 180px;\n  color: #fff;\n  font-size: 12px;\n  box-shadow: 0 4px 16px rgba(0,0,0,0.4);\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n.mc-settings-popover[data-open=\"false\"] { display: none; }\n.mc-settings-row {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: 12px;\n}\n.mc-settings-row > span { color: rgba(255,255,255,0.85); }\n.mc-settings-row > select {\n  font: inherit;\n  background: rgba(255,255,255,0.1);\n  color: #fff;\n  border: 1px solid rgba(255,255,255,0.18);\n  border-radius: 4px;\n  padding: 2px 6px;\n  cursor: pointer;\n}\n.mc-export-confirm {\n  margin-top: 4px;\n  width: 100%;\n  background: var(--mc-accent, #007AFF);\n  color: #fff;\n  border: 0;\n  border-radius: 4px;\n  padding: 6px 10px;\n  font: inherit;\n  font-weight: 600;\n  cursor: pointer;\n  transition: background 120ms ease;\n}\n.mc-export-confirm:hover { background: #0066d6; }\n.mc-export-confirm:disabled { background: rgba(255,255,255,0.18); cursor: not-allowed; }\n\n.mc-export-overlay {\n  position: absolute; inset: 0;\n  background: rgba(0,0,0,0.7);\n  display: flex; justify-content: center; align-items: center;\n  z-index: 2;\n}\n.mc-export-panel {\n  background: rgba(20,20,20,0.96); color: #fff;\n  border-radius: 8px; padding: 16px 20px;\n  text-align: center; min-width: 200px; max-width: 80%;\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n}\n.mc-export-title { font-size: 13px; margin-bottom: 10px; opacity: 0.9; }\n.mc-export-track {\n  width: 100%; height: 6px;\n  background: rgba(255,255,255,0.15); border-radius: 3px;\n  margin-bottom: 8px; overflow: hidden;\n}\n.mc-export-fill {\n  height: 100%; width: 0%;\n  background: linear-gradient(90deg, var(--mc-accent, #007AFF), var(--mc-accent, #0056CC));\n  transition: width 0.3s ease; border-radius: 3px;\n}\n.mc-export-text {\n  color: rgba(255,255,255,0.7); font-size: 11px;\n  font-family: Menlo, Monaco, monospace;\n}\n";

package/dist/Controller.d.ts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-BwT6XtGz.js';
+import { f as Movie } from './Movie-BIGDIla0.js';
 import 'pixi.js';
 import 'gsap';
-import './types-CBSiUKau.js';
+import './types-C8XEUoqe.js';
 
 /** The bar's default stylesheet. Its colours and sizes are CSS custom properties (`--mc-accent`, `--mc-fg`, `--mc-track`, `--mc-bar-bg`, `--mc-track-height`, `--mc-font`): set them in your page CSS, or with the `theme` option. */
 declare const CONTROLLER_CSS = "\n.movie-controller-wrap { position: relative; display: inline-block; line-height: 0; }\n.movie-controller {\n  position: absolute;\n  pointer-events: none;\n  font-family: var(--mc-font, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif);\n  display: flex;\n  flex-direction: column;\n  justify-content: flex-end;\n  opacity: 1;\n  transition: opacity 200ms ease;\n}\n.movie-controller[data-state=\"hidden\"] { opacity: 0; }\n.movie-controller > * { pointer-events: auto; }\n\n.mc-progress {\n  position: relative;\n  width: 100%;\n  height: 16px;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  outline: none;\n}\n.mc-progress:focus-visible {\n  outline: 2px solid var(--mc-accent, #007AFF);\n  outline-offset: 2px;\n}\n.mc-progress::before {\n  content: \"\"; position: absolute; left: 12px; right: 12px;\n  height: var(--mc-track-height, 3px); background: var(--mc-track, rgba(255,255,255,0.25));\n  transition: height 120ms ease;\n}\n.mc-progress:hover::before, .mc-progress.mc-scrubbing::before { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-stops { position: absolute; left: 12px; right: 12px; top: 0; bottom: 0; pointer-events: none; }\n.mc-stop-tick { position: absolute; top: 50%; width: 7px; height: 7px; transform: translate(-50%, -50%); border-radius: 50%; background: var(--mc-fg, #fff); box-shadow: 0 0 0 1.5px rgba(0,0,0,0.5); }\n.mc-stop-page { width: 11px; height: 11px; box-shadow: 0 0 0 2.5px var(--mc-accent, #007AFF), 0 0 0 4px rgba(0,0,0,0.35); }\n.mc-progress-fill {\n  position: absolute; left: 12px; top: 50%;\n  height: var(--mc-track-height, 3px);\n  width: calc((100% - 24px) * var(--mc-fill, 0));\n  background: var(--mc-accent, #007AFF);\n  transform: translateY(-50%);\n  transition: height 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-fill,\n.mc-progress.mc-scrubbing .mc-progress-fill { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-progress-thumb {\n  position: absolute; top: 50%;\n  left: calc(12px + (100% - 24px) * var(--mc-fill, 0));\n  width: 12px; height: 12px; border-radius: 50%;\n  background: var(--mc-accent, #007AFF);\n  transform: translate(-50%, -50%) scale(0);\n  transition: transform 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-thumb,\n.mc-progress.mc-scrubbing .mc-progress-thumb { transform: translate(-50%, -50%) scale(1); }\n\n.mc-bar {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 6px 12px 8px 12px;\n  background: var(--mc-bar-bg, linear-gradient(to top, rgba(0,0,0,0.75) 0%, rgba(0,0,0,0) 100%));\n  color: var(--mc-fg, #fff);\n  line-height: 1;\n}\n.mc-btn {\n  background: none; border: 0; padding: 0; margin: 0;\n  width: 28px; height: 28px;\n  display: inline-flex; align-items: center; justify-content: center;\n  color: var(--mc-fg, #fff); opacity: 0.85; cursor: pointer;\n  transition: opacity 120ms ease;\n}\n.mc-btn:hover { opacity: 1; }\n.mc-btn:disabled { opacity: 0.4; cursor: not-allowed; }\n.mc-time {\n  font-size: 12px; font-family: Menlo, Monaco, monospace;\n  color: var(--mc-fg, #fff); opacity: 0.85;\n  min-width: 90px;\n}\n.mc-spacer { flex: 1; }\n\n.mc-volume { display: flex; align-items: center; }\n.mc-vol-slider {\n  position: relative;\n  width: 0;\n  height: 28px;\n  display: flex;\n  align-items: center;\n  cursor: pointer;\n  margin-left: 0;\n  outline: none;\n  transition: width 200ms ease, margin-left 200ms ease;\n  overflow: hidden;\n}\n.mc-volume:hover .mc-vol-slider,\n.mc-volume:focus-within .mc-vol-slider,\n.mc-vol-slider.mc-scrubbing {\n  width: 70px;\n  margin-left: 6px;\n}\n.mc-vol-slider:focus-visible { outline: 2px solid var(--mc-accent, #007AFF); outline-offset: 2px; }\n.mc-vol-slider::before {\n  content: \"\"; position: absolute; left: 4px; right: 4px;\n  height: 3px; background: var(--mc-track, rgba(255,255,255,0.25)); border-radius: 2px;\n}\n.mc-vol-fill {\n  position: absolute; left: 4px; top: 50%;\n  height: 3px;\n  width: calc((100% - 8px) * var(--mc-volume, 1));\n  background: var(--mc-fg, #fff);\n  transform: translateY(-50%);\n  border-radius: 2px;\n  pointer-events: none;\n}\n.mc-vol-thumb {\n  position: absolute; top: 50%;\n  left: calc(4px + (100% - 8px) * var(--mc-volume, 1));\n  width: 10px; height: 10px; border-radius: 50%;\n  background: var(--mc-fg, #fff);\n  transform: translate(-50%, -50%);\n  pointer-events: none;\n}\n\n[data-mc-wrap]:fullscreen {\n  width: 100vw; height: 100vh;\n  display: flex; align-items: center; justify-content: center;\n  background: #000;\n}\n[data-mc-wrap]:fullscreen > canvas {\n  width: 100% !important;\n  height: 100% !important;\n  max-width: none !important;\n  max-height: none !important;\n  object-fit: contain;\n  border-radius: 0;\n}\n\n.mc-settings-popover {\n  position: absolute;\n  bottom: calc(100% + 8px);\n  right: 12px;\n  background: rgba(20, 20, 20, 0.96);\n  border-radius: 8px;\n  padding: 10px 12px;\n  min-width: 180px;\n  color: #fff;\n  font-size: 12px;\n  box-shadow: 0 4px 16px rgba(0,0,0,0.4);\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n.mc-settings-popover[data-open=\"false\"] { display: none; }\n.mc-settings-row {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: 12px;\n}\n.mc-settings-row > span { color: rgba(255,255,255,0.85); }\n.mc-settings-row > select {\n  font: inherit;\n  background: rgba(255,255,255,0.1);\n  color: #fff;\n  border: 1px solid rgba(255,255,255,0.18);\n  border-radius: 4px;\n  padding: 2px 6px;\n  cursor: pointer;\n}\n.mc-export-confirm {\n  margin-top: 4px;\n  width: 100%;\n  background: var(--mc-accent, #007AFF);\n  color: #fff;\n  border: 0;\n  border-radius: 4px;\n  padding: 6px 10px;\n  font: inherit;\n  font-weight: 600;\n  cursor: pointer;\n  transition: background 120ms ease;\n}\n.mc-export-confirm:hover { background: #0066d6; }\n.mc-export-confirm:disabled { background: rgba(255,255,255,0.18); cursor: not-allowed; }\n\n.mc-export-overlay {\n  position: absolute; inset: 0;\n  background: rgba(0,0,0,0.7);\n  display: flex; justify-content: center; align-items: center;\n  z-index: 2;\n}\n.mc-export-panel {\n  background: rgba(20,20,20,0.96); color: #fff;\n  border-radius: 8px; padding: 16px 20px;\n  text-align: center; min-width: 200px; max-width: 80%;\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n}\n.mc-export-title { font-size: 13px; margin-bottom: 10px; opacity: 0.9; }\n.mc-export-track {\n  width: 100%; height: 6px;\n  background: rgba(255,255,255,0.15); border-radius: 3px;\n  margin-bottom: 8px; overflow: hidden;\n}\n.mc-export-fill {\n  height: 100%; width: 0%;\n  background: linear-gradient(90deg, var(--mc-accent, #007AFF), var(--mc-accent, #0056CC));\n  transition: width 0.3s ease; border-radius: 3px;\n}\n.mc-export-text {\n  color: rgba(255,255,255,0.7); font-size: 11px;\n  font-family: Menlo, Monaco, monospace;\n}\n";

package/dist/{Movie-BwT6XtGz.d.ts → Movie-BIGDIla0.d.ts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { z as Stop, e as AssetSpec, c as CompositionSpec } from './types-CBSiUKau.js';
+import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-C8XEUoqe.js';
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */

package/dist/{Movie-qmgOU4in.d.cts → Movie-CJMfAizW.d.cts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { z as Stop, e as AssetSpec, c as CompositionSpec } from './types-CBSiUKau.cjs';
+import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-C8XEUoqe.cjs';
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */

package/dist/Presenter.d.cts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-qmgOU4in.cjs';
+import { f as Movie } from './Movie-CJMfAizW.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-CBSiUKau.cjs';
+import './types-C8XEUoqe.cjs';
 
 interface PresenterOptions {
     canvas: HTMLCanvasElement;

package/dist/Presenter.d.ts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-BwT6XtGz.js';
+import { f as Movie } from './Movie-BIGDIla0.js';
 import 'pixi.js';
 import 'gsap';
-import './types-CBSiUKau.js';
+import './types-C8XEUoqe.js';
 
 interface PresenterOptions {
     canvas: HTMLCanvasElement;

package/dist/{chunk-C6QHKYC5.js → chunk-7D7RAQWM.js}

@@ -1020,7 +1020,7 @@ function lintTiming(spec, parentDuration, warn = defaultWarn) {
   if (at >= parentDuration) {
     warn(`pixi-effects: ${who} starts at ${at}s, after its composition ends (${parentDuration}s), so it is never visible`);
   }
-  if (spec.type === "audio" && spec.sfx !== void 0 && spec.duration === void 0) return;
+  if (spec.type === "audio" && (spec.sfx !== void 0 || spec.music !== void 0) && spec.duration === void 0) return;
   const duration = spec.duration ?? parentDuration;
   (spec.keyframes ?? []).forEach((kf, i) => {
     const kat = kf.at ?? 0;
@@ -1723,6 +1723,7 @@ var AudioSequence = class extends Sequence {
   _source = "";
   async build() {
     this.target = null;
+    if (this.spec.music !== void 0) return this._buildMusic(this.spec);
     if (this.spec.sfx !== void 0) return this._buildSfx(this.spec);
     const spec = this.spec;
     this._source = `asset "${spec.asset}"`;
@@ -1757,6 +1758,30 @@ var AudioSequence = class extends Sequence {
       }
     });
   }
+  async _buildMusic(spec) {
+    const who = describeLayer(spec);
+    const raw = spec;
+    if (raw.asset !== void 0) console.warn(`pixi-effects: ${who}: has both asset and music \u2014 the music plays; remove one`);
+    if (raw.sfx !== void 0) console.warn(`pixi-effects: ${who}: has both sfx and music \u2014 the music plays; remove one`);
+    const { resolveMusic, renderMusic, musicLength, musicKey } = await import('./music-4HDFULNR.js');
+    const music = resolveMusic(spec.music, who);
+    if (!music) return;
+    const natural = musicLength(music);
+    const rest = Math.max(0, (this.parent?.duration ?? this.root.duration) - this.at);
+    let length = natural;
+    if (spec.duration !== void 0) {
+      if (typeof spec.duration === "number" && Number.isFinite(spec.duration) && spec.duration > 0) length = spec.duration;
+      else console.warn(`pixi-effects: ${who}: duration must be a positive number of seconds (got ${JSON.stringify(spec.duration)}); using the music's own length, ${natural.toFixed(1)}s`);
+    } else if (spec.loop) length = rest || natural;
+    else if (rest > 0) length = Math.min(natural, rest);
+    if (!spec.loop && spec.duration !== void 0 && length > natural + 0.05) {
+      console.warn(`pixi-effects: ${who}: the music is ${natural.toFixed(1)}s (with its tail) but the layer lasts ${length.toFixed(1)}s, so it goes silent after ${natural.toFixed(1)}s. Add loop: true, or shorten the layer's duration.`);
+    }
+    this.duration = length;
+    const loop = !!spec.loop;
+    this._source = "music";
+    this._synth = { key: musicKey(music, length, loop), render: (sr) => renderMusic(music, sr, length, loop) };
+  }
   bindTimeline(_timeline) {
   }
   collectAudio(out, baseTime) {
@@ -2691,7 +2716,7 @@ function numOrZero(v, scope) {
 var _CompositionSequence = null;
 async function getCompositionSequence() {
   if (!_CompositionSequence) {
-    _CompositionSequence = (await import('./Composition-HIISJAX2.js')).CompositionSequence;
+    _CompositionSequence = (await import('./Composition-X2VZSVPD.js')).CompositionSequence;
   }
   return _CompositionSequence;
 }
@@ -2730,5 +2755,5 @@ async function buildSequenceTree(specs, parent, root) {
 }
 
 export { CameraSequence, DEFAULT_FOV, DEG, NEAR, NullSequence, Sequence, buildScope, buildSequenceTree, cameraBasis, collectPropKeys, describeLayer, ensureFilterLibrary, evaluateExpr, flattenSvgPath, homeCamera, homeDistance, lintText, lintTiming, noise, projectLayer, rand, random, registerSequenceType, resolveAt, summarizeWarnings };
-//# sourceMappingURL=chunk-C6QHKYC5.js.map
-//# sourceMappingURL=chunk-C6QHKYC5.js.map
+//# sourceMappingURL=chunk-7D7RAQWM.js.map
+//# sourceMappingURL=chunk-7D7RAQWM.js.map