pixi-effects 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk4VSIJLU3_cjs = require('./chunk-4VSIJLU3.cjs');
-var chunk6I55T4OH_cjs = require('./chunk-6I55T4OH.cjs');
+var chunkPDBDDGG5_cjs = require('./chunk-PDBDDGG5.cjs');
+var chunkAGMNSJJH_cjs = require('./chunk-AGMNSJJH.cjs');
 var chunkUQBGW5DO_cjs = require('./chunk-UQBGW5DO.cjs');
 var PIXI = require('pixi.js');
 var gsap = require('gsap');
@@ -308,6 +308,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) => mediabunny.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": mediabunny.QUALITY_VERY_LOW,
   "low": mediabunny.QUALITY_LOW,
@@ -340,8 +362,10 @@ async function exportFrames(movie, options = {}) {
       bitrate: qualityMap[options.audio?.bitrate ?? "high"] ?? mediabunny.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 mediabunny.Output({
-    format: makeOutputFormat(opts.format),
+    format: container,
     target: new mediabunny.BufferTarget()
   });
   const canvasSource = new mediabunny.CanvasSource(movie.app.canvas, {
@@ -819,16 +843,16 @@ function expandTransitions(spec) {
     if (toUses > 1) {
       throw new Error(`pixi-effects: ${tag} sequence "${t.to}" is used as \`to\` in more than one transition`);
     }
-    const tStart = chunk6I55T4OH_cjs.resolveAt(t.at, parentDuration);
+    const tStart = chunkAGMNSJJH_cjs.resolveAt(t.at, parentDuration);
     const tEnd = tStart + t.duration;
     const fromSeq = fromEntry.seq;
-    const fromStart = chunk6I55T4OH_cjs.resolveAt(fromSeq.at, parentDuration);
+    const fromStart = chunkAGMNSJJH_cjs.resolveAt(fromSeq.at, parentDuration);
     const fromEnd = fromStart + (fromSeq.duration ?? parentDuration);
     if (tStart < fromStart || tEnd > fromEnd) {
       throw new Error(`pixi-effects: ${tag} window [${tStart}, ${tEnd}] is not covered by \`from\` "${t.from}" (lives [${fromStart}, ${fromEnd}], so it ends at ${fromEnd})`);
     }
     const toSeq = toEntry.seq;
-    const toStart = chunk6I55T4OH_cjs.resolveAt(toSeq.at, parentDuration);
+    const toStart = chunkAGMNSJJH_cjs.resolveAt(toSeq.at, parentDuration);
     const toEnd = toStart + (toSeq.duration ?? parentDuration);
     if (tStart < toStart || tEnd > toEnd) {
       throw new Error(`pixi-effects: ${tag} window [${tStart}, ${tEnd}] is not covered by \`to\` "${t.to}" (lives [${toStart}, ${toEnd}], so it starts at ${toStart})`);
@@ -1168,7 +1192,7 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
         onCanvas = inter === 0 && area > 0 ? "none" : inter >= area - 1e-6 ? "full" : "partial";
         if (area === 0) onCanvas = "none";
       }
-      const keys = chunk6I55T4OH_cjs.collectPropKeys(seq.spec);
+      const keys = chunkAGMNSJJH_cjs.collectPropKeys(seq.spec);
       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);
@@ -1184,7 +1208,7 @@ 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 chunk4VSIJLU3_cjs.CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
+      if (seq instanceof chunkPDBDDGG5_cjs.CompositionSequence) walk2(seq, prefix + label + "/", insideThreeD || threeD, visible, group, moving, zero);
     });
   };
   walk2(root, "", false, true);
@@ -1244,10 +1268,10 @@ function walk(comp, parentStart, parentEnd, depth, prefix, rows, transitions) {
     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 + chunk6I55T4OH_cjs.resolveAt(kf.at, span))).sort((a, b) => a - b).slice(0, MAX_KEYS);
+    const keys = (seq.spec.keyframes ?? []).map((kf) => round(start + chunkAGMNSJJH_cjs.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 chunk4VSIJLU3_cjs.CompositionSequence;
+    const isComp = seq instanceof chunkPDBDDGG5_cjs.CompositionSequence;
     if (isComp) walk(seq, start, end, depth + 1, prefix + name + "/", inner, transitions);
     entries.push({ row, inner, groupable: !isComp });
   });
@@ -1425,6 +1449,21 @@ function startWhenRunning(ctx, start, gesture) {
 }
 var GESTURES = ["pointerdown", "mousedown", "touchend", "keydown"];
 
+// src/core/poster.ts
+function normalizePoster(poster, duration, frameRate) {
+  if (poster === void 0 || poster === null) return { seconds: null, frame: null };
+  if (typeof poster !== "number" || !Number.isFinite(poster)) {
+    console.warn(`pixi-effects: movie.init({ poster }): ${JSON.stringify(poster)} is not a time in seconds; ignored`);
+    return { seconds: null, frame: null };
+  }
+  let seconds = poster < 0 ? Math.max(0, duration + poster) : poster;
+  if (seconds > duration) {
+    console.warn(`pixi-effects: movie.init({ poster }): the poster time ${poster} s is past the end of the movie (${duration} s); using the last frame`);
+    seconds = duration;
+  }
+  return { seconds, frame: Math.round(seconds * frameRate) };
+}
+
 // src/core/Movie.ts
 PIXI.extensions.add(PIXI.CullerPlugin);
 gsap.gsap.registerPlugin(PixiPlugin.PixiPlugin);
@@ -1438,6 +1477,13 @@ var Movie = class {
   audioSource = null;
   gainNode = null;
   _cancelAudioStart = null;
+  /** The poster time in seconds (`movie.init({ poster })`), or null. */
+  poster = null;
+  _posterFrame = null;
+  /** The canvas shows the poster picture while the playhead is still at frame 0 (like `<video poster>`): the first seek or play replaces it. */
+  _atPoster = false;
+  /** > 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;
@@ -1479,6 +1525,36 @@ var Movie = class {
   get isReady() {
     return this._initState === "ready";
   }
+  /** The poster time as a frame number, or null. */
+  get posterFrame() {
+    return this._posterFrame;
+  }
+  /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */
+  async _showPoster() {
+    if (this._posterFrame === null || !this.timeline) return;
+    const back = this.currentFrame;
+    this.currentFrame = this._posterFrame;
+    try {
+      this.timeline.time(this._posterFrame / this.frameRate);
+      await this._awaitVideoFrames();
+      this._updateSpace();
+      this._renderNow();
+    } finally {
+      this.currentFrame = back;
+    }
+    this._atPoster = true;
+  }
+  async posterImage(opts = {}) {
+    this._requireReady("posterImage");
+    const back = this.currentFrame, wasAtPoster = this._atPoster;
+    try {
+      return await this.snapshot(this._posterFrame ?? 0, opts);
+    } finally {
+      this.currentFrame = back;
+      if (wasAtPoster) await this._showPoster();
+      else await this._quietly(() => this.gotoFrame(back, true));
+    }
+  }
   _ensureAudioContext() {
     if (!this._audioContext) {
       const Ctx = window.AudioContext ?? window.webkitAudioContext;
@@ -1487,7 +1563,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
-    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition"]);
+    chunkUQBGW5DO_cjs.warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1495,6 +1571,9 @@ var Movie = class {
       this.duration = options.duration ?? 10;
       this.frameRate = options.frameRate ?? 30;
       this.totalFrames = Math.round(this.duration * this.frameRate);
+      const poster = normalizePoster(options.poster, this.duration, this.frameRate);
+      this.poster = poster.seconds;
+      this._posterFrame = poster.frame;
       this.background = options.background ?? "#000000";
       this.timeline = gsap.gsap.timeline({ paused: true, defaults: { ease: "none" } });
       this.timeline.add(gsap.gsap.to({}, { duration: this.duration }));
@@ -1531,7 +1610,7 @@ var Movie = class {
         height: options.composition.height ?? this.height,
         duration: options.composition.duration ?? this.duration
       } : void 0;
-      await chunk6I55T4OH_cjs.ensureFilterLibrary(seededComposition);
+      await chunkAGMNSJJH_cjs.ensureFilterLibrary(seededComposition);
       const userComposition = seededComposition ? expandTransitions(seededComposition) : void 0;
       const rootSeqSpec = {
         type: "composition",
@@ -1541,7 +1620,7 @@ var Movie = class {
         ...userComposition
       };
       if (userComposition) carryTransitionWindows(userComposition, rootSeqSpec);
-      const composition = new chunk4VSIJLU3_cjs.CompositionSequence(rootSeqSpec, null, rootShape);
+      const composition = new chunkPDBDDGG5_cjs.CompositionSequence(rootSeqSpec, null, rootShape);
       await composition.build();
       this._rootSequence = composition;
       if (composition.target) root.addChild(composition.target);
@@ -1558,6 +1637,7 @@ var Movie = class {
       this._updateSpace();
       this._renderNow();
       this._initState = "ready";
+      if (this._posterFrame !== null) await this._showPoster();
       this.emit("ready");
     } catch (err) {
       try {
@@ -1565,12 +1645,33 @@ 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 (!force && !this._atPoster && 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._atPoster = false;
     this.currentFrame = Math.max(0, Math.min(frame, this.totalFrames));
     this.timeline.time(this.currentFrame / this.frameRate);
     await this._awaitVideoFrames();
@@ -1592,7 +1693,7 @@ var Movie = class {
   async snapshot(frame = this.currentFrame, opts = {}) {
     chunkUQBGW5DO_cjs.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));
@@ -1612,11 +1713,11 @@ var Movie = class {
     const g = sheet.getContext("2d");
     g.fillStyle = "#10131c";
     g.fillRect(0, 0, L.width, L.height);
-    const back = this.currentFrame;
+    const back = this.currentFrame, wasAtPoster = this._atPoster;
     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";
@@ -1625,7 +1726,8 @@ 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);
+      if (wasAtPoster) await this._showPoster();
+      else await this._quietly(() => this.gotoFrame(back, true));
     }
     return encodeCanvas(sheet, "image/png", opts.as ?? "blob");
   }
@@ -1708,17 +1810,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);
@@ -1762,15 +1867,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;
@@ -1781,7 +1891,12 @@ var Movie = class {
   }
   async render(options) {
     chunkUQBGW5DO_cjs.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());
@@ -2004,17 +2119,17 @@ function orbit(opts) {
     throw new Error("pixi-effects: orbit() cannot combine `radius` with `dollyZoom` \u2014 the radius follows the animated fov");
   }
   const [cx, cy] = opts.center ?? [width / 2, height / 2];
-  const fixedR = opts.radius ?? chunk6I55T4OH_cjs.homeDistance(height, fov ?? chunk6I55T4OH_cjs.DEFAULT_FOV);
+  const fixedR = opts.radius ?? chunkAGMNSJJH_cjs.homeDistance(height, fov ?? chunkAGMNSJJH_cjs.DEFAULT_FOV);
   const start = opts.start ?? -degrees / 2;
   const steps = Math.max(1, Math.round(duration * stepsPerSecond));
   const easeFn = parseEase(ease);
   const dollyEase = dolly ? parseEase(dolly.ease ?? ease) : null;
   const pos = (i) => {
     const p = i / steps;
-    const a = (start + degrees * easeFn(p)) * chunk6I55T4OH_cjs.DEG;
+    const a = (start + degrees * easeFn(p)) * chunkAGMNSJJH_cjs.DEG;
     if (!dolly) return { x: cx + fixedR * Math.sin(a), z: fixedR * Math.cos(a) };
     const f = dolly.from + (dolly.to - dolly.from) * dollyEase(p);
-    const R = chunk6I55T4OH_cjs.homeDistance(height, f);
+    const R = chunkAGMNSJJH_cjs.homeDistance(height, f);
     return { x: cx + R * Math.sin(a), z: R * Math.cos(a), fov: f };
   };
   const keyframes = [];
@@ -2063,7 +2178,7 @@ function withFade(spec, opts) {
 
 Object.defineProperty(exports, "registerSequenceType", {
   enumerable: true,
-  get: function () { return chunk6I55T4OH_cjs.registerSequenceType; }
+  get: function () { return chunkAGMNSJJH_cjs.registerSequenceType; }
 });
 exports.Movie = Movie;
 exports.kenBurns = kenBurns;