webcodecs-node 0.7.1 → 0.7.5

package/docs/api.md

@@ -57,15 +57,19 @@ Configure the encoder. Must be called before encoding.
 **VideoEncoderConfig:**
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `codec` | string | Yes | Codec string (e.g., 'avc1.42001E', 'vp9') |
+| `codec` | string | Yes | Codec string (e.g., 'avc1.42001E', 'vp9', 'av1') |
 | `width` | number | Yes | Frame width in pixels |
 | `height` | number | Yes | Frame height in pixels |
+| `displayWidth` | number | No | Display width (for non-square pixels) |
+| `displayHeight` | number | No | Display height (for non-square pixels) |
 | `bitrate` | number | No | Target bitrate in bits/second |
 | `framerate` | number | No | Target framerate |
 | `bitrateMode` | 'constant' \| 'variable' \| 'quantizer' | No | Bitrate control mode |
 | `alpha` | 'discard' \| 'keep' | No | Alpha channel handling |
 | `latencyMode` | 'quality' \| 'realtime' | No | Latency vs quality tradeoff |
 | `hardwareAcceleration` | 'no-preference' \| 'prefer-hardware' \| 'prefer-software' | No | Hardware acceleration preference |
+| `scalabilityMode` | string | No | SVC scalability mode (e.g., 'L1T2') |
+| `format` | 'mp4' \| 'annexb' | No | Output format: 'mp4' (default) for length-prefixed, 'annexb' for raw bitstreams |
 | `maxQueueSize` | number | No | Max pending frames before QuotaExceededError. Auto-calculated from resolution if not set (~300MB target memory). |
 
 #### `encode(frame: VideoFrame, options?: VideoEncoderEncodeOptions): void`
@@ -124,7 +128,13 @@ Check if a configuration is supported.
 | `codec` | string | Yes | Codec string |
 | `codedWidth` | number | No | Coded frame width |
 | `codedHeight` | number | No | Coded frame height |
+| `displayAspectWidth` | number | No | Display aspect ratio width |
+| `displayAspectHeight` | number | No | Display aspect ratio height |
 | `description` | BufferSource | No | Codec-specific data (e.g., SPS/PPS for H.264) |
+| `colorSpace` | VideoColorSpaceInit | No | Color space configuration |
+| `hardwareAcceleration` | 'no-preference' \| 'prefer-hardware' \| 'prefer-software' | No | Hardware acceleration preference |
+| `optimizeForLatency` | boolean | No | Optimize for low latency decoding |
+| `outputFormat` | VideoPixelFormat | No | Preferred output pixel format |
 | `maxQueueSize` | number | No | Max pending chunks before QuotaExceededError. Auto-calculated from resolution if dimensions provided (~300MB target memory). |
 
 #### `decode(chunk: EncodedVideoChunk): void`
@@ -174,7 +184,10 @@ new AudioEncoder(init: AudioEncoderInit)
 | `codec` | string | Yes | Codec string (e.g., 'opus', 'mp4a.40.2') |
 | `sampleRate` | number | Yes | Sample rate in Hz |
 | `numberOfChannels` | number | Yes | Number of audio channels |
-| `bitrate` | number | No | Target bitrate |
+| `bitrate` | number | No | Target bitrate in bits/second |
+| `bitrateMode` | 'constant' \| 'variable' | No | Bitrate control mode |
+| `latencyMode` | 'quality' \| 'realtime' | No | Latency vs quality tradeoff |
+| `format` | 'adts' \| 'aac' | No | Output format: 'adts' (default) for ADTS headers, 'aac' for raw AAC frames |
 
 #### `encode(data: AudioData): void`
 
@@ -209,6 +222,7 @@ new AudioDecoder(init: AudioDecoderInit)
 | `sampleRate` | number | Yes | Sample rate in Hz |
 | `numberOfChannels` | number | Yes | Number of channels |
 | `description` | BufferSource | No | Codec-specific data |
+| `outputFormat` | AudioSampleFormat | No | Preferred output sample format (default: 'f32') |
 
 #### `decode(chunk: EncodedAudioChunk): void`
 
@@ -396,6 +410,10 @@ new VideoFrame(data: BufferSource, init: VideoFrameBufferInit)
 
 Get buffer size needed for copyTo.
 
+#### `metadata(): VideoFrameMetadata`
+
+Returns metadata associated with this VideoFrame. Currently returns an empty object as metadata fields (like `rtpTimestamp` for WebRTC) will be added as needed per W3C spec.
+
 #### `copyTo(destination: BufferSource, options?: VideoFrameCopyToOptions): Promise<PlaneLayout[]>`
 
 Copy frame data to a buffer.
@@ -659,3 +677,35 @@ export WEBCODECS_CAPABILITIES_PROFILE=$(pwd)/webcodecs-capabilities.json
 ```
 
 The JSON follows the `CapabilityProfile` schema (see `src/capabilities/types.ts`). If no profile is provided, `mediaCapabilities` falls back to built-in heuristics based on resolution, bitrate, and detected hardware acceleration.
+
+---
+
+## Known Limitations
+
+### Encoder Frame Batching
+
+When using `latencyMode: 'quality'` (the default), FFmpeg encoders may buffer frames for better compression. This means:
+
+- Multiple `encode()` calls may produce fewer output chunks than input frames
+- All frames are output after `flush()`, but may be batched
+
+**Workaround:** Use `latencyMode: 'realtime'` for 1:1 frame-to-chunk output:
+
+```typescript
+encoder.configure({
+  codec: 'vp8',
+  width: 640,
+  height: 480,
+  latencyMode: 'realtime', // Disables frame buffering
+});
+```
+
+### Codec String Validation
+
+The `isConfigSupported()` method performs strict codec string validation per the WebCodecs specification:
+
+- **Case-sensitive:** `vP8` or `VP8` returns `supported: false` (use `vp8`)
+- **Fully qualified VP9/AV1:** Ambiguous `vp9` returns `supported: false` (use `vp09.00.10.08`)
+- **Valid parameters:** Unknown profiles/levels return `supported: false`
+
+Note: `configure()` is more lenient and accepts simple codec strings like `vp9` for FFmpeg compatibility.

package/docs/configuration.md

@@ -100,10 +100,10 @@ encoder.configure({
 
 `crf` and `preset` are **extensions** (not part of the WebCodecs spec). They are loaded globally from a JS file and passed to FFmpeg when supported.
 
-Edit `ffmpeg-quality.js` in the project root:
+Edit `webcodecs-config.js` in the project root:
 
 ```javascript
-export default {
+module.exports = {
   // Global overrides:
   // crf: 28,
   // preset: 'veryfast',
@@ -113,12 +113,15 @@ export default {
   //   h264: { crf: 30, preset: 'veryfast' },
   //   hevc: { crf: 28, preset: 'medium' },
   // },
+
+  // Hardware acceleration priority (optional):
+  // hwaccel: ['nvenc', 'qsv', 'vaapi'],
 };
 ```
 
 **Notes:**
 - If the file is missing, no overrides are applied.
-- The file is loaded from `process.cwd()` or from `WEB_CODECS_FFMPEG_QUALITY`.
+- The file is loaded from `process.cwd()` or from `WEBCODECS_CONFIG` env var.
 
 ---
 
@@ -147,16 +150,16 @@ The `alpha` option controls how transparent pixels are handled during encoding.
 
 ## Output Bitstream Format
 
-By default the encoders emit Annex B (video) and ADTS/OGG (audio) bitstreams. If you need MP4-style payloads (length-prefixed NAL units, raw AAC frames) you can opt-in via the `format` config field.
+By default the video encoder emits MP4-style payloads (length-prefixed NAL units) with `decoderConfig.description`. Audio encoders default to ADTS/OGG bitstreams, with an option for raw AAC frames.
 
 ### VideoEncoder `format`
 
 | Value | Description |
 |-------|-------------|
-| `'annexb'` (default) | Emit Annex B/IVF bitstreams (same as before). |
-| `'mp4'` | Convert Annex B output into length-prefixed avcC/hvcc samples and include `decoderConfig.description`. |
+| `'mp4'` (default) | Emit length-prefixed avcC/hvcc samples with `decoderConfig.description` for MP4 muxing. |
+| `'annexb'` | Emit raw Annex B bitstreams with start codes (for raw streaming or ffmpeg piping). |
 
-When `format: 'mp4'` is set the encoder automatically extracts SPS/PPS/VPS from keyframes and exposes them in metadata so an MP4 muxer can use them.
+With the default `format: 'mp4'`, the encoder automatically extracts SPS/PPS/VPS from keyframes and exposes them in metadata so an MP4 muxer can use them.
 
 ### AudioEncoder `format`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcodecs-node",
-  "version": "0.7.1",
+  "version": "0.7.5",
   "description": "WebCodecs API implementation for Node.js using node-av",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",