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

package/dist/platform.js

@@ -41,36 +41,12 @@ exports.prebuiltPlatforms = void 0;
 exports.runtimePlatformArch = runtimePlatformArch;
 exports.buildPlatformArch = buildPlatformArch;
 exports.isPrebuiltAvailable = isPrebuiltAvailable;
-exports.getPrebuiltPackageName = getPrebuiltPackageName;
-exports.getFFmpegPackageName = getFFmpegPackageName;
 const os = __importStar(require("node:os"));
-// Try to detect musl vs glibc on Linux
-function detectLibc() {
-    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.
  */
 function runtimePlatformArch() {
-    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()}`;
 }
 /**
  * Get the build-time platform-architecture string.
@@ -92,8 +68,6 @@ exports.prebuiltPlatforms = [
     'darwin-arm64',
     'darwin-x64',
     'linux-x64',
-    'linuxmusl-x64',
-    'win32-x64',
 ];
 /**
  * Check if a prebuilt binary is available for the current platform.
@@ -102,15 +76,3 @@ function isPrebuiltAvailable() {
     const platform = runtimePlatformArch();
     return exports.prebuiltPlatforms.includes(platform);
 }
-/**
- * Get the npm package name for the prebuilt binary.
- */
-function getPrebuiltPackageName() {
-    return `@pproenca/node-webcodecs-${runtimePlatformArch()}`;
-}
-/**
- * Get the npm package name for prebuilt FFmpeg.
- */
-function getFFmpegPackageName() {
-    return `@pproenca/ffmpeg-${runtimePlatformArch()}`;
-}

package/dist/resource-manager.d.ts

@@ -15,7 +15,6 @@ export declare class ResourceManager {
     private static instance;
     private codecs;
     private inactivityTimeout;
-    private checkInterval;
     private constructor();
     static getInstance(): ResourceManager;
     /**
@@ -51,9 +50,9 @@ export declare class ResourceManager {
      * Set inactivity timeout (for testing).
      */
     setInactivityTimeout(ms: number): void;
-    private startMonitoring;
     /**
      * Stop monitoring (for cleanup).
+     * @deprecated No longer needed - monitoring happens on-demand via getReclaimableCodecs()
      */
     stopMonitoring(): void;
 }

package/dist/resource-manager.js

@@ -11,8 +11,7 @@ class ResourceManager {
     constructor() {
         this.codecs = new Map();
         this.inactivityTimeout = 10000; // 10 seconds per spec
-        this.checkInterval = null;
-        this.startMonitoring();
+        // Monitoring happens on-demand via getReclaimableCodecs()
     }
     static getInstance() {
         if (!ResourceManager.instance) {
@@ -104,25 +103,12 @@ class ResourceManager {
     setInactivityTimeout(ms) {
         this.inactivityTimeout = ms;
     }
-    startMonitoring() {
-        // 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() {
-        if (this.checkInterval) {
-            clearInterval(this.checkInterval);
-            this.checkInterval = null;
-        }
+        // No-op: monitoring now happens on-demand
     }
 }
 exports.ResourceManager = ResourceManager;

package/dist/resource-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-manager.js","sourceRoot":"","sources":["../lib/resource-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-manager.js","sourceRoot":"","sources":["../lib/resource-manager.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -54,6 +54,16 @@ export type HardwareAcceleration = 'no-preference' | 'prefer-hardware' | 'prefer
  * enum AlphaOption { "keep", "discard" };
  */
 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';
 /**
  * WebIDL:
  * enum LatencyMode { "quality", "realtime" };
@@ -561,6 +571,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;
@@ -571,6 +582,7 @@ export interface ImageDecoderInit {
     type: string;
     data: ImageBufferSource;
     colorSpaceConversion?: ColorSpaceConversion;
+    premultiplyAlpha?: PremultiplyAlpha;
     desiredWidth?: number;
     desiredHeight?: number;
     preferAnimation?: boolean;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":""}

package/dist/video-decoder.d.ts

@@ -13,10 +13,31 @@ export declare class VideoDecoder extends CodecBase {
     private _needsKeyFrame;
     private _errorCallback;
     private _resourceId;
+    private _maxQueueDepth;
     constructor(init: VideoDecoderInit);
     get state(): CodecState;
     get decodeQueueSize(): number;
     get codecSaturated(): boolean;
+    /**
+     * 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>;
+    /**
+     * The maximum queue depth before backpressure is applied.
+     * Default is 16. Adjust based on memory constraints and frame size.
+     */
+    get maxQueueDepth(): number;
+    set maxQueueDepth(value: number);
     configure(config: VideoDecoderConfig): void;
     decode(chunk: EncodedVideoChunk): void;
     flush(): Promise<void>;

package/dist/video-decoder.js

@@ -47,11 +47,15 @@ const resource_manager_1 = require("./resource-manager");
 const video_frame_1 = require("./video-frame");
 // Load native addon with type assertion
 const native = binding_1.binding;
+// Default backpressure threshold for limiting in-flight chunks
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
 class VideoDecoder extends codec_base_1.CodecBase {
     constructor(init) {
         super();
         this._decodeQueueSize = 0;
         this._needsKeyFrame = true;
+        // Backpressure support
+        this._maxQueueDepth = DEFAULT_MAX_QUEUE_DEPTH;
         // W3C spec: output and error callbacks are required
         is.assertPlainObject(init, 'init');
         is.assertFunction(init.output, 'init.output');
@@ -61,7 +65,6 @@ class VideoDecoder extends codec_base_1.CodecBase {
         this._controlQueue.setErrorHandler(init.error);
         this._resourceId = resource_manager_1.ResourceManager.getInstance().register(this);
         const outputCallback = (nativeFrame) => {
-            // Decrement queue size when output received
             this._decodeQueueSize = Math.max(0, this._decodeQueueSize - 1);
             // Wrap the native frame as a VideoFrame
             // biome-ignore lint/suspicious/noExplicitAny: Object.create wrapper pattern requires any for property assignment
@@ -87,11 +90,72 @@ class VideoDecoder extends codec_base_1.CodecBase {
     get codecSaturated() {
         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() {
+        // 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((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() {
+        return this._maxQueueDepth;
+    }
+    set maxQueueDepth(value) {
+        if (value < 1) {
+            throw new RangeError('maxQueueDepth must be at least 1');
+        }
+        this._maxQueueDepth = value;
+    }
     configure(config) {
         // 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);
@@ -121,7 +185,15 @@ class VideoDecoder extends codec_base_1.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() {
         // W3C spec: throw InvalidStateError if closed

package/dist/video-encoder.d.ts

@@ -11,10 +11,32 @@ export declare class VideoEncoder extends CodecBase {
     private _controlQueue;
     private _encodeQueueSize;
     private _resourceId;
+    private _maxQueueDepth;
     constructor(init: VideoEncoderInit);
     get state(): CodecState;
     get encodeQueueSize(): number;
     get codecSaturated(): boolean;
+    /**
+     * 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>;
+    /**
+     * The maximum queue depth before backpressure is applied.
+     * Default is 16. Adjust based on memory constraints and frame size.
+     */
+    get maxQueueDepth(): number;
+    set maxQueueDepth(value: number);
     configure(config: VideoEncoderConfig): void;
     encode(frame: VideoFrame, options?: {
         keyFrame?: boolean;

package/dist/video-encoder.js

@@ -47,10 +47,14 @@ const is = __importStar(require("./is"));
 const resource_manager_1 = require("./resource-manager");
 // Load native addon with type assertion
 const native = binding_1.binding;
+// Default backpressure threshold for limiting in-flight frames
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
 class VideoEncoder extends codec_base_1.CodecBase {
     constructor(init) {
         super();
         this._encodeQueueSize = 0;
+        // Backpressure support
+        this._maxQueueDepth = DEFAULT_MAX_QUEUE_DEPTH;
         // W3C spec: output and error callbacks are required
         is.assertPlainObject(init, 'init');
         is.assertFunction(init.output, 'init.output');
@@ -59,14 +63,25 @@ class VideoEncoder extends codec_base_1.CodecBase {
         this._controlQueue.setErrorHandler(init.error);
         this._resourceId = resource_manager_1.ResourceManager.getInstance().register(this);
         const outputCallback = (chunk, metadata) => {
-            // Decrement queue size when output received
             this._encodeQueueSize = Math.max(0, this._encodeQueueSize - 1);
-            const wrappedChunk = new encoded_chunks_1.EncodedVideoChunk({
-                type: chunk.type,
-                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;
+            if ('data' in chunk && chunk.data instanceof Buffer) {
+                // Legacy path: plain object from sync encoder - wrap it
+                wrappedChunk = new encoded_chunks_1.EncodedVideoChunk({
+                    type: chunk.type,
+                    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 = encoded_chunks_1.EncodedVideoChunk._fromNative(chunk);
+            }
             init.output(wrappedChunk, metadata);
             // Fire ondequeue after output
             this._triggerDequeue();
@@ -85,6 +100,56 @@ class VideoEncoder extends codec_base_1.CodecBase {
     get codecSaturated() {
         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() {
+        // 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((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() {
+        return this._maxQueueDepth;
+    }
+    set maxQueueDepth(value) {
+        if (value < 1) {
+            throw new RangeError('maxQueueDepth must be at least 1');
+        }
+        this._maxQueueDepth = value;
+    }
     configure(config) {
         // W3C spec: throw if closed
         if (this.state === 'closed') {
@@ -98,6 +163,10 @@ class VideoEncoder extends codec_base_1.CodecBase {
         this._native.configure(config);
     }
     encode(frame, options) {
+        // W3C spec: throw if not configured
+        if (this.state !== 'configured') {
+            throw new DOMException(`Encoder is ${this.state}`, 'InvalidStateError');
+        }
         resource_manager_1.ResourceManager.getInstance().recordActivity(this._resourceId);
         this._encodeQueueSize++;
         // Call native encode directly - frame must be valid at call time
@@ -116,11 +185,17 @@ class VideoEncoder extends codec_base_1.CodecBase {
         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.pendingChunks > 0) {
-            await new Promise((resolve) => setImmediate(resolve));
+            await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
         }
     }
     reset() {
+        // 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();

package/lib/audio-decoder.ts

@@ -30,7 +30,6 @@ export class AudioDecoder extends CodecBase {
     this._controlQueue.setErrorHandler(init.error);
 
     const outputCallback: AudioDecoderOutputCallback = (nativeData) => {
-      // Decrement queue size when output received
       this._decodeQueueSize = Math.max(0, this._decodeQueueSize - 1);
 
       // biome-ignore lint/suspicious/noExplicitAny: Object.create wrapper pattern requires any for property assignment
@@ -76,7 +75,7 @@ export class AudioDecoder extends CodecBase {
   decode(chunk: EncodedAudioChunk): void {
     // W3C spec: throw InvalidStateError if not configured
     if (this.state === 'unconfigured') {
-      throw new DOMException('Decoder is not configured', 'InvalidStateError');
+      throw new DOMException('Decoder is unconfigured', 'InvalidStateError');
     }
     if (this.state === 'closed') {
       throw new DOMException('Decoder is closed', 'InvalidStateError');

package/lib/audio-encoder.ts

@@ -21,10 +21,13 @@ import type { AudioEncoderConfig, AudioEncoderInit, CodecState } from './types';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class AudioEncoder extends CodecBase {
   private _native: NativeAudioEncoder;
   private _controlQueue: ControlMessageQueue;
   private _encodeQueueSize: number = 0;
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
 
   constructor(init: AudioEncoderInit) {
     super();
@@ -38,7 +41,6 @@ export class AudioEncoder extends CodecBase {
     this._controlQueue.setErrorHandler(init.error);
 
     const outputCallback: AudioEncoderOutputCallback = (chunk, metadata) => {
-      // Decrement queue size when output received
       this._encodeQueueSize = Math.max(0, this._encodeQueueSize - 1);
 
       // biome-ignore lint/suspicious/noExplicitAny: Object.create wrapper pattern requires any for property assignment
@@ -68,6 +70,33 @@ export class AudioEncoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  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;
+  }
+
+  get ready(): Promise<void> {
+    if (this._encodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._encodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
   configure(config: AudioEncoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
@@ -86,7 +115,7 @@ export class AudioEncoder extends CodecBase {
   encode(data: AudioData): void {
     // W3C spec: throw InvalidStateError if not configured
     if (this.state === 'unconfigured') {
-      throw new DOMException('Encoder is not configured', 'InvalidStateError');
+      throw new DOMException('Encoder is unconfigured', 'InvalidStateError');
     }
     if (this.state === 'closed') {
       throw new DOMException('Encoder is closed', 'InvalidStateError');