@pproenca/node-webcodecs 0.1.1-alpha.0 → 0.1.1-alpha.5

package/lib/encoded-chunks.ts

@@ -10,11 +10,42 @@ import type {
   NativeEncodedVideoChunk,
   NativeModule,
 } from './native-types';
+import { detachArrayBuffers } from './transfer';
 import type { EncodedAudioChunkInit, EncodedVideoChunkInit } from './types';
 
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+/**
+ * FinalizationRegistry for automatic cleanup of native EncodedVideoChunk objects.
+ * When a JS EncodedVideoChunk wrapper becomes unreachable, the registry callback
+ * fires and releases the native memory via close().
+ *
+ * This provides a safety net for users who forget to call close(), preventing
+ * memory leaks in high-throughput scenarios where GC may be delayed.
+ */
+const videoChunkRegistry = new FinalizationRegistry<NativeEncodedVideoChunk>((native) => {
+  // The weak reference to the JS wrapper is now dead, but the native object
+  // may still be valid. Call close() to release its internal data buffer.
+  // close() is idempotent - safe to call even if already closed.
+  try {
+    native.close();
+  } catch {
+    // Ignore errors - native object may already be destroyed
+  }
+});
+
+/**
+ * FinalizationRegistry for automatic cleanup of native EncodedAudioChunk objects.
+ */
+const audioChunkRegistry = new FinalizationRegistry<NativeEncodedAudioChunk>((native) => {
+  try {
+    native.close();
+  } catch {
+    // Ignore errors - native object may already be destroyed
+  }
+});
+
 export class EncodedVideoChunk {
   /** @internal */
   _native: NativeEncodedVideoChunk;
@@ -24,7 +55,6 @@ export class EncodedVideoChunk {
     if (init.type !== 'key' && init.type !== 'delta') {
       throw new TypeError(`Invalid type: ${init.type}`);
     }
-    // Convert BufferSource to Buffer for native
     let dataBuffer: Buffer;
     if (init.data instanceof ArrayBuffer) {
       dataBuffer = Buffer.from(init.data);
@@ -39,6 +69,29 @@ export class EncodedVideoChunk {
       duration: init.duration,
       data: dataBuffer,
     });
+
+    // Register with FinalizationRegistry for automatic cleanup.
+    // When this JS wrapper is GC'd, the registry callback will call close()
+    // on the native object to release memory.
+    videoChunkRegistry.register(this, this._native, this);
+
+    // Handle ArrayBuffer transfer semantics per W3C spec
+    if (init.transfer && Array.isArray(init.transfer)) {
+      detachArrayBuffers(init.transfer.filter((b): b is ArrayBuffer => b instanceof ArrayBuffer));
+    }
+  }
+
+  /**
+   * @internal
+   * Wrap an existing native EncodedVideoChunk without copying data.
+   * Used by the encoder's async output path to avoid double-copying.
+   */
+  static _fromNative(nativeChunk: NativeEncodedVideoChunk): EncodedVideoChunk {
+    const chunk = Object.create(EncodedVideoChunk.prototype) as EncodedVideoChunk;
+    chunk._native = nativeChunk;
+    // Register with FinalizationRegistry for automatic cleanup
+    videoChunkRegistry.register(chunk, nativeChunk, chunk);
+    return chunk;
   }
 
   get type(): 'key' | 'delta' {
@@ -75,13 +128,28 @@ export class EncodedVideoChunk {
       throw new TypeError('Destination must be ArrayBuffer or ArrayBufferView');
     }
   }
+
+  /**
+   * Releases the internal data buffer.
+   * Per W3C WebCodecs spec, this allows early release of memory.
+   */
+  close(): void {
+    // Unregister from FinalizationRegistry to prevent double-close.
+    // If close() is called explicitly, we don't need the registry callback.
+    videoChunkRegistry.unregister(this);
+    this._native.close();
+  }
 }
 
 export class EncodedAudioChunk {
   private _native: NativeEncodedAudioChunk;
 
   constructor(init: EncodedAudioChunkInit) {
-    // Convert BufferSource to Buffer for native
+    // W3C spec: type must be 'key' or 'delta'
+    if (init.type !== 'key' && init.type !== 'delta') {
+      throw new TypeError(`Invalid type: ${init.type}`);
+    }
+
     let dataBuffer: Buffer;
     if (init.data instanceof ArrayBuffer) {
       dataBuffer = Buffer.from(init.data);
@@ -96,6 +164,16 @@ export class EncodedAudioChunk {
       duration: init.duration,
       data: dataBuffer,
     });
+
+    // Register with FinalizationRegistry for automatic cleanup.
+    // When this JS wrapper is GC'd, the registry callback will call close()
+    // on the native object to release memory.
+    audioChunkRegistry.register(this, this._native, this);
+
+    // Handle ArrayBuffer transfer semantics per W3C spec
+    if (init.transfer && Array.isArray(init.transfer)) {
+      detachArrayBuffers(init.transfer.filter((b): b is ArrayBuffer => b instanceof ArrayBuffer));
+    }
   }
 
   get type(): 'key' | 'delta' {
@@ -128,6 +206,16 @@ export class EncodedAudioChunk {
     }
   }
 
+  /**
+   * Releases the internal data buffer.
+   * Per W3C WebCodecs spec, this allows early release of memory.
+   */
+  close(): void {
+    // Unregister from FinalizationRegistry to prevent double-close.
+    audioChunkRegistry.unregister(this);
+    this._native.close();
+  }
+
   get _nativeChunk(): NativeEncodedAudioChunk {
     return this._native;
   }

package/lib/image-decoder.ts

@@ -49,6 +49,7 @@ export class ImageDecoder {
     this._initOptions = {
       type: init.type,
       colorSpaceConversion: init.colorSpaceConversion,
+      premultiplyAlpha: init.premultiplyAlpha,
       desiredWidth: init.desiredWidth,
       desiredHeight: init.desiredHeight,
       preferAnimation: init.preferAnimation,
@@ -86,6 +87,7 @@ export class ImageDecoder {
       type: string;
       data: Buffer;
       colorSpaceConversion?: string;
+      premultiplyAlpha?: string;
       desiredWidth?: number;
       desiredHeight?: number;
       preferAnimation?: boolean;
@@ -98,6 +100,9 @@ export class ImageDecoder {
     if ('colorSpaceConversion' in init && init.colorSpaceConversion) {
       nativeInit.colorSpaceConversion = init.colorSpaceConversion;
     }
+    if ('premultiplyAlpha' in init && init.premultiplyAlpha !== undefined) {
+      nativeInit.premultiplyAlpha = init.premultiplyAlpha;
+    }
     if ('desiredWidth' in init && init.desiredWidth !== undefined) {
       nativeInit.desiredWidth = init.desiredWidth;
     }

package/lib/index.ts

@@ -47,6 +47,9 @@ export const ErrorBuilder = native.ErrorBuilder;
 export const testAttrAsEnum = native.testAttrAsEnum;
 export const createEncoderConfigDescriptor = native.createEncoderConfigDescriptor;
 
+// Export instance counters for monitoring and leak detection
+export const getCounters = native.getCounters;
+
 export type { ErrorCodeType } from './errors';
 // Re-export error classes and codes
 export {

package/lib/native-types.ts

@@ -80,6 +80,7 @@ export interface NativeVideoDecoder {
   readonly state: CodecState;
   readonly decodeQueueSize: number;
   readonly codecSaturated: boolean;
+  readonly pendingFrames: number;
 
   configure(config: VideoDecoderConfig): void;
   decode(chunk: NativeEncodedVideoChunk): void;
@@ -98,6 +99,7 @@ export interface NativeEncodedVideoChunk {
   readonly byteLength: number;
 
   copyTo(dest: Uint8Array | ArrayBuffer): void;
+  close(): void;
 }
 
 /**
@@ -127,6 +129,7 @@ export interface NativeEncodedAudioChunk {
   readonly byteLength: number;
 
   copyTo(dest: Uint8Array | ArrayBuffer): void;
+  close(): void;
 }
 
 /**
@@ -173,6 +176,12 @@ export interface NativeVideoFilter {
 export interface NativeDemuxer {
   open(path: string): void;
   demux(): void;
+  /**
+   * Read packets from the file in chunks.
+   * @param maxPackets - Maximum number of packets to read. 0 = unlimited.
+   * @returns The number of packets actually read.
+   */
+  demuxPackets(maxPackets: number): number;
   close(): void;
   getVideoTrack(): TrackInfo | null;
   getAudioTrack(): TrackInfo | null;
@@ -509,6 +518,19 @@ export interface NativeModule {
   // Test helpers
   testAttrAsEnum: (obj: object, attr: string) => string;
 
+  // Instance counters for monitoring and leak detection
+  getCounters: () => {
+    videoFrames: number;
+    audioData: number;
+    videoEncoders: number;
+    videoDecoders: number;
+    audioEncoders: number;
+    audioDecoders: number;
+    queue: number;
+    process: number;
+    frames: number;
+  };
+
   // Descriptor factories
   createEncoderConfigDescriptor: (config: object) => {
     codec: string;

package/lib/platform.ts

@@ -5,35 +5,11 @@
 
 import * as os from 'node:os';
 
-// Try to detect musl vs glibc on Linux
-function detectLibc(): 'glibc' | 'musl' | null {
-  if (os.platform() !== 'linux') return null;
-
-  try {
-    const { familySync } = require('detect-libc');
-    return familySync() === 'musl' ? 'musl' : 'glibc';
-  } catch {
-    // detect-libc not available, assume glibc
-    return 'glibc';
-  }
-}
-
 /**
  * Get the runtime platform-architecture string.
- * Handles musl vs glibc distinction on Linux.
  */
 export function runtimePlatformArch(): string {
-  const platform = os.platform();
-  const arch = os.arch();
-
-  if (platform === 'linux') {
-    const libc = detectLibc();
-    if (libc === 'musl') {
-      return `linuxmusl-${arch}`;
-    }
-  }
-
-  return `${platform}-${arch}`;
+  return `${os.platform()}-${os.arch()}`;
 }
 
 /**
@@ -57,8 +33,6 @@ export const prebuiltPlatforms = [
   'darwin-arm64',
   'darwin-x64',
   'linux-x64',
-  'linuxmusl-x64',
-  'win32-x64',
 ] as const;
 
 export type PrebuiltPlatform = (typeof prebuiltPlatforms)[number];
@@ -70,17 +44,3 @@ export function isPrebuiltAvailable(): boolean {
   const platform = runtimePlatformArch();
   return prebuiltPlatforms.includes(platform as PrebuiltPlatform);
 }
-
-/**
- * Get the npm package name for the prebuilt binary.
- */
-export function getPrebuiltPackageName(): string {
-  return `@pproenca/node-webcodecs-${runtimePlatformArch()}`;
-}
-
-/**
- * Get the npm package name for prebuilt FFmpeg.
- */
-export function getFFmpegPackageName(): string {
-  return `@pproenca/ffmpeg-${runtimePlatformArch()}`;
-}

package/lib/resource-manager.ts

@@ -23,10 +23,9 @@ export class ResourceManager {
   private static instance: ResourceManager | null = null;
   private codecs: Map<symbol, CodecEntry> = new Map();
   private inactivityTimeout: number = 10000; // 10 seconds per spec
-  private checkInterval: ReturnType<typeof setInterval> | null = null;
 
   private constructor() {
-    this.startMonitoring();
+    // Monitoring happens on-demand via getReclaimableCodecs()
   }
 
   static getInstance(): ResourceManager {
@@ -132,26 +131,11 @@ export class ResourceManager {
     this.inactivityTimeout = ms;
   }
 
-  private startMonitoring(): void {
-    // Check every 5 seconds
-    this.checkInterval = setInterval(() => {
-      // Just track, don't auto-reclaim
-      // Actual reclamation would be triggered by memory pressure
-    }, 5000);
-
-    // Don't keep process alive
-    if (this.checkInterval.unref) {
-      this.checkInterval.unref();
-    }
-  }
-
   /**
    * Stop monitoring (for cleanup).
+   * @deprecated No longer needed - monitoring happens on-demand via getReclaimableCodecs()
    */
   stopMonitoring(): void {
-    if (this.checkInterval) {
-      clearInterval(this.checkInterval);
-      this.checkInterval = null;
-    }
+    // No-op: monitoring now happens on-demand
   }
 }

package/lib/types.ts

@@ -82,6 +82,17 @@ export type HardwareAcceleration = 'no-preference' | 'prefer-hardware' | 'prefer
  */
 export type AlphaOption = 'keep' | 'discard';
 
+/**
+ * WebIDL:
+ * enum PremultiplyAlpha { "none", "premultiply", "default" };
+ *
+ * Per W3C WebCodecs spec:
+ * - "none": Do not premultiply alpha
+ * - "premultiply": Premultiply RGB values by alpha
+ * - "default": Use default behavior (typically none)
+ */
+export type PremultiplyAlpha = 'none' | 'premultiply' | 'default';
+
 // =============================================================================
 // LATENCY MODE
 // =============================================================================
@@ -816,6 +827,7 @@ export type ImageBufferSource = AllowSharedBufferSource | ReadableStream<Uint8Ar
  *   required DOMString type;
  *   required ImageBufferSource data;
  *   ColorSpaceConversion colorSpaceConversion = "default";
+ *   PremultiplyAlpha premultiplyAlpha = "default";
  *   [EnforceRange] unsigned long desiredWidth;
  *   [EnforceRange] unsigned long desiredHeight;
  *   boolean preferAnimation;
@@ -826,6 +838,7 @@ export interface ImageDecoderInit {
   type: string;
   data: ImageBufferSource;
   colorSpaceConversion?: ColorSpaceConversion;
+  premultiplyAlpha?: PremultiplyAlpha;
   desiredWidth?: number;
   desiredHeight?: number;
   preferAnimation?: boolean;

package/lib/video-decoder.ts

@@ -17,6 +17,9 @@ import { VideoFrame } from './video-frame';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+// Default backpressure threshold for limiting in-flight chunks
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class VideoDecoder extends CodecBase {
   private _native: NativeVideoDecoder;
   private _controlQueue: ControlMessageQueue;
@@ -25,6 +28,9 @@ export class VideoDecoder extends CodecBase {
   private _errorCallback: (error: DOMException) => void;
   private _resourceId: symbol;
 
+  // Backpressure support
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
+
   constructor(init: VideoDecoderInit) {
     super();
     // W3C spec: output and error callbacks are required
@@ -38,7 +44,6 @@ export class VideoDecoder extends CodecBase {
     this._resourceId = ResourceManager.getInstance().register(this);
 
     const outputCallback: VideoDecoderOutputCallback = (nativeFrame) => {
-      // Decrement queue size when output received
       this._decodeQueueSize = Math.max(0, this._decodeQueueSize - 1);
 
       // Wrap the native frame as a VideoFrame
@@ -71,11 +76,78 @@ export class VideoDecoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  /**
+   * Returns a Promise that resolves when the decoder has capacity for more chunks.
+   * Use this to implement backpressure in high-throughput decoding pipelines.
+   *
+   * When the internal queue is full (decodeQueueSize >= maxQueueDepth), calling
+   * `await decoder.ready` will pause until capacity is available.
+   *
+   * @example
+   * for (const chunk of chunks) {
+   *   await decoder.ready;  // Wait for capacity
+   *   decoder.decode(chunk);
+   * }
+   */
+  get ready(): Promise<void> {
+    // If we have capacity, resolve immediately
+    if (this._decodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+
+    // Otherwise, poll until capacity is available.
+    // We use setTimeout(1ms) polling to allow TSFN output callbacks to execute.
+    // setTimeout ensures we yield through the full event loop cycle, including
+    // the I/O phase where TSFN callbacks are delivered.
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._decodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          // Yield full event loop cycle to allow output callbacks to run
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      // Initial yield to allow any pending callbacks to run
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
+  /**
+   * The maximum queue depth before backpressure is applied.
+   * Default is 16. Adjust based on memory constraints and frame size.
+   */
+  get maxQueueDepth(): number {
+    return this._maxQueueDepth;
+  }
+
+  set maxQueueDepth(value: number) {
+    if (value < 1) {
+      throw new RangeError('maxQueueDepth must be at least 1');
+    }
+    this._maxQueueDepth = value;
+  }
+
   configure(config: VideoDecoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
       throw new DOMException('Decoder is closed', 'InvalidStateError');
     }
+
+    // Validate rotation (node-webcodecs extension)
+    if ('rotation' in config && config.rotation !== undefined) {
+      if (![0, 90, 180, 270].includes(config.rotation)) {
+        throw new TypeError(`rotation must be 0, 90, 180, or 270, got ${config.rotation}`);
+      }
+    }
+
+    // Validate flip (node-webcodecs extension)
+    if ('flip' in config && config.flip !== undefined) {
+      if (typeof config.flip !== 'boolean') {
+        throw new TypeError('flip must be a boolean');
+      }
+    }
+
     this._needsKeyFrame = true;
     // Configure synchronously to set state immediately per W3C spec
     this._native.configure(config);
@@ -111,7 +183,17 @@ export class VideoDecoder extends CodecBase {
       return Promise.reject(new DOMException('Decoder is closed', 'InvalidStateError'));
     }
     await this._controlQueue.flush();
-    return this._native.flush();
+
+    // Flush the native decoder (waits for worker queue to drain)
+    this._native.flush();
+
+    // Poll for pending TSFN callbacks to complete.
+    // This allows the event loop to run (delivering callbacks) while we wait.
+    // Using setTimeout(1ms) instead of setImmediate to ensure other event loop
+    // phases (timers, I/O) can run, preventing event loop starvation.
+    while (this._native.pendingFrames > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
+    }
   }
 
   reset(): void {

package/lib/video-encoder.ts

@@ -17,12 +17,18 @@ import type { VideoFrame } from './video-frame';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+// Default backpressure threshold for limiting in-flight frames
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class VideoEncoder extends CodecBase {
   private _native: NativeVideoEncoder;
   private _controlQueue: ControlMessageQueue;
   private _encodeQueueSize: number = 0;
   private _resourceId: symbol;
 
+  // Backpressure support
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
+
   constructor(init: VideoEncoderInit) {
     super();
     // W3C spec: output and error callbacks are required
@@ -35,19 +41,32 @@ export class VideoEncoder extends CodecBase {
     this._resourceId = ResourceManager.getInstance().register(this);
 
     const outputCallback: VideoEncoderOutputCallback = (chunk, metadata) => {
-      // Decrement queue size when output received
       this._encodeQueueSize = Math.max(0, this._encodeQueueSize - 1);
 
-      const wrappedChunk = new EncodedVideoChunk({
-        type: chunk.type as 'key' | 'delta',
-        timestamp: chunk.timestamp,
-        duration: chunk.duration ?? undefined,
-        data: chunk.data,
-      });
+      // The native layer now returns an EncodedVideoChunk directly (not a plain object).
+      // Check if it's already a native chunk (has close method) vs plain object (has data buffer).
+      // Native chunks have close() but no 'data' property; plain objects have 'data' buffer.
+      let wrappedChunk: EncodedVideoChunk;
+      if ('data' in chunk && chunk.data instanceof Buffer) {
+        // Legacy path: plain object from sync encoder - wrap it
+        wrappedChunk = new EncodedVideoChunk({
+          type: chunk.type as 'key' | 'delta',
+          timestamp: chunk.timestamp,
+          duration: chunk.duration ?? undefined,
+          data: chunk.data,
+        });
+      } else {
+        // New path: already a native EncodedVideoChunk from async encoder
+        // Wrap without copying data
+        wrappedChunk = EncodedVideoChunk._fromNative(
+          chunk as unknown as import('./native-types').NativeEncodedVideoChunk,
+        );
+      }
       init.output(wrappedChunk, metadata);
 
       // Fire ondequeue after output
       this._triggerDequeue();
+
     };
 
     this._native = new native.VideoEncoder({
@@ -68,6 +87,59 @@ export class VideoEncoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  /**
+   * Returns a Promise that resolves when the encoder has capacity for more frames.
+   * Use this to implement backpressure in high-throughput encoding pipelines.
+   *
+   * When the internal queue is full (encodeQueueSize >= maxQueueDepth), calling
+   * `await encoder.ready` will pause until capacity is available.
+   *
+   * @example
+   * for (const frame of frames) {
+   *   await encoder.ready;  // Wait for capacity
+   *   encoder.encode(frame);
+   *   frame.close();
+   * }
+   */
+  get ready(): Promise<void> {
+    // If we have capacity, resolve immediately
+    if (this._encodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+
+    // Otherwise, poll until capacity is available.
+    // We use setTimeout(1ms) polling to allow TSFN output callbacks to execute.
+    // setTimeout ensures we yield through the full event loop cycle, including
+    // the I/O phase where TSFN callbacks are delivered.
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._encodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          // Yield full event loop cycle to allow output callbacks to run
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      // Initial yield to allow any pending callbacks to run
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
+  /**
+   * The maximum queue depth before backpressure is applied.
+   * Default is 16. Adjust based on memory constraints and frame size.
+   */
+  get maxQueueDepth(): number {
+    return this._maxQueueDepth;
+  }
+
+  set maxQueueDepth(value: number) {
+    if (value < 1) {
+      throw new RangeError('maxQueueDepth must be at least 1');
+    }
+    this._maxQueueDepth = value;
+  }
+
   configure(config: VideoEncoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
@@ -84,6 +156,10 @@ export class VideoEncoder extends CodecBase {
   }
 
   encode(frame: VideoFrame, options?: { keyFrame?: boolean }): void {
+    // W3C spec: throw if not configured
+    if (this.state !== 'configured') {
+      throw new DOMException(`Encoder is ${this.state}`, 'InvalidStateError');
+    }
     ResourceManager.getInstance().recordActivity(this._resourceId);
     this._encodeQueueSize++;
     // Call native encode directly - frame must be valid at call time
@@ -105,12 +181,18 @@ export class VideoEncoder extends CodecBase {
 
     // Poll for pending TSFN callbacks to complete.
     // This allows the event loop to run (delivering callbacks) while we wait.
+    // Using setTimeout(1ms) instead of setImmediate to ensure other event loop
+    // phases (timers, I/O) can run, preventing event loop starvation.
     while (this._native.pendingChunks > 0) {
-      await new Promise((resolve) => setImmediate(resolve));
+      await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
     }
   }
 
   reset(): void {
+    // W3C spec: throw if closed
+    if (this.state === 'closed') {
+      throw new DOMException('Encoder is closed', 'InvalidStateError');
+    }
     this._controlQueue.clear();
     this._encodeQueueSize = 0;
     this._native.reset();