@mediafox/core 1.2.12 → 1.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediafox/core",
-  "version": "1.2.12",
+  "version": "1.2.13",
   "description": "Framework-agnostic media player library powered by MediaBunny",
   "type": "module",
   "main": "./dist/index.js",

package/src/compositor/audio-manager.ts

@@ -113,7 +113,7 @@ export class CompositorAudioManager {
    * Updates which sources are playing and their parameters.
    */
   processAudioLayers(layers: AudioLayer[], mediaTime: number): void {
-    if (this.disposed || !this.playing) return;
+    if (this.disposed) return;
 
     // Track which sources are active in this frame
     const activeSourceIds = this.activeSourceIdsScratch;
@@ -179,6 +179,14 @@ export class CompositorAudioManager {
     this.startContextTime = this.audioContext.currentTime;
     this.startMediaTime = fromTime;
     this.pauseTime = fromTime;
+
+    // Clear any stale iterators so sources can be restarted fresh
+    for (const source of this.activeSources.values()) {
+      if (source.iterator) {
+        void source.iterator.return();
+        source.iterator = null;
+      }
+    }
   }
 
   /**
@@ -251,7 +259,7 @@ export class CompositorAudioManager {
 
         // Throttle if we're too far ahead (more than 1 second of audio buffered)
         const elapsedSinceStart = this.audioContext.currentTime - source.iteratorStartTime;
-        const bufferedAhead = (timestamp - source.startSourceTime) - elapsedSinceStart;
+        const bufferedAhead = timestamp - source.startSourceTime - elapsedSinceStart;
         if (bufferedAhead > 1) {
           await this.waitForCatchup(source, timestamp);
         }
@@ -272,7 +280,7 @@ export class CompositorAudioManager {
 
         // Calculate how far ahead we've buffered
         const elapsedSinceStart = this.audioContext.currentTime - source.iteratorStartTime;
-        const bufferedAhead = (targetSourceTime - source.startSourceTime) - elapsedSinceStart;
+        const bufferedAhead = targetSourceTime - source.startSourceTime - elapsedSinceStart;
         if (bufferedAhead < 1) {
           clearInterval(checkInterval);
           resolve();

package/src/compositor/compositor-worker.ts

@@ -1,16 +1,16 @@
 import { Compositor } from './compositor';
-import type { CompositorLayer, CompositionFrame, CompositorSource } from './types';
+import type { CompositionFrame, CompositorLayer, CompositorSource } from './types';
 import type {
   CompositorWorkerExportPayload,
   CompositorWorkerFrame,
   CompositorWorkerInitPayload,
   CompositorWorkerLoadPayload,
   CompositorWorkerRenderPayload,
+  CompositorWorkerRequest,
   CompositorWorkerResizePayload,
+  CompositorWorkerResponse,
   CompositorWorkerSourceInfo,
   CompositorWorkerUnloadPayload,
-  CompositorWorkerRequest,
-  CompositorWorkerResponse,
 } from './worker-types';
 
 type WorkerScope = {
@@ -48,6 +48,7 @@ const mapFrame = (frame: CompositorWorkerFrame): CompositionFrame => {
       source,
       sourceTime: layer.sourceTime,
       transform: layer.transform,
+      fitMode: layer.fitMode,
       visible: layer.visible,
       zIndex: layer.zIndex,
     };
@@ -122,8 +123,8 @@ workerScope.onmessage = async (event: MessageEvent<CompositorWorkerRequest>) =>
       }
       case 'resize': {
         if (!compositor) throw new Error('Compositor not initialized');
-        const { width, height } = payload as CompositorWorkerResizePayload;
-        compositor.resize(width, height);
+        const { width, height, fitMode } = payload as CompositorWorkerResizePayload;
+        compositor.resize(width, height, fitMode);
         postResponse({ id, ok: true, result: true });
         return;
       }

package/src/compositor/compositor.ts

@@ -11,6 +11,7 @@ import type {
   CompositorOptions,
   CompositorSource,
   CompositorSourceOptions,
+  FitMode,
   FrameExportOptions,
   PreviewOptions,
 } from './types';
@@ -60,6 +61,7 @@ export class Compositor {
   private width: number;
   private height: number;
   private backgroundColor: string;
+  private fitMode: FitMode;
   private sourcePool: SourcePool;
   private audioManager: CompositorAudioManager | null = null;
   private workerClient: CompositorWorkerClient | null = null;
@@ -88,6 +90,9 @@ export class Compositor {
   };
   private registeredAudioSources = new Set<string>();
 
+  // Seek/Play synchronization
+  private pendingPlayAfterSeek = false;
+
   /**
    * Creates a new Compositor instance.
    * @param options - Configuration options for the compositor
@@ -97,6 +102,7 @@ export class Compositor {
     this.width = options.width ?? (this.canvas.width || 1920);
     this.height = options.height ?? (this.canvas.height || 1080);
     this.backgroundColor = options.backgroundColor ?? '#000000';
+    this.fitMode = options.fitMode ?? 'fill';
     this.emitter = new EventEmitter({ maxListeners: 50 });
     this.state = {
       playing: false,
@@ -110,11 +116,7 @@ export class Compositor {
     this.canvas.height = this.height;
 
     const workerEnabled =
-      typeof options.worker === 'boolean'
-        ? options.worker
-        : options.worker
-          ? (options.worker.enabled ?? true)
-          : false;
+      typeof options.worker === 'boolean' ? options.worker : options.worker ? (options.worker.enabled ?? true) : false;
     const canUseWorker =
       workerEnabled &&
       typeof Worker !== 'undefined' &&
@@ -434,29 +436,99 @@ export class Compositor {
     const transform = layer.transform;
     const sourceWidth = layer.source.width ?? this.width;
     const sourceHeight = layer.source.height ?? this.height;
+    const effectiveFitMode =
+      layer.fitMode === undefined || layer.fitMode === 'auto' ? this.fitMode : layer.fitMode;
+
+    let fittedWidth = sourceWidth;
+    let fittedHeight = sourceHeight;
+    let fittedX = 0;
+    let fittedY = 0;
+
+    if (sourceWidth === 0 || sourceHeight === 0) {
+      fittedWidth = this.width;
+      fittedHeight = this.height;
+    } else if (effectiveFitMode === 'none') {
+      fittedWidth = sourceWidth;
+      fittedHeight = sourceHeight;
+      fittedX = (this.width - fittedWidth) / 2;
+      fittedY = (this.height - fittedHeight) / 2;
+    } else {
+      const sourceAspect = sourceWidth / sourceHeight;
+      const canvasAspect = this.width / this.height;
+
+      switch (effectiveFitMode) {
+        case 'fill':
+          // Stretch to fill canvas - ignore aspect ratio
+          fittedWidth = this.width;
+          fittedHeight = this.height;
+          break;
+
+        case 'cover':
+          // Scale to cover entire canvas - may crop
+          if (sourceAspect > canvasAspect) {
+            fittedHeight = this.height;
+            fittedWidth = this.height * sourceAspect;
+            fittedX = (this.width - fittedWidth) / 2;
+          } else {
+            fittedWidth = this.width;
+            fittedHeight = this.width / sourceAspect;
+            fittedY = (this.height - fittedHeight) / 2;
+          }
+          break;
+
+        default:
+          // Scale to fit entirely within canvas - may letterbox
+          if (sourceAspect > canvasAspect) {
+            fittedWidth = this.width;
+            fittedHeight = this.width / sourceAspect;
+            fittedY = (this.height - fittedHeight) / 2;
+          } else {
+            fittedHeight = this.height;
+            fittedWidth = this.height * sourceAspect;
+            fittedX = (this.width - fittedWidth) / 2;
+          }
+          break;
+      }
+    }
 
-    // Fast path: no transform object means draw at origin with source dimensions
     if (!transform) {
-      ctx.drawImage(image, 0, 0, sourceWidth, sourceHeight);
+      ctx.drawImage(image, fittedX, fittedY, fittedWidth, fittedHeight);
       return;
     }
 
-    const destWidth = transform.width ?? sourceWidth;
-    const destHeight = transform.height ?? sourceHeight;
-    const x = transform.x ?? 0;
-    const y = transform.y ?? 0;
+    const x = (transform.x ?? 0) + fittedX;
+    const y = (transform.y ?? 0) + fittedY;
+    const destWidth = transform.width ?? fittedWidth;
+    const destHeight = transform.height ?? fittedHeight;
     const rotation = transform.rotation ?? 0;
     const scaleX = transform.scaleX ?? 1;
     const scaleY = transform.scaleY ?? 1;
     const opacity = transform.opacity ?? 1;
+    const filter = transform.filter;
 
     // Check if we need context state changes
     const needsOpacity = opacity !== 1;
     const needsTransform = rotation !== 0 || scaleX !== 1 || scaleY !== 1;
+    const needsFilter = !!filter && filter !== 'none';
+    const needsContextState = needsOpacity || needsTransform || needsFilter;
 
     // Fast path: simple position/size only, no rotation/scale/opacity
-    if (!needsOpacity && !needsTransform) {
+    if (!needsContextState) {
+      ctx.drawImage(image, x, y, destWidth, destHeight);
+      return;
+    }
+
+    // If we only need opacity/filter but no transforms, avoid translate/rotate work
+    if (!needsTransform) {
+      ctx.save();
+      if (needsOpacity) {
+        ctx.globalAlpha = opacity;
+      }
+      if (needsFilter) {
+        ctx.filter = filter;
+      }
       ctx.drawImage(image, x, y, destWidth, destHeight);
+      ctx.restore();
       return;
     }
 
@@ -470,6 +542,10 @@ export class Compositor {
       ctx.globalAlpha = opacity;
     }
 
+    if (needsFilter) {
+      ctx.filter = filter;
+    }
+
     // Move to layer position
     ctx.translate(x + destWidth * anchorX, y + destHeight * anchorY);
 
@@ -556,6 +632,7 @@ export class Compositor {
         sourceId,
         sourceTime: layer.sourceTime,
         transform: layer.transform,
+        fitMode: layer.fitMode,
         visible: layer.visible,
         zIndex: layer.zIndex,
       };
@@ -606,6 +683,12 @@ export class Compositor {
       throw new Error('No preview configured. Call preview() first.');
     }
 
+    // If currently seeking, queue play to execute after seek completes
+    if (this.state.seeking) {
+      this.pendingPlayAfterSeek = true;
+      return;
+    }
+
     this.state.playing = true;
     this.lastFrameTime = performance.now();
     this.lastRenderTime = this.lastFrameTime;
@@ -616,6 +699,11 @@ export class Compositor {
       // Reset active audio tracking so sources restart after pause/seek.
       this.activeAudioSourceIds.clear();
       await this.audioManager.play(this.state.currentTime);
+
+      // Process audio layers immediately to start sources right away
+      // instead of waiting for render loop which might skip first frame
+      const frame = this.previewOptions.getComposition(this.state.currentTime);
+      this.processAudioLayers(frame.audio ?? [], this.state.currentTime);
     }
 
     // Start render loop
@@ -630,6 +718,7 @@ export class Compositor {
     if (!this.state.playing) return;
 
     this.state.playing = false;
+    this.pendingPlayAfterSeek = false;
     this.stopRenderLoop();
     if (this.audioManager) {
       this.audioManager.pause();
@@ -654,15 +743,26 @@ export class Compositor {
     // Seek audio
     if (this.audioManager) {
       await this.audioManager.seek(clampedTime);
+      // Clear tracking so sources are treated as new and restarted
+      this.activeAudioSourceIds.clear();
     }
 
-    // Render frame at new time
+    // Render frame at new time and process audio layers during seek
     const frame = this.previewOptions.getComposition(clampedTime);
+    if (this.audioManager) {
+      this.processAudioLayers(frame.audio ?? [], clampedTime);
+    }
     await this.render(frame);
 
     this.state.seeking = false;
     this.emitter.emit('seeked', { time: clampedTime });
     this.emitter.emit('timeupdate', { currentTime: clampedTime });
+
+    // Execute pending play if one was queued during seek
+    if (this.pendingPlayAfterSeek) {
+      this.pendingPlayAfterSeek = false;
+      await this.play();
+    }
   }
 
   private startRenderLoop(): void {
@@ -820,22 +920,55 @@ export class Compositor {
 
   /**
    * Resizes the compositor canvas without disposing loaded sources.
+   * When worker mode is active, delegates resizing to the worker thread
+   * since the OffscreenCanvas cannot be resized from the main thread.
    * @param width - New width in pixels
    * @param height - New height in pixels
+   * @param fitMode - Optional fit mode for scaling sources to the canvas
    */
-  resize(width: number, height: number): void {
+  resize(width: number, height: number, fitMode?: FitMode): void {
     this.checkDisposed();
     this.width = width;
     this.height = height;
-    this.canvas.width = width;
-    this.canvas.height = height;
+    if (fitMode !== undefined) {
+      this.fitMode = fitMode;
+    }
+
+    // When worker mode is active, the canvas control has been transferred
+    // to OffscreenCanvas via transferControlToOffscreen(). Attempting to
+    // modify the HTMLCanvasElement's width/height would throw InvalidStateError.
+    // Delegate resizing entirely to the worker in this case.
     if (this.workerClient) {
-      void this.workerClient.resize(width, height);
+      void this.workerClient.resize(width, height, this.fitMode);
       return;
     }
+
+    // Main thread rendering: update DOM canvas dimensions directly
+    this.canvas.width = width;
+    this.canvas.height = height;
     this.clear();
   }
 
+  /**
+   * Sets the fit mode for scaling sources to the canvas.
+   * @param fitMode - The fit mode to use
+   */
+  setFitMode(fitMode: FitMode): void {
+    this.checkDisposed();
+    this.fitMode = fitMode;
+    if (this.workerClient) {
+      void this.workerClient.resize(this.width, this.height, fitMode);
+    }
+  }
+
+  /**
+   * Gets the current fit mode.
+   * @returns The current fit mode
+   */
+  getFitMode(): FitMode {
+    return this.fitMode;
+  }
+
   // Events
 
   /**

package/src/compositor/index.ts

@@ -12,7 +12,9 @@ export type {
   CompositorSource,
   CompositorSourceOptions,
   CompositorWorkerOptions,
+  FitMode,
   FrameExportOptions,
+  LayerFitMode,
   LayerTransform,
   PreviewOptions,
   SourceType,

package/src/compositor/types.ts

@@ -2,6 +2,15 @@ import type { RendererType, Rotation } from '../types';
 
 export type CompositorRendererType = RendererType;
 
+/**
+ * Fit mode for scaling video/image content within the compositor canvas.
+ * - `'fill'` (default): Stretch to exactly fill the canvas, ignoring aspect ratio. May distort the image.
+ * - `'contain'`: Scale to fit entirely within the canvas, preserving aspect ratio. May result in letterboxing/pillarboxing.
+ * - `'cover'`: Scale to completely cover the canvas, preserving aspect ratio. Parts may be cropped.
+ */
+export type FitMode = 'contain' | 'cover' | 'fill';
+export type LayerFitMode = FitMode | 'none' | 'auto';
+
 export interface CompositorOptions {
   canvas: HTMLCanvasElement | OffscreenCanvas;
   width?: number;
@@ -10,6 +19,8 @@ export interface CompositorOptions {
   backgroundColor?: string;
   enableAudio?: boolean;
   worker?: boolean | CompositorWorkerOptions;
+  /** Initial fit mode for scaling sources to the canvas. Defaults to 'fill'. */
+  fitMode?: FitMode;
 }
 
 export interface LayerTransform {
@@ -23,12 +34,19 @@ export interface LayerTransform {
   opacity?: number;
   anchorX?: number;
   anchorY?: number;
+  /** CSS filter string applied to this layer (e.g. "brightness(1.1) contrast(1.05)"). */
+  filter?: string;
 }
 
 export interface CompositorLayer {
   source: CompositorSource;
   sourceTime?: number;
   transform?: LayerTransform;
+  /**
+   * Fit mode override for this layer. Use 'auto' or leave undefined to use the
+   * compositor's global fitMode, or 'none' to render at the source's original size.
+   */
+  fitMode?: LayerFitMode;
   visible?: boolean;
   zIndex?: number;
 }

package/src/compositor/worker-client.ts

@@ -1,5 +1,5 @@
 import type { MediaSource } from '../types';
-import type { CompositorWorkerOptions, CompositorSourceOptions, FrameExportOptions } from './types';
+import type { CompositorSourceOptions, CompositorWorkerOptions, FrameExportOptions } from './types';
 import type {
   CompositorWorkerExportPayload,
   CompositorWorkerFrame,
@@ -32,10 +32,9 @@ export class CompositorWorkerClient {
   private ready: Promise<void>;
 
   constructor(options: CompositorWorkerClientOptions) {
-    const workerOptions = typeof options.worker === 'boolean' ? {} : options.worker ?? {};
+    const workerOptions = typeof options.worker === 'boolean' ? {} : (options.worker ?? {});
     const workerType = workerOptions.type ?? 'module';
-    const workerUrl =
-      workerOptions.url ?? new URL('./compositor-worker.js', import.meta.url);
+    const workerUrl = workerOptions.url ?? new URL('./compositor-worker.js', import.meta.url);
 
     this.worker = new Worker(workerUrl, { type: workerType });
     this.worker.onmessage = (event: MessageEvent<CompositorWorkerResponse>) => {
@@ -115,9 +114,9 @@ export class CompositorWorkerClient {
     return this.call<boolean>('clear');
   }
 
-  async resize(width: number, height: number): Promise<boolean> {
+  async resize(width: number, height: number, fitMode?: 'contain' | 'cover' | 'fill'): Promise<boolean> {
     await this.ready;
-    const payload: CompositorWorkerResizePayload = { width, height };
+    const payload: CompositorWorkerResizePayload = { width, height, fitMode };
     return this.call<boolean>('resize', payload);
   }
 

package/src/compositor/worker-types.ts

@@ -1,10 +1,11 @@
 import type { MediaSource } from '../types';
-import type { FrameExportOptions, LayerTransform, CompositorSourceOptions, SourceType } from './types';
+import type { CompositorSourceOptions, FrameExportOptions, LayerFitMode, LayerTransform, SourceType } from './types';
 
 export interface CompositorWorkerLayer {
   sourceId: string;
   sourceTime?: number;
   transform?: LayerTransform;
+  fitMode?: LayerFitMode;
   visible?: boolean;
   zIndex?: number;
 }
@@ -59,6 +60,7 @@ export interface CompositorWorkerRenderPayload {
 export interface CompositorWorkerResizePayload {
   width: number;
   height: number;
+  fitMode?: 'contain' | 'cover' | 'fill';
 }
 
 export interface CompositorWorkerExportPayload {

package/src/index.ts

@@ -26,7 +26,9 @@ export type {
   CompositorSource,
   CompositorSourceOptions,
   CompositorWorkerOptions,
+  FitMode,
   FrameExportOptions,
+  LayerFitMode,
   LayerTransform,
   PreviewOptions,
   SourceType,