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

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');

package/lib/binding.ts

@@ -1,116 +1,59 @@
 // Copyright 2024 The node-webcodecs Authors
 // SPDX-License-Identifier: MIT
 //
-// Native binding loader with fallback chain and enhanced error messages.
+// Native binding loader using esbuild-style platform resolution.
+// Tries platform-specific package first, falls back to node-gyp-build for local dev.
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { getPrebuiltPackageName, isPrebuiltAvailable, runtimePlatformArch } from './platform';
+import { resolve, dirname, join } from 'node:path';
 
-const rootDir = path.resolve(__dirname, '..');
-
-type LoadCandidate = string | (() => unknown);
-
-const candidates: LoadCandidate[] = [
-  // Development build (node-gyp output)
-  path.join(rootDir, 'build', 'Release', 'node_webcodecs.node'),
-  path.join(rootDir, 'build', 'Debug', 'node_webcodecs.node'),
-
-  // node-gyp-build compatible
-  () => {
-    try {
-      return require('node-gyp-build')(rootDir);
-    } catch {
-      throw new Error('node-gyp-build not available');
-    }
-  },
-
-  // Prebuilt from platform package
-  () => {
-    const pkg = getPrebuiltPackageName();
-
-    return require(pkg);
-  },
-];
-
-function getPlatformBuildInstructions(): string {
-  const platform = process.platform;
-
-  if (platform === 'darwin') {
-    return `  brew install ffmpeg pkg-config
-  npm run build:native`;
-  }
-  if (platform === 'linux') {
-    return `  sudo apt-get install libavcodec-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev pkg-config
-  npm run build:native`;
-  }
-  if (platform === 'win32') {
-    return `  Download FFmpeg from https://github.com/BtbN/FFmpeg-Builds/releases
-  Set FFMPEG_PATH environment variable
-  npm run build:native`;
-  }
-  return `  Install FFmpeg development libraries
-  npm run build:native`;
-}
-
-function buildHelpMessage(errors: Array<{ path: string; error: Error }>): string {
-  const platform = runtimePlatformArch();
-  const hasPrebuilt = isPrebuiltAvailable();
-
-  let msg = `Could not load native binding for ${platform}.\n\n`;
-  msg += `Node.js: ${process.version}\n\n`;
+const PLATFORMS: Record<string, string> = {
+  'darwin-arm64': '@pproenca/node-webcodecs-darwin-arm64',
+  'darwin-x64': '@pproenca/node-webcodecs-darwin-x64',
+  'linux-x64': '@pproenca/node-webcodecs-linux-x64',
+};
 
-  msg += 'Attempted paths:\n';
-  for (const { path: p, error } of errors) {
-    msg += `  - ${p}: ${error.message}\n`;
+/**
+ * Load the native binding.
+ *
+ * Resolution order:
+ * 1. Platform-specific npm package (production path via optionalDependencies)
+ * 2. node-gyp-build (local development fallback)
+ */
+function loadBinding(): unknown {
+  const platform = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORMS[platform];
+
+  if (!pkg) {
+    throw new Error(
+      `Unsupported platform: ${platform}. ` +
+        `Supported platforms: ${Object.keys(PLATFORMS).join(', ')}`
+    );
   }
 
-  msg += '\nPossible solutions:\n';
-
-  if (hasPrebuilt) {
-    msg += '  1. Install with optional dependencies:\n';
-    msg += '     npm install --include=optional\n\n';
-    msg += '  2. Build from source:\n';
-  } else {
-    msg += '  1. Build from source:\n';
+  // Try platform-specific package first (production path)
+  try {
+    const pkgPath = require.resolve(`${pkg}/package.json`);
+    const binPath = join(dirname(pkgPath), 'bin', 'node.napi.node');
+    return require(binPath);
+  } catch {
+    // Platform package not installed - fallback to local build
   }
 
-  msg += getPlatformBuildInstructions();
-
-  return msg;
-}
-
-function loadBinding(): unknown {
-  const errors: Array<{ path: string; error: Error }> = [];
-
-  for (const candidate of candidates) {
-    try {
-      if (typeof candidate === 'function') {
-        const binding = candidate();
-        if (binding && typeof (binding as Record<string, unknown>).VideoEncoder === 'function') {
-          return binding;
-        }
-        throw new Error('Invalid binding: missing VideoEncoder');
-      }
-
-      if (!fs.existsSync(candidate)) {
-        continue;
-      }
-
-      const binding = require(candidate);
-      if (typeof binding.VideoEncoder !== 'function') {
-        throw new Error('Invalid binding: missing VideoEncoder');
-      }
-      return binding;
-    } catch (err) {
-      errors.push({
-        path: typeof candidate === 'string' ? candidate : 'dynamic loader',
-        error: err instanceof Error ? err : new Error(String(err)),
-      });
-    }
+  // Fallback to node-gyp-build for local development
+  try {
+    const nodeGypBuild = require('node-gyp-build');
+    const rootDir = resolve(__dirname, '..');
+    return nodeGypBuild(rootDir);
+  } catch (err) {
+    throw new Error(
+      `Could not load the node-webcodecs native binding for ${platform}.\n` +
+        `Error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+        `Solutions:\n` +
+        `  1. Install the main package: npm install @pproenca/node-webcodecs\n` +
+        `  2. Build from source: npm rebuild --build-from-source\n` +
+        `  3. Ensure FFmpeg dev libs: pkg-config --exists libavcodec\n`
+    );
   }
-
-  throw new Error(buildHelpMessage(errors));
 }
 
 export const binding = loadBinding();
@@ -118,8 +61,6 @@ export const binding = loadBinding();
 export const platformInfo = {
   platform: process.platform,
   arch: process.arch,
-  runtimePlatform: runtimePlatformArch(),
   nodeVersion: process.version,
   napiVersion: (process.versions as Record<string, string>).napi ?? 'unknown',
-  prebuiltAvailable: isPrebuiltAvailable(),
 };

package/lib/control-message-queue.ts

@@ -77,7 +77,6 @@ export class ControlMessageQueue {
 
     this.processing = false;
 
-    // Continue processing if more messages
     if (this.queue.length > 0) {
       this.scheduleProcessing();
     }

package/lib/demuxer.ts

@@ -45,6 +45,16 @@ export class Demuxer {
     return this._native.demux();
   }
 
+  /**
+   * Read packets from the file in chunks.
+   * This is useful for yielding to the event loop during demuxing.
+   * @param maxPackets - Maximum number of packets to read. 0 = unlimited (reads all).
+   * @returns The number of packets actually read.
+   */
+  demuxPackets(maxPackets?: number): number {
+    return this._native.demuxPackets(maxPackets ?? 0);
+  }
+
   close(): void {
     this._native.close();
   }

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

@@ -5,11 +5,14 @@
  * - VideoEncoder, VideoDecoder, AudioEncoder, AudioDecoder extend EventTarget via CodecBase
  * - VideoFrame visibleRect cropping implemented in native layer
  * - ArrayBuffer transfer semantics implemented (uses structuredClone with transfer)
- * - High bit-depth pixel formats for VideoFrame (I420P10, I420P12, I422P10, I422P12, I444P10, I444P12, NV12P10)
+ * - High bit-depth pixel formats for VideoFrame (I420P10, I420P12, etc.)
  *   Note: VideoEncoder input format conversion does not yet support high bit-depth formats
  * - NV21 pixel format supported (8-bit YUV420 semi-planar with VU ordering)
- * - Note: VideoFrame constructor from CanvasImageSource not supported (Node.js has no DOM)
- * - 10-bit alpha formats (I420AP10, I422AP10, I444AP10) supported; 12-bit alpha not supported by FFmpeg
+ * - VideoFrame constructor accepts ImageData (from canvas.getImageData()) - Node.js extension
+ *   Usage: const frame = new VideoFrame(ctx.getImageData(0, 0, w, h), { timestamp: 0 })
+ * - ImageDecoder decodes JPEG/PNG/WebP/GIF directly to VideoFrame
+ * - 10-bit alpha formats (I420AP10, I422AP10, I444AP10) supported
+ * - SVC temporal layer tracking via scalabilityMode (L1T1, L1T2, L1T3)
  */
 
 import { binding, platformInfo } from './binding';
@@ -44,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/is.ts

@@ -135,6 +135,38 @@ export function inArray<T>(val: T, list: readonly T[]): boolean {
   return list.includes(val);
 }
 
+//==============================================================================
+// ImageData Support (for canvas integration)
+//==============================================================================
+
+/**
+ * ImageData-like interface (from canvas.getContext('2d').getImageData()).
+ * Self-describing: contains width, height, and RGBA pixel data.
+ *
+ * Note: This is a Node.js extension to WebCodecs, providing equivalent
+ * functionality to CanvasImageSource for server-side canvas integration.
+ */
+export interface ImageDataLike {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8ClampedArray;
+}
+
+/**
+ * Is this value an ImageData object (from canvas.getImageData)?
+ * ImageData is self-describing: contains width, height, and Uint8ClampedArray data.
+ * This follows sharp's pattern of accepting self-describing pixel buffers.
+ */
+export function isImageData(val: unknown): val is ImageDataLike {
+  if (!object(val)) return false;
+  const img = val as Record<string, unknown>;
+  return (
+    positiveInteger(img.width) &&
+    positiveInteger(img.height) &&
+    img.data instanceof Uint8ClampedArray
+  );
+}
+
 //==============================================================================
 // Domain-Specific Guards
 //==============================================================================

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
   }
 }