pixi-effects 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,10 +1,59 @@
-export { C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, a as InspectReport, L as LayerInfo, M as Movie, b as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions } from './Movie-CghFXprP.cjs';
-import { S as Sequence } from './Base-5R7C5pHR.cjs';
-import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, b as SequenceCommon } from './types-CRE9WKd4.cjs';
-export { A as AssetSpec, c as AudioSequenceSpec, d as ChromaKeyFilterSpec, e as CircleShapeSpec, f as CompositionSequenceSpec, g as CompositionSpec, h as CrossfadeTransition, i as CustomFilterSpec, D as DipTransition, j as DissolveTransition, E as EllipseShapeSpec, k as Expr, F as FilterSpec, G as GradientSpec, l as IrisTransition, K as Keyframe, L as LineShapeSpec, P as PathShapeSpec, m as PolygonShapeSpec, n as PropValue, o as Props, R as RectShapeSpec, p as ShapeSequenceSpec, q as SlideTransition, T as TextSequenceSpec, r as TransitionCommon, s as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-CRE9WKd4.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 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';
 import 'pixi.js';
 import 'gsap';
 
+/** A text style as written in a `text` layer's `style` (numbers, not expressions, for the fields that size the text). */
+type MeasureStyle = Record<string, unknown>;
+interface TextSize {
+    width: number;
+    height: number;
+    /** Number of lines. */
+    lines: number;
+}
+interface SplitOptions {
+    /** What a piece is: one visible character (default), one word, or one line. */
+    by?: 'chars' | 'words' | 'lines';
+    /** Where the text goes: `x` is its left edge, or its centre / right edge with `align`. Default 0. */
+    x?: number;
+    /** Top of the first line. Default 0. */
+    y?: number;
+    /** How each line sits on `x`. Default `'left'`. */
+    align?: 'left' | 'center' | 'right';
+}
+interface TextPiece {
+    text: string;
+    /** Left edge of the piece, for a text layer with `anchorX: 0` (the default for text). */
+    x: number;
+    /** Top of the piece's line, for a text layer with `anchorY: 0`. */
+    y: number;
+    width: number;
+    /** Position in the returned list, 0-based. */
+    index: number;
+    /** Which line (0-based) the piece is on. */
+    line: number;
+}
+/**
+ * How big `text` is drawn with `style`: the same numbers a text layer with that style has, measured with the font the
+ * renderer will use. A web font must be loaded first (`await document.fonts.load('24px "Name"')`), or the width is a
+ * fallback font's.
+ */
+declare function measureText(text: string, style?: MeasureStyle): TextSize;
+/**
+ * Cut `text` into characters, words or lines and give each piece the x / y it needs so that one text layer per piece
+ * (same `style`, `anchorX: 0`, `anchorY: 0`) reads exactly like the whole text: per-letter and per-word animation without
+ * measuring anything by hand. Kerning is kept (a piece's x is the measured width of everything before it). Whitespace is
+ * not returned as a piece, but it takes its room. Lines are split on `\n` and go down by the style's line height.
+ *
+ * ```js
+ * splitText('Hello world', style, { by: 'words', x: 640, y: 300, align: 'center' })
+ *   .map(p => ({ type: 'text', text: p.text, style, initial: { x: p.x, y: p.y, alpha: 0 }, at: 0.2 * p.index, ... }))
+ * ```
+ */
+declare function splitText(text: string, style?: MeasureStyle, opts?: SplitOptions): TextPiece[];
+
 type SequenceCtor = {
     new (spec: SequenceSpec, parent: CompositionShape | null, root: CompositionShape): Sequence;
 };
@@ -147,4 +196,4 @@ interface WithFadeOptions {
  */
 declare function withFade<T extends SequenceCommon>(spec: T, opts: WithFadeOptions): T;
 
-export { CameraSequenceSpec, ImageSequenceSpec, type KenBurnsOptions, type OrbitOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type WithFadeOptions, kenBurns, orbit, registerSequenceType, withFade };
+export { CameraSequenceSpec, ImageSequenceSpec, type KenBurnsOptions, type MeasureStyle, type OrbitOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type TextPiece, type TextSize, type WithFadeOptions, kenBurns, measureText, orbit, registerSequenceType, splitText, withFade };

package/dist/index.d.ts

@@ -1,10 +1,59 @@
-export { C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, a as InspectReport, L as LayerInfo, M as Movie, b as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions } from './Movie-DRZtIGU7.js';
-import { S as Sequence } from './Base-DhY9oMxr.js';
-import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, b as SequenceCommon } from './types-CRE9WKd4.js';
-export { A as AssetSpec, c as AudioSequenceSpec, d as ChromaKeyFilterSpec, e as CircleShapeSpec, f as CompositionSequenceSpec, g as CompositionSpec, h as CrossfadeTransition, i as CustomFilterSpec, D as DipTransition, j as DissolveTransition, E as EllipseShapeSpec, k as Expr, F as FilterSpec, G as GradientSpec, l as IrisTransition, K as Keyframe, L as LineShapeSpec, P as PathShapeSpec, m as PolygonShapeSpec, n as PropValue, o as Props, R as RectShapeSpec, p as ShapeSequenceSpec, q as SlideTransition, T as TextSequenceSpec, r as TransitionCommon, s as TransitionSpec, V as VideoSequenceSpec, W as WipeTransition, Z as ZoomTransition } from './types-CRE9WKd4.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 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';
 import 'pixi.js';
 import 'gsap';
 
+/** A text style as written in a `text` layer's `style` (numbers, not expressions, for the fields that size the text). */
+type MeasureStyle = Record<string, unknown>;
+interface TextSize {
+    width: number;
+    height: number;
+    /** Number of lines. */
+    lines: number;
+}
+interface SplitOptions {
+    /** What a piece is: one visible character (default), one word, or one line. */
+    by?: 'chars' | 'words' | 'lines';
+    /** Where the text goes: `x` is its left edge, or its centre / right edge with `align`. Default 0. */
+    x?: number;
+    /** Top of the first line. Default 0. */
+    y?: number;
+    /** How each line sits on `x`. Default `'left'`. */
+    align?: 'left' | 'center' | 'right';
+}
+interface TextPiece {
+    text: string;
+    /** Left edge of the piece, for a text layer with `anchorX: 0` (the default for text). */
+    x: number;
+    /** Top of the piece's line, for a text layer with `anchorY: 0`. */
+    y: number;
+    width: number;
+    /** Position in the returned list, 0-based. */
+    index: number;
+    /** Which line (0-based) the piece is on. */
+    line: number;
+}
+/**
+ * How big `text` is drawn with `style`: the same numbers a text layer with that style has, measured with the font the
+ * renderer will use. A web font must be loaded first (`await document.fonts.load('24px "Name"')`), or the width is a
+ * fallback font's.
+ */
+declare function measureText(text: string, style?: MeasureStyle): TextSize;
+/**
+ * Cut `text` into characters, words or lines and give each piece the x / y it needs so that one text layer per piece
+ * (same `style`, `anchorX: 0`, `anchorY: 0`) reads exactly like the whole text: per-letter and per-word animation without
+ * measuring anything by hand. Kerning is kept (a piece's x is the measured width of everything before it). Whitespace is
+ * not returned as a piece, but it takes its room. Lines are split on `\n` and go down by the style's line height.
+ *
+ * ```js
+ * splitText('Hello world', style, { by: 'words', x: 640, y: 300, align: 'center' })
+ *   .map(p => ({ type: 'text', text: p.text, style, initial: { x: p.x, y: p.y, alpha: 0 }, at: 0.2 * p.index, ... }))
+ * ```
+ */
+declare function splitText(text: string, style?: MeasureStyle, opts?: SplitOptions): TextPiece[];
+
 type SequenceCtor = {
     new (spec: SequenceSpec, parent: CompositionShape | null, root: CompositionShape): Sequence;
 };
@@ -147,4 +196,4 @@ interface WithFadeOptions {
  */
 declare function withFade<T extends SequenceCommon>(spec: T, opts: WithFadeOptions): T;
 
-export { CameraSequenceSpec, ImageSequenceSpec, type KenBurnsOptions, type OrbitOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type WithFadeOptions, kenBurns, orbit, registerSequenceType, withFade };
+export { CameraSequenceSpec, ImageSequenceSpec, type KenBurnsOptions, type MeasureStyle, type OrbitOptions, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type TextPiece, type TextSize, type WithFadeOptions, kenBurns, measureText, orbit, registerSequenceType, splitText, withFade };

package/dist/index.js

@@ -1,8 +1,9 @@
-import { CompositionSequence } from './chunk-A574IA4F.js';
-import { homeDistance, DEFAULT_FOV, DEG, resolveAt, collectPropKeys } from './chunk-ZQX7WIYL.js';
-export { registerSequenceType } from './chunk-ZQX7WIYL.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, Assets, ExtensionType, Filter, UniformGroup, GpuProgram, GlProgram, defaultFilterVert } 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';
@@ -68,21 +69,213 @@ async function loadAssetBundle(assets, audioContext) {
 async function mixdown(audios, totalDuration, sampleRate = 44100) {
   if (audios.length === 0) return null;
   const ctx = new OfflineAudioContext(2, Math.ceil(sampleRate * totalDuration), sampleRate);
+  const synthesised = /* @__PURE__ */ new Map();
+  const bufferOf = (a) => {
+    if (a.buffer) return a.buffer;
+    if (!a.synth) return null;
+    let buf = synthesised.get(a.synth.key);
+    if (!buf) {
+      const [left, right] = a.synth.render(sampleRate);
+      buf = ctx.createBuffer(2, left.length, sampleRate);
+      buf.getChannelData(0).set(left);
+      buf.getChannelData(1).set(right);
+      synthesised.set(a.synth.key, buf);
+    }
+    return buf;
+  };
   for (const a of audios) {
+    const buffer = bufferOf(a);
+    if (!buffer) continue;
+    const begin = Math.max(0, a.start);
+    const skipped = begin - a.start;
+    if (skipped > 0) {
+      console.warn(
+        `pixi-effects: ${a.layer ?? "an audio layer"} starts at ${a.start.toFixed(2)}s, before the movie starts, so its first ${skipped.toFixed(2)}s are cut off. Start it at 0 or later.`
+      );
+    }
     const src = ctx.createBufferSource();
-    src.buffer = a.buffer;
+    src.buffer = buffer;
     src.loop = !!a.loop;
     const gain = ctx.createGain();
-    gain.gain.setValueAtTime(a.initialVolume ?? 1, a.start);
+    gain.gain.setValueAtTime(a.initialVolume ?? 1, begin);
     for (const kf of a.volumeKeyframes ?? []) {
-      gain.gain.linearRampToValueAtTime(kf.value, kf.time);
+      gain.gain.linearRampToValueAtTime(kf.value, Math.max(0, kf.time));
     }
     src.connect(gain).connect(ctx.destination);
-    src.start(a.start);
-    src.stop(a.end);
+    src.start(begin, skipped);
+    src.stop(Math.max(begin, a.end));
   }
   return await ctx.startRendering();
 }
+var KNEE = 0.9;
+function limitMix(buffer, audios) {
+  let peak = 0;
+  let peakIndex = 0;
+  for (let ch = 0; ch < buffer.numberOfChannels; ch++) {
+    const d = buffer.getChannelData(ch);
+    for (let i = 0; i < d.length; i++) {
+      const x = Math.abs(d[i]);
+      if (x > peak) {
+        peak = x;
+        peakIndex = i;
+      }
+      if (x > KNEE) d[i] = Math.sign(d[i]) * (KNEE + (1 - KNEE) * Math.tanh((x - KNEE) / (1 - KNEE)));
+    }
+  }
+  const peakAt = peakIndex / buffer.sampleRate;
+  if (peak > 1) {
+    const playing = audios.filter((a) => a.start <= peakAt && peakAt < a.end).map((a) => a.layer ?? "an audio layer");
+    console.warn(
+      `pixi-effects: the audio mix peaks at ${peak.toFixed(2)} (${(20 * Math.log10(peak)).toFixed(1)} dBFS) at ${peakAt.toFixed(2)}s, so it was limited (it would distort). Playing there: ${[...new Set(playing)].join(", ")}. Lower their volume.`
+    );
+  }
+  return { peak, peakAt };
+}
+
+// src/core/spectrum.ts
+function fft(re, im) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = -2 * Math.PI / len;
+    for (let i = 0; i < n; i += len) {
+      for (let k = 0; k < len / 2; k++) {
+        const wr = Math.cos(ang * k), wi = Math.sin(ang * k);
+        const a = i + k, b = a + len / 2;
+        const xr = re[b] * wr - im[b] * wi, xi = re[b] * wi + im[b] * wr;
+        re[b] = re[a] - xr;
+        im[b] = im[a] - xi;
+        re[a] = re[a] + xr;
+        im[a] = im[a] + xi;
+      }
+    }
+  }
+}
+var FRAME = 2048;
+function spectralCentroid(samples, sampleRate, from = 0, to = samples.length) {
+  let num = 0;
+  let den = 0;
+  const re = new Float64Array(FRAME);
+  const im = new Float64Array(FRAME);
+  const end = Math.min(to, samples.length);
+  for (let start = Math.max(0, from); start < end; start += FRAME / 2) {
+    for (let i = 0; i < FRAME; i++) {
+      const k = start + i;
+      const w = 0.5 - 0.5 * Math.cos(2 * Math.PI * i / (FRAME - 1));
+      re[i] = k < end ? samples[k] * w : 0;
+      im[i] = 0;
+    }
+    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);
+      den += power;
+    }
+  }
+  return den > 1e-9 ? Math.round(num / den / 10) * 10 : 0;
+}
+
+// src/core/inspectAudio.ts
+var INAUDIBLE_DB = -50;
+var db = (x) => Math.round(10 * Math.max(-120, 20 * Math.log10(x))) / 10;
+var mono = (chans) => {
+  if (chans.length === 1) return chans[0];
+  const out = new Float32Array(chans[0].length);
+  for (const d of chans) for (let i = 0; i < out.length; i++) out[i] = out[i] + d[i] / chans.length;
+  return out;
+};
+function measure(chans, sampleRate) {
+  let peak = 0;
+  let at = 0;
+  for (const d of chans) for (let i = 0; i < d.length; i++) if (Math.abs(d[i]) > peak) {
+    peak = Math.abs(d[i]);
+    at = i;
+  }
+  return {
+    length: Math.round(chans[0].length / sampleRate * 1e3) / 1e3,
+    peakDb: db(peak),
+    loudestAt: Math.round(at / sampleRate * 1e3) / 1e3,
+    brightnessHz: spectralCentroid(mono(chans), sampleRate)
+  };
+}
+function analyzeAudio(mix, sources, stats, movieDuration, opts = {}) {
+  if (!mix) {
+    return { duration: movieDuration, sampleRate: 0, peakDb: -120, peakAt: 0, sources: [], windows: [], issues: ['no audio: the movie has no audio layers (sound effects need no files: { type: "audio", sfx: "pop", at: 1 })'] };
+  }
+  const sr = mix.sampleRate;
+  const chans = Array.from({ length: mix.numberOfChannels }, (_, c) => mix.getChannelData(c));
+  const mixMono = mono(chans);
+  const peakIn = (t0, t1) => {
+    let p = 0;
+    const i1 = Math.min(mix.length, Math.ceil(t1 * sr));
+    for (const d of chans) for (let i = Math.max(0, Math.floor(t0 * sr)); i < i1; i++) p = Math.max(p, Math.abs(d[i]));
+    return p;
+  };
+  const win = opts.window && opts.window > 0 ? Math.max(0.01, opts.window) : 0.1;
+  const windows2 = [];
+  for (let t = 0; t < movieDuration - 1e-9; t += win) {
+    const i0 = Math.floor(t * sr);
+    const i1 = Math.min(mix.length, Math.floor((t + win) * sr));
+    let sum = 0;
+    let peak = 0;
+    for (const d of chans) {
+      for (let i = i0; i < i1; i++) {
+        sum += d[i] * d[i];
+        peak = Math.max(peak, Math.abs(d[i]));
+      }
+    }
+    const n = Math.max(1, (i1 - i0) * chans.length);
+    windows2.push({ t: Math.round(t * 1e3) / 1e3, rmsDb: db(Math.sqrt(sum / n)), peakDb: db(peak), brightnessHz: spectralCentroid(mixMono, sr, i0, i1) });
+  }
+  const issues = [];
+  if (stats && stats.peak > 1) {
+    issues.push(`the mix peaks at ${db(stats.peak)} dBFS at ${stats.peakAt.toFixed(2)}s and was limited \u2014 lower the volume of the layers playing there`);
+  }
+  const rendered = /* @__PURE__ */ new Map();
+  const soundOf = (s) => {
+    if (s.synth) {
+      let m = rendered.get(s.synth.key);
+      if (!m) rendered.set(s.synth.key, m = measure(s.synth.render(sr), sr));
+      return m;
+    }
+    const b = s.buffer;
+    return measure(Array.from({ length: b.numberOfChannels }, (_, c) => b.getChannelData(c)), b.sampleRate);
+  };
+  const list = [...sources].sort((a, b) => a.start - b.start).map((s) => {
+    const layer = s.layer ?? "an audio layer";
+    const source = s.source ?? "audio";
+    const peakDb = db(peakIn(s.start, Math.min(s.end, movieDuration)));
+    const sound = soundOf(s);
+    const topVolume = Math.max(s.initialVolume ?? 1, ...(s.volumeKeyframes ?? []).map((k) => k.value));
+    const ownDb = db(Math.pow(10, sound.peakDb / 20) * Math.max(0, topVolume));
+    if (s.start >= movieDuration) {
+      issues.push(`${layer} (${source}) starts at ${s.start.toFixed(2)}s, after the movie ends (${movieDuration}s)`);
+    } else if (ownDb < INAUDIBLE_DB || peakDb < INAUDIBLE_DB) {
+      issues.push(`${layer} (${source}) is inaudible from ${s.start.toFixed(2)}s to ${s.end.toFixed(2)}s (its own peak ${ownDb} dBFS at volume ${topVolume}; mix peak there ${peakDb} dBFS) \u2014 check its volume`);
+    }
+    if (s.synth && s.end > movieDuration + 1e-6 && s.start < movieDuration) {
+      issues.push(`${layer} (${source}) is cut off by the end of the movie at ${movieDuration}s (it runs to ${s.end.toFixed(2)}s)`);
+    }
+    return { layer, source, start: s.start, end: s.end, peakDb, sound };
+  });
+  return {
+    duration: movieDuration,
+    sampleRate: sr,
+    peakDb: db(stats?.peak ?? peakIn(0, movieDuration)),
+    peakAt: stats?.peakAt ?? 0,
+    sources: list,
+    windows: windows2,
+    issues
+  };
+}
 var VIDEO_CODEC_BY_FORMAT = {
   mp4: "avc",
   mov: "avc",
@@ -140,7 +333,7 @@ async function exportFrames(movie, options = {}) {
     const audioSource = new AudioBufferSource({
       codec: opts.audio.codec,
       bitrate: opts.audio.bitrate
-    });
+    }, { startTimestamp: opts.audio.codec === "aac" ? -2112 / movie.audioBuffer.sampleRate : 0 });
     output.addAudioTrack(audioSource);
     await output.start();
     await audioSource.add(movie.audioBuffer);
@@ -926,7 +1119,8 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
   const view = { x: 0, y: 0, width: canvas.width, height: canvas.height };
   const seen = /* @__PURE__ */ new Map();
   const scene = /* @__PURE__ */ new Map();
-  const walk = (comp, prefix, insideThreeD, parentVisible, parentScene) => {
+  const scaledToNothing = /* @__PURE__ */ new Set();
+  const walk = (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;
@@ -955,7 +1149,9 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
         if (area === 0) onCanvas = "none";
       }
       const keys = collectPropKeys(seq.spec);
-      const moving = (seq.spec.keyframes ?? []).length > 0 && (keys.has("x") || keys.has("y"));
+      const moving = parentMoving || (seq.spec.keyframes ?? []).length > 0 && (keys.has("x") || keys.has("y"));
+      const scale = t?.scale;
+      const zero = parentZero || !!scale && (scale.x === 0 || scale.y === 0);
       const info = { path: prefix + label, name, type: seq.spec.type, threeD, visible, alpha, moving, bounds, onCanvas };
       layers.push(info);
       let shown = bounds ? clip(bounds, view) : null;
@@ -967,7 +1163,8 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
       seen.set(info, shown);
       const group = parentScene ?? (name !== void 0 && blending.has(name) ? name : void 0);
       if (group) scene.set(info, group);
-      if (seq instanceof CompositionSequence) walk(seq, prefix + label + "/", insideThreeD || threeD, visible, group);
+      if (zero || seq.showsNothingYet) scaledToNothing.add(info);
+      if (seq instanceof CompositionSequence) walk(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
     });
   };
   walk(root, "", false, true);
@@ -977,6 +1174,7 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
     const b = l.bounds;
     const who = `text layer "${l.path}"`;
     if (b.width < 1 || b.height < 1) {
+      if (scaledToNothing.has(l)) continue;
       issues.push(`${who} has no size (empty text, or not drawn yet)`);
     } else if (l.moving || scene.has(l)) ; else if (l.onCanvas === "none") {
       issues.push(`${who} is entirely outside the canvas (at ${Math.round(b.x)},${Math.round(b.y)}, ${Math.round(b.width)}\xD7${Math.round(b.height)})`);
@@ -1026,63 +1224,34 @@ function sheetLayout(n, columns, cellW, srcW, srcH, labelH) {
   return { cols, rows, cellW, cellH, width: cols * cellW, height: rows * (cellH + labelH), positions };
 }
 
-// src/core/options.ts
-function distance(a, b) {
-  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
-  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
-  for (let i = 1; i <= a.length; i++) {
-    for (let j = 1; j <= b.length; j++) {
-      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
-      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
-    }
-  }
-  return dp[a.length][b.length];
-}
-var isSubsequence = (small, big) => {
-  let i = 0;
-  for (const ch of big) if (i < small.length && ch === small[i]) i++;
-  return i === small.length;
-};
-var COMMON_ALIASES = {
-  fps: "frameRate",
-  framerate: "frameRate",
-  frame_rate: "frameRate",
-  bg: "background",
-  backgroundcolor: "background",
-  bgcolor: "background",
-  seconds: "duration",
-  length: "duration",
-  time: "duration",
-  w: "width",
-  h: "height",
-  cols: "columns",
-  sweep: "degrees",
-  angle: "degrees"
-};
-function suggestName(name, valid) {
-  const n = name.toLowerCase();
-  const alias = COMMON_ALIASES[n];
-  if (alias && valid.includes(alias)) return alias;
-  let best = null;
-  for (const v of valid) {
-    const lv = v.toLowerCase();
-    const d = distance(n, lv);
-    const close = d <= Math.max(1, Math.floor(Math.min(n.length, lv.length) / 3));
-    const abbreviation = n.length >= 3 && isSubsequence(n, lv) || lv.length >= 2 && n.length > lv.length && n.includes(lv);
-    if (!close && !abbreviation) continue;
-    const score = close ? d : 3 + (lv.length - n.length) / 100;
-    if (!best || score < best.score) best = { v, score };
-  }
-  return best ? best.v : null;
-}
-function warnUnknownOptions(where, opts, valid) {
-  if (!opts || typeof opts !== "object") return;
-  for (const key of Object.keys(opts)) {
-    if (valid.includes(key)) continue;
-    const guess = suggestName(key, valid);
-    console.warn(`pixi-effects: ${where}: unknown option "${key}"${guess ? ` \u2014 did you mean "${guess}"?` : ""} (valid: ${valid.join(", ")})`);
+// src/core/startWhenRunning.ts
+function startWhenRunning(ctx, start, gesture) {
+  if (ctx.state === "running") {
+    start();
+    return () => {
+    };
   }
+  let done = false;
+  const resume = () => {
+    ctx.resume?.()?.catch(() => {
+    });
+  };
+  const stop = () => {
+    done = true;
+    ctx.removeEventListener("statechange", onState);
+    for (const e of GESTURES) gesture?.removeEventListener(e, resume, true);
+  };
+  const onState = () => {
+    if (done || ctx.state !== "running") return;
+    stop();
+    start();
+  };
+  ctx.addEventListener("statechange", onState);
+  for (const e of GESTURES) gesture?.addEventListener(e, resume, true);
+  resume();
+  return stop;
 }
+var GESTURES = ["pointerdown", "mousedown", "touchend", "keydown"];
 
 // src/core/Movie.ts
 extensions.add(CullerPlugin);
@@ -1096,6 +1265,7 @@ var Movie = class {
   audioBuffer = null;
   audioSource = null;
   gainNode = null;
+  _cancelAudioStart = null;
   _volume = 1;
   _muted = false;
   isPlaying = false;
@@ -1110,6 +1280,9 @@ var Movie = class {
   _rootSequence = null;
   _rootContainer = null;
   _raf = null;
+  /** What went into the mix, and its peak before limiting — kept for inspectAudio(). */
+  _audioSources = [];
+  _mixStats = null;
   on(event, fn) {
     (this._events[event] ??= []).push(fn);
     if (event === "ready" && this._initState === "ready") {
@@ -1204,7 +1377,9 @@ var Movie = class {
       composition.collectAudio(audios, 0);
       if (audios.length > 0) {
         this.audioBuffer = await mixdown(audios, this.duration, audioContext.sampleRate);
+        if (this.audioBuffer) this._mixStats = limitMix(this.audioBuffer, audios);
       }
+      this._audioSources = audios;
       this.timeline.progress(1).progress(0);
       await this._awaitVideoFrames();
       this._updateSpace();
@@ -1292,6 +1467,15 @@ var Movie = class {
     await this.gotoFrame(f, true);
     return inspectScene(this._rootSequence, f, f / this.frameRate, { width: this.width, height: this.height }, 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.
+   */
+  inspectAudio(opts = {}) {
+    warnUnknownOptions("movie.inspectAudio()", opts, ["window"]);
+    this._requireReady("inspectAudio");
+    return analyzeAudio(this.audioBuffer, this._audioSources, this._mixStats, this.duration, opts);
+  }
   /**
    * Draw the stage now. PixiJS's CullerPlugin only culls inside `app.render()` (the ticker), and we render
    * by hand — while seeking and especially during `render()`, which stops the ticker — so without this the
@@ -1319,6 +1503,7 @@ var Movie = class {
   play() {
     if (this._initState !== "ready") return;
     if (this.currentFrame >= this.totalFrames) this.currentFrame = 0;
+    const wasPlaying = this.isPlaying;
     this.isPlaying = true;
     const startTime = performance.now() - this.currentFrame / this.frameRate * 1e3;
     let inFlight = false;
@@ -1348,17 +1533,25 @@ var Movie = class {
     this._raf = requestAnimationFrame(tick);
     if (this.audioBuffer) {
       const ctx = this._ensureAudioContext();
-      this.audioSource = ctx.createBufferSource();
-      this.audioSource.buffer = this.audioBuffer;
-      this.gainNode = ctx.createGain();
-      this.gainNode.gain.value = this._muted ? 0 : this._volume;
-      this.audioSource.connect(this.gainNode).connect(ctx.destination);
-      this.audioSource.start(0, this.currentFrame / this.frameRate);
+      const buffer = this.audioBuffer;
+      this._cancelAudioStart?.();
+      this._cancelAudioStart = startWhenRunning(ctx, () => {
+        if (!this.isPlaying) return;
+        this.audioSource = ctx.createBufferSource();
+        this.audioSource.buffer = buffer;
+        this.gainNode = ctx.createGain();
+        this.gainNode.gain.value = this._muted ? 0 : this._volume;
+        this.audioSource.connect(this.gainNode).connect(ctx.destination);
+        this.audioSource.start(0, Math.min(this.currentFrame / this.frameRate, buffer.duration));
+      }, typeof window !== "undefined" ? window : void 0);
     }
+    if (!wasPlaying) this.emit("play");
   }
   pause() {
     const wasPlaying = this.isPlaying;
     this.isPlaying = false;
+    this._cancelAudioStart?.();
+    this._cancelAudioStart = null;
     if (this._raf) {
       cancelAnimationFrame(this._raf);
       this._raf = null;
@@ -1408,6 +1601,8 @@ var Movie = class {
     safeRun(() => this.app?.destroy(true, { children: true, texture: true }));
     this.app = null;
     this.audioBuffer = null;
+    this._audioSources = [];
+    this._mixStats = null;
     safeRun(() => this._audioContext?.close().catch(() => {
     }));
     this._audioContext = null;
@@ -1435,6 +1630,53 @@ function collectVideoSequences(seq, out) {
     collectVideoSequences(child, out);
   }
 }
+var BY = ["chars", "words", "lines"];
+var ALIGN = ["left", "center", "right"];
+var widthOf = (text, style) => CanvasTextMetrics.measureText(text, style).width;
+function measureText(text, style = {}) {
+  const m = CanvasTextMetrics.measureText(text, new TextStyle(style));
+  return { width: m.width, height: m.height, lines: text.split("\n").length };
+}
+function splitText(text, style = {}, opts = {}) {
+  warnUnknownOptions("splitText()", opts, ["by", "x", "y", "align"]);
+  let by = opts.by ?? "chars";
+  if (!BY.includes(by)) {
+    const g = suggestName(String(by), BY);
+    console.warn(`pixi-effects: splitText(): by "${by}" is not one of ${BY.map((b) => `"${b}"`).join(", ")}${g ? ` \u2014 did you mean "${g}"?` : ""}; using "chars"`);
+    by = "chars";
+  }
+  let align = opts.align ?? "left";
+  if (!ALIGN.includes(align)) {
+    const g = suggestName(String(align), ALIGN);
+    console.warn(`pixi-effects: splitText(): align "${align}" is not one of ${ALIGN.join(", ")}${g ? ` \u2014 did you mean "${g}"?` : ""}; using "left"`);
+    align = "left";
+  }
+  const x0 = opts.x ?? 0, y0 = opts.y ?? 0;
+  if (text === "") return [];
+  const ts = new TextStyle(style);
+  const lineHeight = CanvasTextMetrics.measureText("M", ts).lineHeight ?? CanvasTextMetrics.measureText("M", ts).height;
+  const sentinel = widthOf("|", ts);
+  const out = [];
+  text.split("\n").forEach((line, lineNo) => {
+    const lineWidth = widthOf(line, ts);
+    const left = align === "center" ? x0 - lineWidth / 2 : align === "right" ? x0 - lineWidth : x0;
+    const y = y0 + lineNo * lineHeight;
+    const advance = (upTo) => upTo === 0 ? 0 : widthOf(line.slice(0, upTo) + "|", ts) - sentinel;
+    const spans = [];
+    if (by === "lines") {
+      if (line.trim() !== "") spans.push([0, line.length]);
+    } else if (by === "words") {
+      for (const m of line.matchAll(/\S+/g)) spans.push([m.index, m.index + m[0].length]);
+    } else {
+      for (let i = 0; i < line.length; i++) if (!/\s/.test(line[i])) spans.push([i, i + 1]);
+    }
+    for (const [a, b] of spans) {
+      const piece = line.slice(a, b);
+      out.push({ text: piece, x: left + advance(a), y, width: widthOf(piece, ts), index: out.length, line: lineNo });
+    }
+  });
+  return out;
+}
 
 // src/presets/kenBurns.ts
 var KEN_BURNS_KEYS = ["asset", "name", "at", "duration", "fit", "ease", "motion", "origin", "zoom", "direction", "angle", "from", "to"];
@@ -1628,6 +1870,6 @@ function withFade(spec, opts) {
   return spec;
 }
 
-export { Movie, kenBurns, orbit, withFade };
+export { Movie, kenBurns, measureText, orbit, splitText, withFade };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map