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

package/README.md

@@ -1,24 +1,19 @@
 # node-webcodecs
 
-W3C WebCodecs API implementation for Node.js - encode and decode video/audio with browser-compatible APIs.
+WebCodecs API for Node.js — encode and decode video/audio with browser-compatible APIs, powered by FFmpeg.
 
-[![Tests](https://img.shields.io/badge/tests-428%2F442%20passing-brightgreen)](test/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-blue)](package.json)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-blue)](package.json)
 
 ## Why node-webcodecs?
 
-| Feature | node-webcodecs | Browser WebCodecs |
-|---------|----------------|-------------------|
-| **Video Codecs** | H.264, H.265, VP8, VP9, AV1 | Varies by browser |
-| **Audio Codecs** | AAC, Opus, MP3*, FLAC* | Varies by browser |
-| **Container Muxing** | MP4 | ❌ Not in spec |
-| **Demuxing** | Any FFmpeg format | ❌ Not in spec |
-| **Image Decoding** | JPEG, PNG, WebP, GIF (animated) | Same |
-| **Pixel Formats** | 20+ formats (8/10/12-bit) | Limited |
-| **Server-side** | ✅ | ❌ Browser only |
-
-*\* Decode only*
+| Feature              | node-webcodecs              | Browser WebCodecs |
+| -------------------- | --------------------------- | ----------------- |
+| **Video Codecs**     | H.264, H.265, VP8, VP9, AV1 | Varies by browser |
+| **Audio Codecs**     | AAC, Opus, MP3, FLAC        | Varies by browser |
+| **Container Muxing** | MP4                         | Not in spec       |
+| **Demuxing**         | Any FFmpeg format           | Not in spec       |
+| **Server-side**      | Yes                         | Browser only      |
 
 ## Installation
 
@@ -26,279 +21,156 @@ W3C WebCodecs API implementation for Node.js - encode and decode video/audio wit
 npm install @pproenca/node-webcodecs
 ```
 
-### Prerequisites
+Prebuilt binaries with FFmpeg statically linked are included for:
+
+- macOS ARM64 (Apple Silicon)
+- macOS x64 (Intel)
+- Linux x64 (musl, fully static)
+
+<details>
+<summary><strong>Building from Source</strong></summary>
+
+For other platforms or to force a source build:
 
-FFmpeg development libraries are required:
+```bash
+npm install @pproenca/node-webcodecs --build-from-source
+```
+
+This requires FFmpeg 5.0+ development libraries:
 
 **macOS:**
+
 ```bash
 brew install ffmpeg pkg-config
 ```
 
 **Ubuntu/Debian:**
+
 ```bash
-sudo apt-get install \
-  libavcodec-dev libavformat-dev libavutil-dev \
-  libswscale-dev libswresample-dev libavfilter-dev \
-  pkg-config
+sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev \
+  libswscale-dev libswresample-dev libavfilter-dev pkg-config
 ```
 
 **Fedora/RHEL:**
+
 ```bash
 sudo dnf install ffmpeg-devel pkg-config
 ```
 
-**Windows:**
-```bash
-# Using vcpkg
-vcpkg install ffmpeg
-```
+</details>
 
 ## Quick Start
 
-### Encode Video Frames
+### Encode
 
 ```javascript
-import { VideoEncoder, VideoFrame } from '@pproenca/node-webcodecs';
-
-const chunks = [];
+import { VideoEncoder, VideoFrame } from "@pproenca/node-webcodecs";
 
 const encoder = new VideoEncoder({
-  output: (chunk, metadata) => {
-    chunks.push(chunk);
-    if (metadata?.decoderConfig?.description) {
-      // Save codec extradata for container
-    }
-  },
-  error: (e) => console.error('Encode error:', e),
+  output: (chunk) => chunks.push(chunk),
+  error: console.error,
 });
 
 encoder.configure({
-  codec: 'avc1.42001e',  // H.264 Baseline
+  codec: "avc1.42001e",
   width: 1920,
   height: 1080,
   bitrate: 5_000_000,
-  framerate: 30,
 });
 
-// Create frames from RGBA buffers
-for (let i = 0; i < 60; i++) {
-  const frame = new VideoFrame(rgbaBuffer, {
-    format: 'RGBA',
-    codedWidth: 1920,
-    codedHeight: 1080,
-    timestamp: i * (1_000_000 / 30),  // microseconds
-  });
-
-  encoder.encode(frame, { keyFrame: i === 0 });
-  frame.close();
-}
+const frame = new VideoFrame(rgbaBuffer, {
+  format: "RGBA",
+  codedWidth: 1920,
+  codedHeight: 1080,
+  timestamp: 0,
+});
 
+encoder.encode(frame);
+frame.close();
 await encoder.flush();
-encoder.close();
 ```
 
-### Decode Video Chunks
+### Decode
 
 ```javascript
-import { VideoDecoder, EncodedVideoChunk } from '@pproenca/node-webcodecs';
+import { VideoDecoder, EncodedVideoChunk } from "@pproenca/node-webcodecs";
 
 const decoder = new VideoDecoder({
   output: (frame) => {
-    console.log(`Frame: ${frame.codedWidth}x${frame.codedHeight}`);
-    // Process frame data...
+    // Process frame...
     frame.close();
   },
-  error: (e) => console.error('Decode error:', e),
+  error: console.error,
 });
 
 decoder.configure({
-  codec: 'avc1.42001e',
+  codec: "avc1.42001e",
   codedWidth: 1920,
   codedHeight: 1080,
-  description: codecExtradata,  // From container or encoder
 });
 
-for (const chunk of encodedChunks) {
-  decoder.decode(new EncodedVideoChunk({
-    type: chunk.isKeyframe ? 'key' : 'delta',
-    timestamp: chunk.timestamp,
-    data: chunk.data,
-  }));
-}
-
+decoder.decode(new EncodedVideoChunk({ type: "key", timestamp: 0, data }));
 await decoder.flush();
-decoder.close();
 ```
 
-### Mux to MP4 Container
+### Mux to MP4
 
 ```javascript
-import { Muxer, VideoEncoder, VideoFrame } from '@pproenca/node-webcodecs';
+import { Muxer } from "@pproenca/node-webcodecs";
 
-const muxer = new Muxer({ filename: 'output.mp4' });
-let videoTrackId;
+const muxer = new Muxer({ filename: "output.mp4" });
 
-const encoder = new VideoEncoder({
-  output: (chunk, metadata) => {
-    if (metadata?.decoderConfig?.description) {
-      // Add video track on first keyframe
-      videoTrackId = muxer.addVideoTrack({
-        codec: 'avc1.42001e',
-        width: 1920,
-        height: 1080,
-        description: metadata.decoderConfig.description,
-      });
-    }
-    muxer.writeVideoChunk(videoTrackId, chunk);
-  },
-  error: console.error,
-});
-
-encoder.configure({
-  codec: 'avc1.42001e',
+muxer.addVideoTrack({
+  codec: "avc1.42001e",
   width: 1920,
   height: 1080,
-  bitrate: 5_000_000,
-  avc: { format: 'avc' },  // Use AVCC format for MP4
+  description: codecDescription,
 });
 
-// Encode frames...
-await encoder.flush();
-encoder.close();
+muxer.writeVideoChunk(chunk);
 muxer.finalize();
 ```
 
-### Demux from Video File
+### Demux
 
 ```javascript
-import { Demuxer } from '@pproenca/node-webcodecs';
+import { Demuxer } from "@pproenca/node-webcodecs";
 
 const demuxer = new Demuxer({
-  onTrack: (track) => {
-    console.log(`Track ${track.index}: ${track.type} (${track.codec})`);
-    if (track.type === 'video') {
-      // Configure decoder with track.extradata
-    }
-  },
-  onChunk: (chunk, trackIndex) => {
-    // Feed chunk to decoder
-  },
+  onTrack: (track) => console.log(track.codec),
+  onChunk: (chunk, trackIndex) => decoder.decode(chunk),
   onError: console.error,
 });
 
-demuxer.open('input.mp4');
-demuxer.demux();  // Process all chunks
+demuxer.open("input.mp4");
+demuxer.demux();
 demuxer.close();
 ```
 
-### Decode Images (including animated GIFs)
+See [examples/](examples/) for complete working code.
 
-```javascript
-import { ImageDecoder } from '@pproenca/node-webcodecs';
-import { readFileSync } from 'fs';
-
-const imageData = readFileSync('animation.gif');
-
-const decoder = new ImageDecoder({
-  type: 'image/gif',
-  data: imageData,
-});
-
-await decoder.completed;
-
-console.log(`${decoder.tracks.length} track(s)`);
-console.log(`${decoder.tracks[0].frameCount} frames`);
-console.log(`Animated: ${decoder.tracks[0].animated}`);
-
-// Decode each frame
-for (let i = 0; i < decoder.tracks[0].frameCount; i++) {
-  const { image, complete } = await decoder.decode({ frameIndex: i });
-  console.log(`Frame ${i}: ${image.codedWidth}x${image.codedHeight}`);
-  image.close();
-}
-
-decoder.close();
-```
-
-## API Reference
-
-This library implements the [W3C WebCodecs specification](https://www.w3.org/TR/webcodecs/):
-
-### Core Classes
-
-| Class | Description |
-|-------|-------------|
-| `VideoEncoder` | Encode VideoFrame to EncodedVideoChunk |
-| `VideoDecoder` | Decode EncodedVideoChunk to VideoFrame |
-| `AudioEncoder` | Encode AudioData to EncodedAudioChunk |
-| `AudioDecoder` | Decode EncodedAudioChunk to AudioData |
-| `VideoFrame` | Raw video frame with pixel data |
-| `AudioData` | Raw audio samples |
-| `EncodedVideoChunk` | Compressed video data |
-| `EncodedAudioChunk` | Compressed audio data |
-| `ImageDecoder` | Decode images (JPEG, PNG, WebP, GIF) |
-| `VideoColorSpace` | Color space metadata |
-
-### Beyond W3C Spec
-
-| Class | Description |
-|-------|-------------|
-| `Muxer` | Write to MP4 containers |
-| `Demuxer` | Read from any FFmpeg-supported format |
-| `VideoFilter` | Apply blur filters (content moderation) |
-| `TestVideoGenerator` | Generate test patterns |
+## API
 
-### Supported Codecs
+This library implements the [W3C WebCodecs specification](https://www.w3.org/TR/webcodecs/).
 
-| Type | Codec | Encode | Decode | Codec String |
-|------|-------|--------|--------|--------------|
-| Video | H.264/AVC | ✅ | ✅ | `avc1.*` |
-| Video | H.265/HEVC | ✅ | ✅ | `hvc1.*`, `hev1.*` |
-| Video | VP8 | ✅ | ✅ | `vp8` |
-| Video | VP9 | ✅ | ✅ | `vp09.*` |
-| Video | AV1 | ✅ | ✅ | `av01.*` |
-| Audio | AAC | ✅ | ✅ | `mp4a.40.2` |
-| Audio | Opus | ✅ | ✅ | `opus` |
-| Audio | MP3 | ❌ | ✅ | `mp3` |
-| Audio | FLAC | ❌ | ✅ | `flac` |
+| Class                                     | Description                     |
+| ----------------------------------------- | ------------------------------- |
+| `VideoEncoder` / `VideoDecoder`           | Compress / decompress video     |
+| `AudioEncoder` / `AudioDecoder`           | Compress / decompress audio     |
+| `VideoFrame` / `AudioData`                | Raw media containers            |
+| `EncodedVideoChunk` / `EncodedAudioChunk` | Compressed media packets        |
+| `ImageDecoder`                            | Decode JPEG, PNG, WebP, GIF     |
+|                                           |                                 |
+| `Muxer` / `Demuxer`                       | Container I/O (beyond W3C spec) |
 
-### Pixel Formats
+**Video codecs:** H.264, H.265, VP8, VP9, AV1
+**Audio codecs:** AAC, Opus, MP3 (decode), FLAC (decode)
 
-8-bit: `I420`, `I420A`, `I422`, `I422A`, `I444`, `I444A`, `NV12`, `NV21`, `NV12A`, `RGBA`, `RGBX`, `BGRA`, `BGRX`
-
-10-bit: `I420P10`, `I422P10`, `I444P10`, `NV12P10`, `I420AP10`, `I422AP10`, `I444AP10`
-
-12-bit: `I420P12`, `I422P12`, `I444P12`
-
-## Interactive Demos
-
-Run the interactive demo with web UI:
-
-```bash
-git clone https://github.com/pproenca/node-webcodecs
-cd node-webcodecs
-npm install && npm run build
-node examples/run-demo.js
-```
-
-Or use Docker:
-
-```bash
-docker compose up demo
-```
-
-## Test Results
-
-```
-Test Files:  45 passed / 51 total
-     Tests:  428 passed / 442 total
-  Duration:  ~2 minutes
-```
+See [docs/codecs.md](docs/codecs.md) for codec strings and pixel formats.
 
 ## Contributing
 
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for development setup and guidelines.
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
 ## License
 

package/binding.gyp

@@ -0,0 +1,123 @@
+{
+  "variables": {
+    "enable_sanitizers%": 0
+  },
+  "targets": [
+    {
+      "target_name": "node_webcodecs",
+      "sources": [
+        "src/addon.cc",
+        "src/common.cc",
+        "src/video_encoder.cc",
+        "src/video_decoder.cc",
+        "src/video_frame.cc",
+        "src/audio_encoder.cc",
+        "src/audio_decoder.cc",
+        "src/audio_data.cc",
+        "src/encoded_video_chunk.cc",
+        "src/encoded_audio_chunk.cc",
+        "src/video_filter.cc",
+        "src/demuxer.cc",
+        "src/muxer.cc",
+        "src/image_decoder.cc",
+        "src/test_video_generator.cc",
+        "src/async_encode_worker.cc",
+        "src/async_decode_worker.cc",
+        "src/warnings.cc",
+        "src/error_builder.cc",
+        "src/descriptors.cc"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "."
+      ],
+      "defines": [
+        "NAPI_VERSION=8",
+        "NAPI_CPP_EXCEPTIONS",
+        "NODE_ADDON_API_DISABLE_DEPRECATED"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "conditions": [
+        ["OS=='mac'", {
+          "include_dirs": [
+            "<!@(node gyp/ffmpeg-paths.js include 2>/dev/null || pkg-config --cflags-only-I libavcodec libavutil libswscale libswresample libavfilter 2>/dev/null | sed s/-I//g || echo '/opt/homebrew/include /usr/local/include')"
+          ],
+          "libraries": [
+            "<!@(node gyp/ffmpeg-paths.js lib 2>/dev/null || pkg-config --libs --static libavcodec libavformat libavutil libswscale libswresample libavfilter 2>/dev/null || echo '-L/opt/homebrew/lib -L/usr/local/lib -lavcodec -lavformat -lavutil -lswscale -lswresample -lavfilter')",
+            "-framework VideoToolbox",
+            "-framework AudioToolbox",
+            "-framework CoreMedia",
+            "-framework CoreVideo",
+            "-framework CoreFoundation",
+            "-framework CoreServices",
+            "-framework Security",
+            "-framework Metal",
+            "-framework CoreImage",
+            "-framework AppKit",
+            "-liconv",
+            "-lbz2",
+            "-lz"
+          ],
+          "xcode_settings": {
+            "CLANG_CXX_LANGUAGE_STANDARD": "c++20",
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "GCC_ENABLE_CPP_RTTI": "YES",
+            "MACOSX_DEPLOYMENT_TARGET": "11.0",
+            "OTHER_CPLUSPLUSFLAGS": [
+              "-fexceptions",
+              "-Wall",
+              "-Wextra",
+              "-Wno-unused-parameter"
+            ],
+            "OTHER_LDFLAGS": [
+              "-mmacosx-version-min=11.0"
+            ]
+          }
+        }],
+        ["OS=='linux'", {
+          "include_dirs": [
+            "<!@(node gyp/ffmpeg-paths.js include 2>/dev/null || pkg-config --cflags-only-I libavcodec libavutil libswscale libswresample libavfilter | sed s/-I//g)"
+          ],
+          "libraries": [
+            "<!@(node gyp/ffmpeg-paths.js lib 2>/dev/null || pkg-config --libs --static libavcodec libavformat libavutil libswscale libswresample libavfilter)",
+            "-lpthread",
+            "-lm",
+            "-ldl",
+            "-lz"
+          ],
+          "ldflags": [
+            "-Wl,-Bsymbolic"
+          ],
+          "cflags_cc": [
+            "-std=c++20",
+            "-fexceptions",
+            "-Wall",
+            "-Wextra",
+            "-Wno-unused-parameter",
+            "-fPIC"
+          ]
+        }],
+        ["enable_sanitizers==1", {
+          "cflags_cc": [
+            "-fsanitize=address,undefined",
+            "-fno-omit-frame-pointer"
+          ],
+          "ldflags": [
+            "-fsanitize=address,undefined"
+          ],
+          "xcode_settings": {
+            "OTHER_CFLAGS": [
+              "-fsanitize=address,undefined",
+              "-fno-omit-frame-pointer"
+            ],
+            "OTHER_LDFLAGS": [
+              "-fsanitize=address,undefined"
+            ]
+          }
+        }]
+      ]
+    }
+  ]
+}

package/dist/audio-decoder.js

@@ -55,7 +55,6 @@ class AudioDecoder extends codec_base_1.CodecBase {
         this._errorCallback = init.error;
         this._controlQueue.setErrorHandler(init.error);
         const outputCallback = (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
             const wrapper = Object.create(audio_data_1.AudioData.prototype);
@@ -92,7 +91,7 @@ class AudioDecoder extends codec_base_1.CodecBase {
     decode(chunk) {
         // 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/dist/audio-encoder.d.ts

@@ -10,10 +10,14 @@ export declare class AudioEncoder extends CodecBase {
     private _native;
     private _controlQueue;
     private _encodeQueueSize;
+    private _maxQueueDepth;
     constructor(init: AudioEncoderInit);
     get state(): CodecState;
     get encodeQueueSize(): number;
     get codecSaturated(): boolean;
+    get maxQueueDepth(): number;
+    set maxQueueDepth(value: number);
+    get ready(): Promise<void>;
     configure(config: AudioEncoderConfig): void;
     encode(data: AudioData): void;
     flush(): Promise<void>;

package/dist/audio-encoder.js

@@ -46,10 +46,12 @@ const encoded_chunks_1 = require("./encoded-chunks");
 const is = __importStar(require("./is"));
 // Load native addon with type assertion
 const native = binding_1.binding;
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
 class AudioEncoder extends codec_base_1.CodecBase {
     constructor(init) {
         super();
         this._encodeQueueSize = 0;
+        this._maxQueueDepth = DEFAULT_MAX_QUEUE_DEPTH;
         // W3C spec: output and error callbacks are required
         is.assertPlainObject(init, 'init');
         is.assertFunction(init.output, 'init.output');
@@ -57,7 +59,6 @@ class AudioEncoder extends codec_base_1.CodecBase {
         this._controlQueue = new control_message_queue_1.ControlMessageQueue();
         this._controlQueue.setErrorHandler(init.error);
         const outputCallback = (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
             const wrapper = Object.create(encoded_chunks_1.EncodedAudioChunk.prototype);
@@ -80,6 +81,31 @@ class AudioEncoder extends codec_base_1.CodecBase {
     get codecSaturated() {
         return this._native.codecSaturated;
     }
+    get maxQueueDepth() {
+        return this._maxQueueDepth;
+    }
+    set maxQueueDepth(value) {
+        if (value < 1) {
+            throw new RangeError('maxQueueDepth must be at least 1');
+        }
+        this._maxQueueDepth = value;
+    }
+    get ready() {
+        if (this._encodeQueueSize < this._maxQueueDepth) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const checkCapacity = () => {
+                if (this._encodeQueueSize < this._maxQueueDepth) {
+                    resolve();
+                }
+                else {
+                    setTimeout(checkCapacity, 1);
+                }
+            };
+            setTimeout(checkCapacity, 1);
+        });
+    }
     configure(config) {
         // W3C spec: throw if closed
         if (this.state === 'closed') {
@@ -95,7 +121,7 @@ class AudioEncoder extends codec_base_1.CodecBase {
     encode(data) {
         // 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/dist/binding.d.ts

@@ -2,8 +2,6 @@ export declare const binding: unknown;
 export declare const platformInfo: {
     platform: NodeJS.Platform;
     arch: NodeJS.Architecture;
-    runtimePlatform: string;
     nodeVersion: string;
     napiVersion: string;
-    prebuiltAvailable: boolean;
 };