@napi-rs/webcodecs 1.3.0 → 1.4.0

package/README.md

@@ -168,6 +168,11 @@ result.image.close()
 decoder.close()
 ```
 
+When `data` is a `ReadableStream`, `ImageDecoder` accumulates every chunk so it
+can re-probe the growing input. This buffer currently has no fixed limit, so
+applications should bound or reject unexpectedly large streams before passing
+them to the decoder.
+
 ### Container Demuxing
 
 Read encoded video/audio from MP4, WebM, or MKV containers:
@@ -283,6 +288,7 @@ import { Mp4Muxer } from '@napi-rs/webcodecs'
 
 const muxer = new Mp4Muxer({
   fragmented: true, // Required for MP4 streaming
+  // Maximum bytes returned by each read(); this is not a memory limit.
   streaming: { bufferCapacity: 256 * 1024 },
 })
 
@@ -303,6 +309,12 @@ if (muxer.isFinished) {
 }
 ```
 
+Streaming writes are queued in a growable native buffer so `addVideoChunk()`
+and `addAudioChunk()` never wait for JavaScript to call `read()`. Applications
+must drain `read()` regularly; an indefinitely stalled consumer can retain the
+entire muxed output in memory. `bufferCapacity` controls only the maximum size
+of each returned read chunk.
+
 ### VideoFrame from Canvas
 
 Create VideoFrames from `@napi-rs/canvas` for graphics, text rendering, or image compositing:
@@ -683,6 +695,11 @@ For full API documentation, see the [W3C WebCodecs specification](https://w3c.gi
 - Node.js 18+
 - pnpm
 
+The build downloads the pinned FFmpeg 9.0 release by default. If you opt out
+of that download or set `FFMPEG_DIR`, the supplied FFmpeg headers and libraries
+must be from FFmpeg 9.x; FFmpeg 8.x system/Homebrew installations are rejected
+by the ABI guard.
+
 ### Build
 
 ```bash

package/index.d.ts

@@ -111,32 +111,6 @@ export interface MuxerAudioTrackConfig {
   description?: Uint8Array
 }
 
-/** Init options for Mp4Muxer */
-export interface Mp4MuxerInit {
-  /** Move moov atom to beginning (not compatible with streaming) */
-  fastStart?: boolean
-  /** Use fragmented MP4 for streaming */
-  fragmented?: boolean
-  /** Enable streaming output mode */
-  streaming?: { bufferCapacity?: number }
-}
-
-/** Init options for WebMMuxer */
-export interface WebMMuxerInit {
-  /** Enable live streaming mode */
-  live?: boolean
-  /** Enable streaming output mode */
-  streaming?: { bufferCapacity?: number }
-}
-
-/** Init options for MkvMuxer */
-export interface MkvMuxerInit {
-  /** Enable live streaming mode */
-  live?: boolean
-  /** Enable streaming output mode */
-  streaming?: { bufferCapacity?: number }
-}
-
 // ============================================================================
 // Async Iterator Types
 // ============================================================================
@@ -191,7 +165,18 @@ export interface MkvDemuxer {
   [Symbol.asyncIterator](): AsyncGenerator<DemuxerChunk, void, void>
 }
 
-export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array
+export type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array
 /**
  * AudioData - represents uncompressed audio data
  *
@@ -285,7 +270,7 @@ export declare class AudioDecoder {
    *
    * @param init - Init dictionary containing output and error callbacks
    */
-  constructor(init: { output: (data: AudioData) => void, error: (error: Error) => void })
+  constructor(init: { output: (data: AudioData) => void; error: (error: Error) => void })
   /** Get decoder state */
   get state(): CodecState
   /** Get number of pending decode operations (per WebCodecs spec) */
@@ -325,9 +310,17 @@ export declare class AudioDecoder {
    */
   static isConfigSupported(config: AudioDecoderConfig): Promise<AudioDecoderSupport>
   /** Add an event listener for the specified event type */
-  addEventListener(eventType: string, callback: () => unknown, options?: AudioDecoderAddEventListenerOptions | undefined | null): void
+  addEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: AudioDecoderAddEventListenerOptions | undefined | null,
+  ): void
   /** Remove an event listener for the specified event type */
-  removeEventListener(eventType: string, callback: () => unknown, options?: AudioDecoderEventListenerOptions | undefined | null): void
+  removeEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: AudioDecoderEventListenerOptions | undefined | null,
+  ): void
   /** Dispatch an event to all registered listeners */
   dispatchEvent(eventType: string): boolean
 }
@@ -362,7 +355,10 @@ export declare class AudioEncoder {
    *
    * @param init - Init dictionary containing output and error callbacks
    */
-  constructor(init: { output: (chunk: EncodedAudioChunk, metadata?: EncodedAudioChunkMetadata) => void, error: (error: Error) => void })
+  constructor(init: {
+    output: (chunk: EncodedAudioChunk, metadata?: EncodedAudioChunkMetadata) => void
+    error: (error: Error) => void
+  })
   /** Get encoder state */
   get state(): CodecState
   /** Get number of pending encode operations (per WebCodecs spec) */
@@ -405,9 +401,17 @@ export declare class AudioEncoder {
    * Add an event listener for the specified event type
    * Uses separate RwLock to avoid blocking on encode operations
    */
-  addEventListener(eventType: string, callback: () => unknown, options?: AudioEncoderAddEventListenerOptions | undefined | null): void
+  addEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: AudioEncoderAddEventListenerOptions | undefined | null,
+  ): void
   /** Remove an event listener for the specified event type */
-  removeEventListener(eventType: string, callback: () => unknown, options?: AudioEncoderEventListenerOptions | undefined | null): void
+  removeEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: AudioEncoderEventListenerOptions | undefined | null,
+  ): void
   /** Dispatch an event to all registered listeners */
   dispatchEvent(eventType: string): boolean
 }
@@ -418,7 +422,12 @@ export declare class AudioEncoder {
  */
 export declare class DOMRectReadOnly {
   /** Create a new DOMRectReadOnly */
-  constructor(x?: number | undefined | null, y?: number | undefined | null, width?: number | undefined | null, height?: number | undefined | null)
+  constructor(
+    x?: number | undefined | null,
+    y?: number | undefined | null,
+    width?: number | undefined | null,
+    height?: number | undefined | null,
+  )
   /** X coordinate */
   get x(): number
   /** Y coordinate */
@@ -504,7 +513,8 @@ export declare class EncodedVideoChunk {
 export declare class ImageDecoder {
   /**
    * Create a new ImageDecoder
-   * Supports both Uint8Array and ReadableStream as data source per W3C spec
+   * Supports both Uint8Array and ReadableStream as data source per W3C spec.
+   * ReadableStream input is buffered without a fixed size limit.
    */
   constructor(init: ImageDecoderInit)
   /** Whether the data is fully buffered */
@@ -884,7 +894,7 @@ export declare class VideoDecoder {
    *
    * @param init - Init dictionary containing output and error callbacks
    */
-  constructor(init: { output: (frame: VideoFrame) => void, error: (error: Error) => void })
+  constructor(init: { output: (frame: VideoFrame) => void; error: (error: Error) => void })
   /** Get decoder state */
   get state(): CodecState
   /** Get number of pending decode operations (per WebCodecs spec) */
@@ -934,9 +944,17 @@ export declare class VideoDecoder {
    * Add an event listener for the specified event type
    * Uses separate RwLock to avoid blocking on decode operations
    */
-  addEventListener(eventType: string, callback: () => unknown, options?: VideoDecoderAddEventListenerOptions | undefined | null): void
+  addEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: VideoDecoderAddEventListenerOptions | undefined | null,
+  ): void
   /** Remove an event listener for the specified event type */
-  removeEventListener(eventType: string, callback: () => unknown, options?: VideoDecoderEventListenerOptions | undefined | null): void
+  removeEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: VideoDecoderEventListenerOptions | undefined | null,
+  ): void
   /** Dispatch an event to all registered listeners */
   dispatchEvent(eventType: string): boolean
 }
@@ -972,7 +990,10 @@ export declare class VideoEncoder {
    *
    * @param init - Init dictionary containing output and error callbacks
    */
-  constructor(init: { output: (chunk: EncodedVideoChunk, metadata?: EncodedVideoChunkMetadata) => void, error: (error: Error) => void })
+  constructor(init: {
+    output: (chunk: EncodedVideoChunk, metadata?: EncodedVideoChunkMetadata) => void
+    error: (error: Error) => void
+  })
   /** Get encoder state */
   get state(): CodecState
   /** Get number of pending encode operations (per WebCodecs spec) */
@@ -1007,9 +1028,17 @@ export declare class VideoEncoder {
    * Add an event listener for the specified event type
    * Uses separate RwLock to avoid blocking on encode operations
    */
-  addEventListener(eventType: string, callback: () => unknown, options?: AddEventListenerOptions | undefined | null): void
+  addEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: AddEventListenerOptions | undefined | null,
+  ): void
   /** Remove an event listener for the specified event type */
-  removeEventListener(eventType: string, callback: () => unknown, options?: EventListenerOptions | undefined | null): void
+  removeEventListener(
+    eventType: string,
+    callback: () => unknown,
+    options?: EventListenerOptions | undefined | null,
+  ): void
   /** Dispatch an event to all registered listeners */
   dispatchEvent(eventType: string): boolean
   /**
@@ -1218,9 +1247,9 @@ export declare class WebMMuxer {
 
 /** AAC bitstream format (W3C WebCodecs AAC Registration) */
 export type AacBitstreamFormat = /** Raw AAC frames - metadata in description */
-'aac'|
+| 'aac'
 /** ADTS frames - metadata in each frame */
-'adts';
+| 'adts'
 
 /** AAC encoder configuration (W3C WebCodecs AAC Registration) */
 export interface AacEncoderConfig {
@@ -1240,9 +1269,9 @@ export interface AddEventListenerOptions {
  * Default is "discard" per spec
  */
 export type AlphaOption = /** Keep alpha channel if present */
-'keep'|
+| 'keep'
 /** Discard alpha channel (default per W3C spec) */
-'discard';
+| 'discard'
 
 /** Options for copyTo operation */
 export interface AudioDataCopyToOptions {
@@ -1308,9 +1337,7 @@ export interface AudioEncoderAddEventListenerOptions {
 }
 
 /** Encode options for audio */
-export interface AudioEncoderEncodeOptions {
-
-}
+export interface AudioEncoderEncodeOptions {}
 
 /** Options for removeEventListener (W3C DOM spec) */
 export interface AudioEncoderEventListenerOptions {
@@ -1327,27 +1354,27 @@ export interface AudioEncoderSupport {
 
 /** Audio sample format (WebCodecs spec) */
 export type AudioSampleFormat = /** Unsigned 8-bit integer samples| interleaved */
-'u8'|
+| 'u8'
 /** Signed 16-bit integer samples| interleaved */
-'s16'|
+| 's16'
 /** Signed 32-bit integer samples| interleaved */
-'s32'|
+| 's32'
 /** 32-bit float samples| interleaved */
-'f32'|
+| 'f32'
 /** Unsigned 8-bit integer samples| planar */
-'u8-planar'|
+| 'u8-planar'
 /** Signed 16-bit integer samples| planar */
-'s16-planar'|
+| 's16-planar'
 /** Signed 32-bit integer samples| planar */
-'s32-planar'|
+| 's32-planar'
 /** 32-bit float samples| planar */
-'f32-planar';
+| 'f32-planar'
 
 /** AVC (H.264) bitstream format (W3C WebCodecs AVC Registration) */
 export type AvcBitstreamFormat = /** AVC format with parameter sets in description (ISO 14496-15) */
-'avc'|
+| 'avc'
 /** Annex B format with parameter sets in bitstream */
-'annexb';
+| 'annexb'
 
 /** AVC (H.264) encoder configuration (W3C WebCodecs AVC Registration) */
 export interface AvcEncoderConfig {
@@ -1357,23 +1384,23 @@ export interface AvcEncoderConfig {
 
 /** Bitrate mode for audio encoding (W3C WebCodecs spec) */
 export type BitrateMode = /** Variable bitrate (default) */
-'variable'|
+| 'variable'
 /** Constant bitrate */
-'constant';
+| 'constant'
 
 /** Encoder state per WebCodecs spec */
 export type CodecState = /** Encoder not configured */
-'unconfigured'|
+| 'unconfigured'
 /** Encoder configured and ready */
-'configured'|
+| 'configured'
 /** Encoder closed */
-'closed';
+| 'closed'
 
 /** ColorSpaceConversion for ImageDecoder (W3C WebCodecs spec) */
 export type ColorSpaceConversion = /** Apply default color space conversion (spec default) */
-'default'|
+| 'default'
 /** No color space conversion */
-'none';
+| 'none'
 
 /** Audio decoder configuration exposed to JavaScript */
 export interface DemuxerAudioDecoderConfig {
@@ -1441,9 +1468,9 @@ export interface EncodedAudioChunkMetadataJs {
 
 /** Type of encoded audio chunk */
 export type EncodedAudioChunkType = /** Key chunk - can be decoded independently */
-'key'|
+| 'key'
 /** Delta chunk - depends on previous chunks */
-'delta';
+| 'delta'
 
 /** Output callback metadata per WebCodecs spec */
 export interface EncodedVideoChunkMetadata {
@@ -1471,9 +1498,9 @@ export interface EncodedVideoChunkMetadataJs {
 
 /** Type of encoded video chunk */
 export type EncodedVideoChunkType = /** Keyframe - can be decoded independently */
-'key'|
+| 'key'
 /** Delta frame - depends on previous frames */
-'delta';
+| 'delta'
 
 /** Options for removeEventListener (W3C DOM spec) */
 export interface EventListenerOptions {
@@ -1499,11 +1526,11 @@ export declare function getPreferredHardwareAccelerator(): string | null
 
 /** Hardware acceleration preference (W3C WebCodecs spec) */
 export type HardwareAcceleration = /** No preference - may use hardware or software */
-'no-preference'|
+| 'no-preference'
 /** Prefer hardware acceleration */
-'prefer-hardware'|
+| 'prefer-hardware'
 /** Prefer software implementation */
-'prefer-software';
+| 'prefer-software'
 
 /** Hardware accelerator information */
 export interface HardwareAccelerator {
@@ -1517,9 +1544,9 @@ export interface HardwareAccelerator {
 
 /** HEVC (H.265) bitstream format (W3C WebCodecs HEVC Registration) */
 export type HevcBitstreamFormat = /** HEVC format with parameter sets in description (ISO 14496-15) */
-'hevc'|
+| 'hevc'
 /** Annex B format with parameter sets in bitstream */
-'annexb';
+| 'annexb'
 
 /** HEVC (H.265) encoder configuration (W3C WebCodecs HEVC Registration) */
 export interface HevcEncoderConfig {
@@ -1540,9 +1567,9 @@ export declare function isHardwareAcceleratorAvailable(name: string): boolean
 
 /** Latency mode for video encoding (W3C WebCodecs spec) */
 export type LatencyMode = /** Optimize for quality (default) */
-'quality'|
+| 'quality'
 /** Optimize for low latency */
-'realtime';
+| 'realtime'
 
 /** Audio track configuration for MKV muxer */
 export interface MkvAudioTrackConfig {
@@ -1622,17 +1649,17 @@ export interface Mp4VideoTrackConfig {
 
 /** Opus application mode (W3C WebCodecs Opus Registration) */
 export type OpusApplication = /** Optimize for VoIP (speech intelligibility) */
-'voip'|
+| 'voip'
 /** Optimize for audio fidelity (default) */
-'audio'|
+| 'audio'
 /** Minimize coding delay */
-'lowdelay';
+| 'lowdelay'
 
 /** Opus bitstream format (W3C WebCodecs Opus Registration) */
 export type OpusBitstreamFormat = /** Opus packets (RFC 6716) - no metadata needed for decoding */
-'opus'|
+| 'opus'
 /** Ogg encapsulation (RFC 7845) - metadata in description */
-'ogg';
+| 'ogg'
 
 /** Opus encoder configuration (W3C WebCodecs Opus Registration) */
 export interface OpusEncoderConfig {
@@ -1659,11 +1686,11 @@ export interface OpusEncoderConfig {
 
 /** Opus signal type hint (W3C WebCodecs Opus Registration) */
 export type OpusSignal = /** Auto-detect signal type */
-'auto'|
+| 'auto'
 /** Music signal */
-'music'|
+| 'music'
 /** Voice/speech signal */
-'voice';
+| 'voice'
 
 /** Layout information for a single plane per WebCodecs spec */
 export interface PlaneLayout {
@@ -1686,7 +1713,10 @@ export declare function resetHardwareFallbackState(): void
 
 /** Streaming mode options for muxers */
 export interface StreamingMuxerOptions {
-  /** Buffer capacity for streaming output (default: 256KB) */
+  /**
+   * Maximum bytes returned by each streaming read (default: 256KB).
+   * Muxer writes are queued without blocking the JavaScript consumer.
+   */
   bufferCapacity?: number
 }
 
@@ -1704,15 +1734,15 @@ export interface SvcOutputMetadataJs {
 
 /** Video color primaries (W3C WebCodecs spec) */
 export type VideoColorPrimaries = /** BT.709 / sRGB primaries */
-'bt709'|
+| 'bt709'
 /** BT.470 BG (PAL) */
-'bt470bg'|
+| 'bt470bg'
 /** SMPTE 170M (NTSC) */
-'smpte170m'|
+| 'smpte170m'
 /** BT.2020 (UHD) */
-'bt2020'|
+| 'bt2020'
 /** SMPTE 432 (DCI-P3) */
-'smpte432';
+| 'smpte432'
 
 /** Options for addEventListener (W3C DOM spec) */
 export interface VideoDecoderAddEventListenerOptions {
@@ -1770,11 +1800,11 @@ export interface VideoDecoderSupport {
 
 /** Bitrate mode for video encoding (W3C WebCodecs spec) */
 export type VideoEncoderBitrateMode = /** Variable bitrate (default) */
-'variable'|
+| 'variable'
 /** Constant bitrate */
-'constant'|
+| 'constant'
 /** Use quantizer parameter from codec-specific options */
-'quantizer';
+| 'quantizer'
 
 /** Encode options per WebCodecs spec */
 export interface VideoEncoderEncodeOptions {
@@ -1858,9 +1888,7 @@ export interface VideoFrameInit {
  * VideoFrameMetadata - metadata associated with a VideoFrame (W3C spec)
  * Members defined in VideoFrame Metadata Registry - currently empty per spec
  */
-export interface VideoFrameMetadata {
-
-}
+export interface VideoFrameMetadata {}
 
 /** Rectangle for specifying a region */
 export interface VideoFrameRect {
@@ -1872,75 +1900,75 @@ export interface VideoFrameRect {
 
 /** Video matrix coefficients (W3C WebCodecs spec) */
 export type VideoMatrixCoefficients = /** RGB (identity matrix) */
-'rgb'|
+| 'rgb'
 /** BT.709 */
-'bt709'|
+| 'bt709'
 /** BT.470 BG */
-'bt470bg'|
+| 'bt470bg'
 /** SMPTE 170M */
-'smpte170m'|
+| 'smpte170m'
 /** BT.2020 non-constant luminance */
-'bt2020-ncl';
+| 'bt2020-ncl'
 
 /** Video pixel format (WebCodecs spec) */
 export type VideoPixelFormat = /** Planar YUV 4:2:0| 12bpp| (1 Cr & Cb sample per 2x2 Y samples) */
-'I420'|
+| 'I420'
 /** Planar YUV 4:2:0| 12bpp| with alpha plane */
-'I420A'|
+| 'I420A'
 /** Planar YUV 4:2:2| 16bpp */
-'I422'|
+| 'I422'
 /** Planar YUV 4:2:2| 16bpp| with alpha plane */
-'I422A'|
+| 'I422A'
 /** Planar YUV 4:4:4| 24bpp */
-'I444'|
+| 'I444'
 /** Planar YUV 4:4:4| 24bpp| with alpha plane */
-'I444A'|
+| 'I444A'
 /** Planar YUV 4:2:0| 10-bit */
-'I420P10'|
+| 'I420P10'
 /** Planar YUV 4:2:0| 10-bit| with alpha plane */
-'I420AP10'|
+| 'I420AP10'
 /** Planar YUV 4:2:2| 10-bit */
-'I422P10'|
+| 'I422P10'
 /** Planar YUV 4:2:2| 10-bit| with alpha plane */
-'I422AP10'|
+| 'I422AP10'
 /** Planar YUV 4:4:4| 10-bit */
-'I444P10'|
+| 'I444P10'
 /** Planar YUV 4:4:4| 10-bit| with alpha plane */
-'I444AP10'|
+| 'I444AP10'
 /** Planar YUV 4:2:0| 12-bit */
-'I420P12'|
+| 'I420P12'
 /** Planar YUV 4:2:2| 12-bit */
-'I422P12'|
+| 'I422P12'
 /** Planar YUV 4:4:4| 12-bit */
-'I444P12'|
+| 'I444P12'
 /** Semi-planar YUV 4:2:0| 12bpp (Y plane + interleaved UV) */
-'NV12'|
+| 'NV12'
 /** Semi-planar YUV 4:2:0| 12bpp (Y plane + interleaved VU) - per W3C WebCodecs spec */
-'NV21'|
+| 'NV21'
 /** RGBA 32bpp */
-'RGBA'|
+| 'RGBA'
 /** RGBX 32bpp (alpha ignored) */
-'RGBX'|
+| 'RGBX'
 /** BGRA 32bpp */
-'BGRA'|
+| 'BGRA'
 /** BGRX 32bpp (alpha ignored) */
-'BGRX';
+| 'BGRX'
 
 /** Video transfer characteristics (W3C WebCodecs spec) */
 export type VideoTransferCharacteristics = /** BT.709 transfer */
-'bt709'|
+| 'bt709'
 /** SMPTE 170M transfer */
-'smpte170m'|
+| 'smpte170m'
 /** IEC 61966-2-1 (sRGB) - technical name */
-'iec61966-2-1'|
+| 'iec61966-2-1'
 /** sRGB transfer (alias for iec61966-2-1) */
-'srgb'|
+| 'srgb'
 /** Linear transfer */
-'linear'|
+| 'linear'
 /** Perceptual Quantizer (HDR) */
-'pq'|
+| 'pq'
 /** Hybrid Log-Gamma (HDR) */
-'hlg';
+| 'hlg'
 
 /** Audio track configuration for WebM muxer */
 export interface WebMAudioTrackConfig {