pixi-effects 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-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, T as TimelineData, f as TimelineHtmlOptions, g as TimelineRow, h as TimelineSvgOptions, i as TimelineTransition } from './Movie-BK9daiTt.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-qGHp15c_.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';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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, T as TimelineData, f as TimelineHtmlOptions, g as TimelineRow, h as TimelineSvgOptions, i as TimelineTransition } from './Movie-B0OUKlZI.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-QMlFyHkf.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';

package/dist/index.js

@@ -1,12 +1,12 @@
-import { CompositionSequence } from './chunk-36Z4RIRK.js';
-import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, DEG, resolveAt, collectPropKeys } from './chunk-4O2NYDJG.js';
-export { registerSequenceType } from './chunk-4O2NYDJG.js';
+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 * 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) {
@@ -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, {
@@ -1405,6 +1429,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
 extensions.add(CullerPlugin);
 gsap.registerPlugin(PixiPlugin);
@@ -1418,6 +1457,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;
@@ -1459,6 +1505,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;
@@ -1467,7 +1543,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
-    warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition"]);
+    warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition", "poster"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1475,6 +1551,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.timeline({ paused: true, defaults: { ease: "none" } });
       this.timeline.add(gsap.to({}, { duration: this.duration }));
@@ -1538,6 +1617,7 @@ var Movie = class {
       this._updateSpace();
       this._renderNow();
       this._initState = "ready";
+      if (this._posterFrame !== null) await this._showPoster();
       this.emit("ready");
     } catch (err) {
       try {
@@ -1545,12 +1625,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();
@@ -1572,7 +1673,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));
@@ -1592,11 +1693,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";
@@ -1605,7 +1706,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");
   }
@@ -1688,17 +1790,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);
@@ -1742,15 +1847,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;
@@ -1761,7 +1871,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());