pixi-effects 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, M as Movie, d as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, e as SoundMeasure } from './Movie-CADDBfpl.cjs';
-import { S as Sequence } from './Base-4vNLl4tH.cjs';
-import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, b as SequenceCommon } from './types-DrW9QeKU.cjs';
-export { A as ArcShapeSpec, c as AssetSpec, d as AudioAssetSpec, e as AudioSequenceSpec, f as AudioSfxSpec, g as ChromaKeyFilterSpec, h as CircleShapeSpec, i as CompositionSequenceSpec, j as CompositionSpec, k as CrossfadeTransition, l as CustomFilterSpec, D as DipTransition, m as DissolveTransition, E as EllipseShapeSpec, n as Expr, F as FilterSpec, G as GradientSpec, o as IrisTransition, K as Keyframe, L as LineShapeSpec, P as PathShapeSpec, p as PolygonShapeSpec, q as PropValue, r as Props, R as RectShapeSpec, s as SfxKnobs, t as SfxOptions, u as SfxPreset, v as SfxVoice, w as ShapeSequenceSpec, x as SlideTransition, T as TextSequenceSpec, y as TransitionCommon, z as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-DrW9QeKU.cjs';
+export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, M as Movie, d as MovieErrorEvent, e as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, f as SoundMeasure, T as TimelineData, g as TimelineHtmlOptions, h as TimelineRow, i as TimelineSvgOptions, j as TimelineTransition, V as VolumeEvent } from './Movie-CQOhUmko.cjs';
+import { S as Sequence } from './Base-CSIulyIq.cjs';
+import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, b as SequenceCommon } from './types-oJijbn-K.cjs';
+export { A as ArcShapeSpec, c as AssetSpec, d as AudioAssetSpec, e as AudioSequenceSpec, f as AudioSfxSpec, g as ChromaKeyFilterSpec, h as CircleShapeSpec, i as CompositionSequenceSpec, j as CompositionSpec, k as CrossfadeTransition, l as CustomFilterSpec, D as DipTransition, m as DissolveTransition, E as EllipseShapeSpec, n as Expr, F as FilterSpec, G as GradientSpec, o as IrisTransition, K as Keyframe, L as LineShapeSpec, P as PathShapeSpec, p as PolygonShapeSpec, q as PropValue, r as Props, R as RectShapeSpec, s as SfxKnobs, t as SfxOptions, u as SfxPreset, v as SfxVoice, w as ShapeSequenceSpec, x as SlideTransition, T as TextSequenceSpec, y as TransitionCommon, z as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-oJijbn-K.cjs';
 import 'pixi.js';
 import 'gsap';
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, M as Movie, d as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, e as SoundMeasure } from './Movie-Ch2SUI1h.js';
-import { S as Sequence } from './Base-CD4AoT5-.js';
-import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, b as SequenceCommon } from './types-DrW9QeKU.js';
-export { A as ArcShapeSpec, c as AssetSpec, d as AudioAssetSpec, e as AudioSequenceSpec, f as AudioSfxSpec, g as ChromaKeyFilterSpec, h as CircleShapeSpec, i as CompositionSequenceSpec, j as CompositionSpec, k as CrossfadeTransition, l as CustomFilterSpec, D as DipTransition, m as DissolveTransition, E as EllipseShapeSpec, n as Expr, F as FilterSpec, G as GradientSpec, o as IrisTransition, K as Keyframe, L as LineShapeSpec, P as PathShapeSpec, p as PolygonShapeSpec, q as PropValue, r as Props, R as RectShapeSpec, s as SfxKnobs, t as SfxOptions, u as SfxPreset, v as SfxVoice, w as ShapeSequenceSpec, x as SlideTransition, T as TextSequenceSpec, y as TransitionCommon, z as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-DrW9QeKU.js';
+export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, M as Movie, d as MovieErrorEvent, e as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, f as SoundMeasure, T as TimelineData, g as TimelineHtmlOptions, h as TimelineRow, i as TimelineSvgOptions, j as TimelineTransition, V as VolumeEvent } from './Movie-HF3pSGjQ.js';
+import { S as Sequence } from './Base-DVgwyIUj.js';
+import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, b as SequenceCommon } from './types-oJijbn-K.js';
+export { A as ArcShapeSpec, c as AssetSpec, d as AudioAssetSpec, e as AudioSequenceSpec, f as AudioSfxSpec, g as ChromaKeyFilterSpec, h as CircleShapeSpec, i as CompositionSequenceSpec, j as CompositionSpec, k as CrossfadeTransition, l as CustomFilterSpec, D as DipTransition, m as DissolveTransition, E as EllipseShapeSpec, n as Expr, F as FilterSpec, G as GradientSpec, o as IrisTransition, K as Keyframe, L as LineShapeSpec, P as PathShapeSpec, p as PolygonShapeSpec, q as PropValue, r as Props, R as RectShapeSpec, s as SfxKnobs, t as SfxOptions, u as SfxPreset, v as SfxVoice, w as ShapeSequenceSpec, x as SlideTransition, T as TextSequenceSpec, y as TransitionCommon, z as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-oJijbn-K.js';
 import 'pixi.js';
 import 'gsap';
 

package/dist/index.js

@@ -1,12 +1,12 @@
+import { CompositionSequence } from './chunk-O4AJYUPK.js';
+import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, DEG, resolveAt, collectPropKeys } from './chunk-FNKSXBKB.js';
+export { registerSequenceType } from './chunk-FNKSXBKB.js';
 import { warnUnknownOptions, suggestName } from './chunk-DKGG7WD4.js';
-import { CompositionSequence } from './chunk-B2FTJLNB.js';
-import { homeDistance, DEFAULT_FOV, DEG, resolveAt, collectPropKeys } from './chunk-7IJHJXDI.js';
-export { registerSequenceType } from './chunk-7IJHJXDI.js';
 import * as PIXI from 'pixi.js';
 import { extensions, CullerPlugin, Application, Container, Rectangle, Culler, CanvasTextMetrics, TextStyle, Assets, ExtensionType, Filter, UniformGroup, GpuProgram, GlProgram, defaultFilterVert } from 'pixi.js';
 import { gsap } from 'gsap';
 import { PixiPlugin } from 'gsap/PixiPlugin';
-import { QUALITY_VERY_HIGH, QUALITY_HIGH, QUALITY_MEDIUM, QUALITY_LOW, QUALITY_VERY_LOW, Output, BufferTarget, CanvasSource, AudioBufferSource, Input, ALL_FORMATS, BlobSource, WavOutputFormat, Conversion, VideoSampleSink, MkvOutputFormat, WebMOutputFormat, MovOutputFormat, Mp4OutputFormat } from 'mediabunny';
+import { QUALITY_VERY_HIGH, QUALITY_HIGH, QUALITY_MEDIUM, QUALITY_LOW, QUALITY_VERY_LOW, Output, BufferTarget, CanvasSource, AudioBufferSource, Input, ALL_FORMATS, BlobSource, WavOutputFormat, Conversion, VideoSampleSink, MkvOutputFormat, WebMOutputFormat, MovOutputFormat, Mp4OutputFormat, getFirstEncodableAudioCodec } from 'mediabunny';
 
 var registered = false;
 function ensureLoadersRegistered(audioContext) {
@@ -161,7 +161,7 @@ function fft(re, im) {
 }
 var FRAME = 2048;
 function spectralCentroid(samples, sampleRate, from = 0, to = samples.length) {
-  let num = 0;
+  let num2 = 0;
   let den = 0;
   const re = new Float64Array(FRAME);
   const im = new Float64Array(FRAME);
@@ -176,11 +176,11 @@ function spectralCentroid(samples, sampleRate, from = 0, to = samples.length) {
     fft(re, im);
     for (let b = 1; b < FRAME / 2; b++) {
       const power = re[b] * re[b] + im[b] * im[b];
-      num += power * (b * sampleRate / FRAME);
+      num2 += power * (b * sampleRate / FRAME);
       den += power;
     }
   }
-  return den > 1e-9 ? Math.round(num / den / 10) * 10 : 0;
+  return den > 1e-9 ? Math.round(num2 / den / 10) * 10 : 0;
 }
 
 // src/core/inspectAudio.ts
@@ -288,6 +288,28 @@ var AUDIO_CODEC_BY_FORMAT = {
   webm: "opus",
   mkv: "opus"
 };
+var AUDIO_PREFERENCE = {
+  mp4: ["aac", "opus", "mp3", "flac"],
+  mov: ["aac", "mp3"],
+  webm: ["opus", "vorbis"],
+  mkv: ["opus", "vorbis", "aac", "flac", "mp3"]
+};
+async function chooseAudioCodec(fmt, requested, container, audio, bitrate) {
+  const supported = container.getSupportedAudioCodecs?.();
+  const preferred = AUDIO_PREFERENCE[fmt].filter((c) => !supported || supported.includes(c));
+  const canEncode = (list) => getFirstEncodableAudioCodec(list, { numberOfChannels: audio.numberOfChannels ?? 2, sampleRate: audio.sampleRate, bitrate });
+  if (requested) {
+    if (await canEncode([requested])) return requested;
+    const alt = await canEncode(preferred.filter((c) => c !== requested));
+    throw new Error(`pixi-effects: this browser cannot encode "${requested}" audio for ${fmt}` + (alt ? `; "${alt}" would work: render({ format: '${fmt}', audio: { codec: '${alt}' } }), or leave audio.codec out and the best one is chosen.` : "; it has no audio encoder for this format at all (try another browser, or a movie without sound)."));
+  }
+  const chosen = await canEncode(preferred);
+  if (!chosen) throw new Error(`pixi-effects: this browser has no audio encoder for ${fmt} (it tried ${preferred.join(", ")}): try another browser, or render a movie without sound.`);
+  if (chosen !== preferred[0]) {
+    console.warn(`pixi-effects: this browser cannot encode ${preferred[0].toUpperCase()} audio (Chrome on Linux has no AAC encoder), so the ${fmt} carries ${chosen} instead; current players play it. A webm export needs no AAC.`);
+  }
+  return chosen;
+}
 var qualityMap = {
   "very-low": QUALITY_VERY_LOW,
   "low": QUALITY_LOW,
@@ -320,8 +342,10 @@ async function exportFrames(movie, options = {}) {
       bitrate: qualityMap[options.audio?.bitrate ?? "high"] ?? QUALITY_HIGH
     }
   };
+  const container = makeOutputFormat(opts.format);
+  if (movie.audioBuffer) opts.audio.codec = await chooseAudioCodec(fmt, options.audio?.codec, container, movie.audioBuffer, opts.audio.bitrate);
   const output = new Output({
-    format: makeOutputFormat(opts.format),
+    format: container,
     target: new BufferTarget()
   });
   const canvasSource = new CanvasSource(movie.app.canvas, {
@@ -1120,7 +1144,7 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
   const seen = /* @__PURE__ */ new Map();
   const scene = /* @__PURE__ */ new Map();
   const scaledToNothing = /* @__PURE__ */ new Set();
-  const walk = (comp, prefix, insideThreeD, parentVisible, parentScene, parentMoving = false, parentZero = false) => {
+  const walk2 = (comp, prefix, insideThreeD, parentVisible, parentScene, parentMoving = false, parentZero = false) => {
     const blending = /* @__PURE__ */ new Set();
     for (const w of transitionWindowsOf(comp.spec)) {
       const start = (comp.absoluteStart ?? 0) + w.start, end = (comp.absoluteStart ?? 0) + w.end;
@@ -1164,10 +1188,10 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
       const group = parentScene ?? (name !== void 0 && blending.has(name) ? name : void 0);
       if (group) scene.set(info, group);
       if (zero || seq.showsNothingYet) scaledToNothing.add(info);
-      if (seq instanceof CompositionSequence) walk(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
+      if (seq instanceof CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
     });
   };
-  walk(root, "", false, true);
+  walk2(root, "", false, true);
   const issues = [];
   const texts = layers.filter((l) => l.type === "text" && l.visible && l.alpha >= FAINT && l.bounds);
   for (const l of texts) {
@@ -1204,6 +1228,158 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
   return { frame, time, canvas, summary: { layers: layers.length, visible: layers.filter((l) => l.visible).length }, issues, layers: listed };
 }
 
+// src/core/timelineChart.ts
+var GROUP_MIN = 4;
+var MAX_KEYS = 200;
+var round = (n) => Math.round(n * 1e6) / 1e6;
+var family = (name) => name.replace(/\d+/g, "#");
+function detailOf(seq) {
+  const s = seq.spec;
+  if (typeof s.text === "string") return s.text.length > 60 ? s.text.slice(0, 57) + "\u2026" : s.text;
+  if (typeof s.asset === "string") return `asset \u201C${s.asset}\u201D`;
+  if (typeof s.sfx === "string") return `sfx \u201C${s.sfx}\u201D`;
+  if (s.sfx && typeof s.sfx === "object") return "sfx (custom)";
+  return void 0;
+}
+function walk(comp, parentStart, parentEnd, depth, prefix, rows, transitions) {
+  const entries = [];
+  comp._children.forEach((seq, i) => {
+    const name = seq.spec.name ?? `${seq.spec.type}#${i}`;
+    const start = parentStart + (seq.at ?? 0);
+    const end = Math.min(parentEnd, seq.duration !== void 0 ? start + seq.duration : parentEnd);
+    const span = end - start;
+    const keys = (seq.spec.keyframes ?? []).map((kf) => round(start + resolveAt(kf.at, span))).sort((a, b) => a - b).slice(0, MAX_KEYS);
+    const row = { path: prefix + name, name, type: seq.spec.type, depth, start: round(start), end: round(end), keys, detail: detailOf(seq) };
+    const inner = [];
+    const isComp = seq instanceof CompositionSequence;
+    if (isComp) walk(seq, start, end, depth + 1, prefix + name + "/", inner, transitions);
+    entries.push({ row, inner, groupable: !isComp });
+  });
+  rows.push(...groupFamilies(entries));
+  for (const w of transitionWindowsOf(comp.spec)) {
+    transitions.push({ from: prefix + w.from, to: prefix + w.to, start: round(parentStart + w.start), end: round(parentStart + w.end) });
+  }
+}
+function groupFamilies(entries) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (!e.groupable) continue;
+    const key = e.row.type + "|" + family(e.row.name);
+    (buckets.get(key) ?? buckets.set(key, []).get(key)).push(e.row);
+  }
+  const out = [];
+  const done = /* @__PURE__ */ new Set();
+  for (const e of entries) {
+    const key = e.row.type + "|" + family(e.row.name);
+    const members = e.groupable ? buckets.get(key) : null;
+    if (members && members.length >= GROUP_MIN) {
+      if (done.has(key)) continue;
+      done.add(key);
+      const label = `${family(e.row.name)} \xD7${members.length}`;
+      out.push({
+        path: e.row.path.slice(0, e.row.path.length - e.row.name.length) + label,
+        name: label,
+        type: e.row.type,
+        depth: e.row.depth,
+        start: Math.min(...members.map((x) => x.start)),
+        end: Math.max(...members.map((x) => x.end)),
+        keys: members.flatMap((x) => x.keys).sort((a, b) => a - b).slice(0, MAX_KEYS),
+        parts: members.map((x) => ({ start: x.start, end: x.end }))
+      });
+    } else {
+      out.push(e.row, ...e.inner);
+      continue;
+    }
+    out.push(...e.inner);
+  }
+  return out;
+}
+function collectTimeline(root, duration) {
+  const rows = [];
+  const transitions = [];
+  walk(root, 0, duration, 0, "", rows, transitions);
+  return { duration, rows, transitions };
+}
+var COLORS = {
+  text: "#4cc9f0",
+  shape: "#ffd166",
+  image: "#7bd88f",
+  video: "#c77dff",
+  audio: "#ff7aa8",
+  composition: "#8ea4c8",
+  three: "#ff9f68",
+  camera: "#b0b0b0"
+};
+var esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+var num = (n) => String(Math.round(n * 100) / 100);
+function tickStep(duration, chartWidth) {
+  for (const s of [0.04, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 1200, 3600]) if (s / duration * chartWidth >= 70) return s;
+  return 7200;
+}
+function timelineSvg(data, opts = {}) {
+  const CHART = Math.max(100, opts.chartWidth ?? 950), withLabels = opts.labels !== false;
+  const LABEL = withLabels ? 250 : 0, ROW = 22, TOP = 34, PAD = 16;
+  const W = LABEL + CHART + PAD * 2, H = TOP + data.rows.length * ROW + PAD;
+  const x = (t) => PAD + LABEL + Math.max(0, Math.min(data.duration, t)) / data.duration * CHART;
+  const step = tickStep(data.duration, CHART);
+  const out = [];
+  for (let t = 0; t <= data.duration + 1e-9; t += step) {
+    out.push(`<line class="grid" x1="${num(x(t))}" y1="${TOP - 6}" x2="${num(x(t))}" y2="${H - PAD}"/>`);
+    out.push(`<text class="tick" x="${num(x(t))}" y="${TOP - 12}" text-anchor="middle">${num(t)}${t === 0 || Math.abs(t - data.duration) < 1e-9 ? " s" : ""}</text>`);
+  }
+  if (Math.abs(data.duration % step) > 1e-9) out.push(`<text class="tick" x="${num(x(data.duration))}" y="${TOP - 12}" text-anchor="middle">${num(data.duration)} s</text>`);
+  for (const t of data.transitions) {
+    out.push(`<g><title>transition ${esc(t.from)} \u2192 ${esc(t.to)} (${num(t.start)}\u2013${num(t.end)} s)</title><rect class="transition" x="${num(x(t.start))}" y="${TOP - 4}" width="${num(Math.max(2, x(t.end) - x(t.start)))}" height="${H - TOP - PAD + 4}"/></g>`);
+  }
+  data.rows.forEach((r, i) => {
+    const y = TOP + i * ROW;
+    const color = COLORS[r.type] ?? "#9aa7b8";
+    const tip = `${r.path} \xB7 ${r.type} \xB7 ${num(r.start)}\u2013${num(r.end)} s (${num(r.end - r.start)} s)${r.keys.length ? ` \xB7 ${r.keys.length} keyframe${r.keys.length > 1 ? "s" : ""}` : ""}${r.detail ? ` \xB7 ${r.detail}` : ""}`;
+    out.push(`<g class="row" data-start="${num(r.start)}"><title>${esc(tip)}</title>`);
+    out.push(`<rect class="band" x="${PAD}" y="${y}" width="${LABEL + CHART}" height="${ROW}" ${i % 2 ? 'fill-opacity=".05"' : 'fill-opacity="0"'}/>`);
+    if (withLabels) out.push(`<text class="label" x="${PAD + 6 + r.depth * 14}" y="${y + 15}">${esc(r.name)}</text>`);
+    for (const p of r.parts ?? [{ start: r.start, end: r.end }]) {
+      out.push(`<rect class="bar" x="${num(x(p.start))}" y="${y + 4}" width="${num(Math.max(2, x(p.end) - x(p.start)))}" height="${ROW - 8}" rx="3" fill="${color}"/>`);
+    }
+    for (const k of r.keys) out.push(`<path class="key" d="M ${num(x(k))} ${y + 7} l 3 4 l -3 4 l -3 -4 z"/>`);
+    out.push("</g>");
+  });
+  const legend = Object.entries(COLORS).map(([type, c], i) => `<g transform="translate(${PAD + i * 108},${H + 10})"><rect width="12" height="12" rx="3" fill="${c}"/><text x="18" y="10" class="tick">${type}</text></g>`).join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H + 32}" viewBox="0 0 ${W} ${H + 32}" role="img" aria-label="Timeline of ${data.rows.length} rows" data-duration="${num(data.duration)}" data-x0="${num(x(0))}" data-x1="${num(x(data.duration))}" data-top="${TOP - 6}" data-bottom="${H - PAD}" data-row="${ROW}">
+${out.join("\n")}
+${legend}
+</svg>`;
+}
+function timelineHtml(data, opts = {}) {
+  const W = 250 + 950 + 32;
+  const title = esc(opts.title ?? "Timeline");
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title} \u2014 timeline</title>
+<style>
+  :root { --bg: #f7f5f1; --ink: #1d2433; --dim: #6b7587; --grid: #d9d5cc; --key: #1d2433; --trans: #4cc9f0; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0e1320; --ink: #e8eefc; --dim: #8fa0bf; --grid: #26304a; --key: #ffffff; --trans: #4cc9f0; } }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 14px system-ui, sans-serif; }
+  main { padding: 20px 16px 32px; max-width: ${W + 32}px; margin: 0 auto; overflow-x: auto; }
+  h1 { font-size: 18px; font-weight: 600; margin: 0 0 4px; }
+  p { margin: 0 0 14px; color: var(--dim); font-size: 13px; }
+  svg { display: block; }
+  .grid { stroke: var(--grid); stroke-width: 1; }
+  .tick { fill: var(--dim); font-size: 11px; }
+  .label { fill: var(--ink); font-size: 12px; font-family: ui-monospace, Menlo, monospace; }
+  .band { fill: var(--ink); }
+  .key { fill: var(--key); opacity: .85; }
+  .transition { fill: var(--trans); opacity: .16; }
+  .bar { opacity: .88; }
+  .row:hover .bar { opacity: 1; }
+</style></head>
+<body><main>
+<h1>${title}</h1>
+<p>${data.rows.length} row${data.rows.length === 1 ? "" : "s"} \xB7 ${num(data.duration)} s \xB7 \u25C6 keyframe start \xB7 shaded band: a transition \xB7 hover a bar for details</p>
+${timelineSvg(data)}
+</main></body></html>
+`;
+}
+
 // src/core/frames.ts
 function pickFrames(lastFrame, count) {
   const last = Math.max(0, Math.floor(lastFrame));
@@ -1266,6 +1442,8 @@ var Movie = class {
   audioSource = null;
   gainNode = null;
   _cancelAudioStart = null;
+  /** > 0 while the movie moves its own playhead (playback, render, snapshot, contactSheet): those are not the seeks `seeking` / `seeked` report. */
+  _quiet = 0;
   _volume = 1;
   _muted = false;
   isPlaying = false;
@@ -1359,6 +1537,7 @@ var Movie = class {
         height: options.composition.height ?? this.height,
         duration: options.composition.duration ?? this.duration
       } : void 0;
+      await ensureFilterLibrary(seededComposition);
       const userComposition = seededComposition ? expandTransitions(seededComposition) : void 0;
       const rootSeqSpec = {
         type: "composition",
@@ -1392,12 +1571,32 @@ var Movie = class {
       } catch (cleanupErr) {
         console.warn("pixi-effects: cleanup after init failure also threw:", cleanupErr);
       }
+      this._emitError("init", err);
       throw err;
     }
   }
   async gotoFrame(frame, force = false) {
     if (this._initState !== "ready") return;
     if (!force && this.currentFrame === frame) return;
+    if (this._quiet > 0) return this._goto(frame);
+    const target = Math.max(0, Math.min(frame, this.totalFrames));
+    this.emit("seeking", { frame: target, totalFrames: this.totalFrames });
+    await this._goto(frame);
+    this.emit("seeked", { frame: this.currentFrame, totalFrames: this.totalFrames });
+  }
+  /** Run `fn` with `seeking` / `seeked` silenced: the movie is moving its own playhead, not answering a seek. */
+  async _quietly(fn) {
+    this._quiet++;
+    try {
+      return await fn();
+    } finally {
+      this._quiet--;
+    }
+  }
+  _emitError(where, error) {
+    this.emit("error", { where, message: error instanceof Error ? error.message : String(error), error });
+  }
+  async _goto(frame) {
     this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
     this.timeline.time(this.currentFrame / this.frameRate);
     await this._awaitVideoFrames();
@@ -1419,7 +1618,7 @@ var Movie = class {
   async snapshot(frame = this.currentFrame, opts = {}) {
     warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as"]);
     this._requireReady("snapshot");
-    await this.gotoFrame(clampFrame(frame, this.totalFrames), true);
+    await this._quietly(() => this.gotoFrame(clampFrame(frame, this.totalFrames), true));
     const scale = opts.scale ?? 1;
     const out = document.createElement("canvas");
     out.width = Math.max(1, Math.round(this.width * scale));
@@ -1443,7 +1642,7 @@ var Movie = class {
     try {
       for (let i = 0; i < frames.length; i++) {
         const f = frames[i];
-        await this.gotoFrame(f, true);
+        await this._quietly(() => this.gotoFrame(f, true));
         const { x, y } = L.positions[i];
         g.drawImage(this.app.canvas, x, y + LABEL_H, L.cellW, L.cellH);
         g.fillStyle = "#e8ecf8";
@@ -1452,7 +1651,7 @@ var Movie = class {
         g.fillText(`frame ${f}  \xB7  ${(f / this.frameRate).toFixed(2)}s`, x + 8, y + LABEL_H / 2);
       }
     } finally {
-      await this.gotoFrame(back, true);
+      await this._quietly(() => this.gotoFrame(back, true));
     }
     return encodeCanvas(sheet, "image/png", opts.as ?? "blob");
   }
@@ -1467,6 +1666,24 @@ var Movie = class {
     await this.gotoFrame(f, true);
     return inspectScene(this._rootSequence, f, f / this.frameRate, { width: this.width, height: this.height }, opts);
   }
+  /**
+   * Every layer as a row with absolute start / end / keyframe times (seconds), plus the transition windows. Runs of
+   * similar layers (`pop-1` … `pop-12`) are one row with a `parts` span each. Read it, or draw it with `timelineChart()`.
+   */
+  timelineData() {
+    this._requireReady("timelineData");
+    return collectTimeline(this._rootSequence, this.duration);
+  }
+  /** The timeline as one self-contained HTML page (an inline SVG, no scripts): layers as bars on a time axis, ◆ keyframes, transition bands. Open it in a browser. */
+  timelineChart(opts = {}) {
+    warnUnknownOptions("movie.timelineChart()", opts, ["title"]);
+    return timelineHtml(this.timelineData(), opts);
+  }
+  /** Just the chart: one `<svg>` whose geometry is in `data-*` attributes (a viewer puts a playhead on it: `pixi-effects-view`). */
+  timelineSvg(opts = {}) {
+    warnUnknownOptions("movie.timelineSvg()", opts, ["chartWidth", "labels"]);
+    return timelineSvg(this.timelineData(), opts);
+  }
   /**
    * The soundtrack, measured: when every audio layer plays, how loud the mix is over time, and `issues`
    * (limiting, inaudible layers, sounds cut off by the end). Use it to CHECK sound you cannot hear.
@@ -1517,17 +1734,20 @@ var Movie = class {
       const frame = Math.floor(elapsed * this.frameRate);
       if (frame <= this.totalFrames) {
         inFlight = true;
-        this.gotoFrame(frame).catch((err) => {
+        this._goto(frame).catch((err) => {
           console.warn("pixi-effects: gotoFrame failed during playback:", err);
+          this._emitError("playback", err);
         }).finally(() => {
           inFlight = false;
         });
         this._raf = requestAnimationFrame(tick);
       } else {
         this.pause();
-        this.gotoFrame(this.totalFrames).catch((err) => {
+        this._goto(this.totalFrames).catch((err) => {
           console.warn("pixi-effects: final gotoFrame failed:", err);
+          this._emitError("playback", err);
         });
+        this.emit("ended");
       }
     };
     this._raf = requestAnimationFrame(tick);
@@ -1571,15 +1791,20 @@ var Movie = class {
     if (wasPlaying) this.emit("pause");
   }
   set volume(v) {
-    this._volume = Math.max(0, Math.min(1, v));
+    const next = Math.max(0, Math.min(1, v));
+    const changed = next !== this._volume;
+    this._volume = next;
     if (this.gainNode) this.gainNode.gain.value = this._muted ? 0 : this._volume;
+    if (changed) this.emit("volumechange", { volume: this._volume, muted: this._muted });
   }
   get volume() {
     return this._volume;
   }
   set muted(v) {
+    const changed = !!v !== this._muted;
     this._muted = !!v;
     if (this.gainNode) this.gainNode.gain.value = this._muted ? 0 : this._volume;
+    if (changed) this.emit("volumechange", { volume: this._volume, muted: this._muted });
   }
   get muted() {
     return this._muted;
@@ -1590,7 +1815,12 @@ var Movie = class {
   }
   async render(options) {
     warnUnknownOptions("movie.render()", options, ["format", "video", "audio"]);
-    return await exportFrames(this, options);
+    try {
+      return await this._quietly(() => exportFrames(this, options));
+    } catch (err) {
+      this._emitError("render", err);
+      throw err;
+    }
   }
   async destroy() {
     safeRun(() => this.pause());