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

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 (sharp pattern: @scope/pkg-platform/binding.node)
-  () => {
-    const pkg = getPrebuiltPackageName();
-    const bindingPath = `${pkg}/node-webcodecs.node`;
-    return require(bindingPath);
-  },
-];
-
-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

@@ -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;