node-av 3.1.2 → 4.0.0

package/README.md

@@ -90,10 +90,6 @@ decoderCtx.allocContext3(codec);
 ret = decoderCtx.parametersToContext(videoStream.codecpar);
 FFmpegError.throwIfError(ret, 'Could not copy codec parameters to decoder context');
 
-// Inform the decoder about the timebase for packet timestamps and the frame rate
-decoderCtx.pktTimebase = videoStream.timeBase;
-decoderCtx.framerate = videoStream.rFrameRate || videoStream.avgFrameRate || new Rational(25, 1);
-
 // Open decoder context
 ret = await decoderCtx.open2(codec, null);
 FFmpegError.throwIfError(ret, 'Could not open codec');
@@ -140,49 +136,45 @@ while (true) {
 Higher-level abstractions for common tasks like decoding, encoding, filtering, and transcoding. Easier to use while still providing access to low-level details when needed.
 
 ```typescript
-import { Decoder, Encoder, MediaInput, MediaOutput } from 'node-av/api';
+import { Decoder, Demuxer, Encoder, HardwareContext, Muxer } from 'node-av/api';
 import { FF_ENCODER_LIBX264 } from 'node-av/constants';
 
-// Open media
-await using input = await MediaInput.open('input.mp4');
-await using output = await MediaOutput.open('output.mp4');
+// Open Demuxer
+await using input = await Demuxer.open('input.mp4');
 
 // Get video stream
 const videoStream = input.video()!;
 
+// Optional, setup hardware acceleration
+using hw = HardwareContext.auto();
+
 // Create decoder
-using decoder = await Decoder.create(videoStream);
+using decoder = await Decoder.create(videoStream, {
+  hardware: hw, // Optional, use hardware acceleration if available
+});
 
 // Create encoder
 using encoder = await Encoder.create(FF_ENCODER_LIBX264, {
-  timeBase: videoStream.timeBase,
-  frameRate: videoStream.avgFrameRate,
+  decoder, // Optional, copy settings from decoder
 });
 
-// Add stream to output
-const outputIndex = output.addStream(encoder);
+// Open Muxer
+await using output = await Muxer.open('output.mp4', {
+  input, // Optional, used to copy global headers and metadata
+});
 
-// Process packets
-for await (using packet of input.packets(videoStream.index)) {
-  using frame = await decoder.decode(packet);
-  if (frame) {
-    using encoded = await encoder.encode(frame);
-    if (encoded) {
-      await output.writePacket(encoded, outputIndex);
-    }
-  }
-}
+// Add stream to output
+const outputIndex = output.addStream(encoder, {
+  inputStream: videoStream, // Optional, copy settings from input stream
+});
 
-// Flush decoder
-for await (using frame of decoder.flushFrames()) {
-  using encoded = await encoder.encode(frame);
-  if (encoded) {
-    await output.writePacket(encoded, outputIndex);
-  }
-}
+// Create processing generators
+const inputGenerator = input.packets(videoStream.index);
+const decoderGenerator = decoder.frames(inputGenerator);
+const encoderGenerator = encoder.packets(decoderGenerator);
 
-// Flush encoder
-for await (using packet of encoder.flushPackets()) {
+// Process packets
+for await (using packet of encoderGenerator) {
   await output.writePacket(packet, outputIndex);
 }
 
@@ -194,15 +186,33 @@ for await (using packet of encoder.flushPackets()) {
 A simple way to chain together multiple processing steps like decoding, filtering, encoding, and muxing.
 
 ```typescript
-import { pipeline, MediaInput, MediaOutput, Decoder, Encoder } from 'node-av/api';
+import { Decoder, Demuxer, Encoder, HardwareContext, Muxer, pipeline } from 'node-av/api';
+import { FF_ENCODER_LIBX264 } from 'node-av/constants';
 
 // Simple transcode pipeline: input → decoder → encoder → output
-const input = await MediaInput.open('input.mp4');
-const output = await MediaOutput.open('output.mp4');
-const decoder = await Decoder.create(input.video());
-const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
-  timeBase: videoStream.timeBase,
-  frameRate: videoStream.avgFrameRate,
+
+// Open Demuxer
+await using input = await Demuxer.open('input.mp4');
+
+// Get video stream
+const videoStream = input.video()!;
+
+// Optional, setup hardware acceleration
+using hw = HardwareContext.auto();
+
+// Create decoder
+using decoder = await Decoder.create(videoStream, {
+  hardware: hw, // Optional, use hardware acceleration if available
+});
+
+// Create encoder
+using encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+  decoder, // Optional, copy settings from decoder
+});
+
+// Open Muxer
+await using output = await Muxer.open('output.mp4', {
+  input, // Optional, used to copy global headers and metadata
 });
 
 const control = pipeline(input, decoder, encoder, output);
@@ -231,8 +241,7 @@ const decoder = await Decoder.create(stream, {
 // Use with encoder (use hardware-specific codec)
 const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_LIBX264;
 const encoder = await Encoder.create(encoderCodec, {
-  timeBase: videoStream.timeBase,
-  frameRate: videoStream.avgFrameRate,
+  decoder,
 });
 ```
 
@@ -252,7 +261,7 @@ The library provides multiple entry points for optimal tree shaking:
 
 ```typescript
 // High-Level API only - Recommended for most use cases
-import { MediaInput, MediaOutput, Decoder, Encoder } from 'node-av/api';
+import { Muxer, Muxer, Decoder, Encoder } from 'node-av/api';
 
 // Low-Level API only - Direct FFmpeg bindings
 import { FormatContext, CodecContext, Frame, Packet } from 'node-av/lib';
@@ -272,11 +281,11 @@ import * as ffmpeg from 'node-av';
 ### From Files or Network
 
 ```typescript
-const media = await MediaInput.open('input.mp4');
+const media = await Muxer.open('input.mp4');
 
 // or
 
-const media = await MediaInput.open('rtsp://example.com/stream');
+const media = await Muxer.open('rtsp://example.com/stream');
 ```
 
 ### From Buffers
@@ -285,7 +294,7 @@ const media = await MediaInput.open('rtsp://example.com/stream');
 import { readFile } from 'fs/promises';
 
 const buffer = await readFile('input.mp4');
-const media = await MediaInput.open(buffer);
+const media = await Muxer.open(buffer);
 ```
 
 ### Custom I/O Callbacks
@@ -305,7 +314,7 @@ const inputCallbacks: IOInputCallbacks = {
   }
 };
 
-await using input = await MediaInput.open(inputCallbacks, {
+await using input = await Muxer.open(inputCallbacks, {
   format: 'mp4'
 });
 ```
@@ -314,7 +323,7 @@ await using input = await MediaInput.open(inputCallbacks, {
 
 ```typescript
 // Raw video input
-const rawVideo = await MediaInput.open({
+const rawVideo = await Muxer.open({
   type: 'video',
   input: 'input.yuv',
   width: 1280,
@@ -324,7 +333,7 @@ const rawVideo = await MediaInput.open({
 });
 
 // Raw audio input
-const rawAudio = await MediaInput.open({
+const rawAudio = await Muxer.open({
   type: 'audio',
   input: 'input.pcm',
   sampleRate: 48000,
@@ -342,13 +351,13 @@ The library supports automatic resource cleanup using the Disposable pattern:
 ```typescript
 // Automatic cleanup with 'using'
 {
-  await using media = await MediaInput.open('input.mp4');
+  await using media = await Muxer.open('input.mp4');
   using decoder = await Decoder.create(media.video());
   // Resources automatically cleaned up at end of scope
 }
 
 // Manual cleanup
-const media = await MediaInput.open('input.mp4');
+const media = await Muxer.open('input.mp4');
 try {
   // Process media
 } finally {
@@ -420,18 +429,22 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 | `browser-webrtc` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/browser/webrtc) |
 | `api-dash` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-dash.ts) |
 | `api-encode-decode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-encode-decode.ts) |
+| `api-fmp4` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-fmp4.ts) |
 | `api-frame-extract` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-frame-extract.ts) |
+| `api-hw-codecs` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-codecs.ts) |
 | `api-hw-decode-sw-encode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-decode-sw-encode.ts) |
 | `api-hw-raw` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-raw.ts) |
 | `api-hw-raw-output` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-raw-output.ts) |
-| `api-hw-rtsp-custom-io` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-rtsp-custom-io.ts) |
 | `api-hw-rtsp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-rtsp.ts) |
+| `api-hw-stream-custom-io` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-stream-custom-io.ts) |
 | `api-hw-transcode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-transcode.ts) |
 | `api-hw-filter-sync` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-filter-sync.ts) |
 | `api-muxing` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-muxing.ts) |
 | `api-pipeline-hw-rtsp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-pipeline-hw-rtsp.ts) |
 | `api-pipeline-raw-muxing` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-pipeline-raw-muxing.ts) |
-| `api-sdp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sdp.ts) |
+| `api-rtp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-rtp.ts) |
+| `api-sdp-custom` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sdp-custom.ts) |
+| `api-sdp-input` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sdp-input.ts) |
 | `api-stream-input` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-stream-input.ts) |
 | `api-sw-decode-hw-encode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sw-decode-hw-encode.ts) |
 | `api-sw-transcode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sw-transcode.ts) |

package/binding.gyp

@@ -57,11 +57,14 @@
                 "src/bindings/bitstream_filter_context_async.cc",
                 "src/bindings/bitstream_filter_context_sync.cc",
                 "src/bindings/option.cc",
+                "src/bindings/sync_queue.cc",
+                "externals/jellyfin-ffmpeg/fftools/sync_queue.c",
             ],
             "include_dirs": [
                 "<!@(node -p \"require('node-addon-api').include\")",
                 "/opt/ffbuild/prefix/include",
                 "<(module_root_dir)/externals/jellyfin-ffmpeg",
+                "<(module_root_dir)/externals/jellyfin-ffmpeg/libavcodec",
             ],
             "library_dirs": ["/opt/ffbuild/prefix/lib"],
             "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
@@ -102,6 +105,7 @@
                 "/opt/ffbuild/prefix/lib/libudfread.a",
                 "/opt/ffbuild/prefix/lib/libz.a",
                 "/opt/ffbuild/prefix/lib/liblzma.a",
+                "/opt/ffbuild/prefix/lib/libfdk-aac.a",
                 "<!@(ls /opt/ffbuild/prefix/lib/libNE10.a 2>/dev/null || echo '')",
                 "<!@(ls /opt/ffbuild/prefix/lib/libwebpdemux.a 2>/dev/null || echo '')",
                 "<!@(ls /opt/ffbuild/prefix/lib/libchromaprint.a 2>/dev/null || echo '')",

package/dist/api/audio-frame-buffer.d.ts

@@ -0,0 +1,201 @@
+import { Frame } from '../lib/frame.js';
+import type { AVSampleFormat } from '../constants/index.js';
+import type { ChannelLayout } from '../lib/types.js';
+/**
+ * Audio frame buffering utility for encoders with fixed frame size requirements.
+ *
+ * Many audio encoders (Opus, AAC, MP3, etc.) require frames with a specific number
+ * of samples (frame_size). This class buffers incoming frames and outputs frames
+ * with exactly the required size.
+ *
+ * Uses FFmpeg's AVAudioFifo internally for efficient sample buffering.
+ *
+ * @example
+ * ```typescript
+ * import { AudioFrameBuffer } from 'node-av/api';
+ *
+ * // Create buffer for 480-sample frames (e.g., Opus at 24kHz)
+ * using buffer = AudioFrameBuffer.create(480, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1);
+ *
+ * // Push variable-sized frames from filter
+ * for await (const frame of filterOutput) {
+ *   await buffer.push(frame);
+ *
+ *   // Pull fixed-size frames for encoder
+ *   let outputFrame;
+ *   while ((outputFrame = await buffer.pull()) !== null) {
+ *     await encoder.encode(outputFrame);
+ *     outputFrame.free();
+ *   }
+ * }
+ *
+ * // Flush remaining samples
+ * let outputFrame;
+ * while ((outputFrame = await buffer.pull()) !== null) {
+ *   await encoder.encode(outputFrame);
+ *   outputFrame.free();
+ * }
+ * ```
+ */
+export declare class AudioFrameBuffer implements Disposable {
+    private fifo;
+    private frame;
+    private frameSize;
+    private nextPts;
+    private firstFramePts;
+    /**
+     * @param fifo - Underlying AudioFifo instance
+     *
+     * @param frameSize - Number of samples per output frame
+     *
+     * @param sampleFormat - Audio sample format
+     *
+     * @param sampleRate - Sample rate in Hz
+     *
+     * @param channelLayout - Channel layout
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create an audio frame buffer.
+     *
+     * @param frameSize - Required frame size in samples
+     *
+     * @param sampleFormat - Audio sample format
+     *
+     * @param sampleRate - Sample rate in Hz
+     *
+     * @param channelLayout - Channel layout (e.g., 'mono', 'stereo')
+     *
+     * @param channels - Number of audio channels
+     *
+     * @returns Configured audio frame buffer
+     *
+     * @example
+     * ```typescript
+     * // For Opus encoder at 48kHz with 20ms frames
+     * const buffer = AudioFrameBuffer.create(960, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1);
+     * ```
+     */
+    static create(frameSize: number, sampleFormat: AVSampleFormat, sampleRate: number, channelLayout: ChannelLayout, channels: number): AudioFrameBuffer;
+    /**
+     * Get number of samples currently in buffer.
+     *
+     * @returns Number of buffered samples
+     *
+     * @example
+     * ```typescript
+     * console.log(`Buffer contains ${buffer.size} samples`);
+     * ```
+     */
+    get size(): number;
+    /**
+     * Check if a complete frame is available.
+     *
+     * Returns true if the FIFO contains at least frameSize samples.
+     *
+     * @returns True if a full frame can be pulled
+     *
+     * @example
+     * ```typescript
+     * while (buffer.hasFrame()) {
+     *   const frame = buffer.pull();
+     *   // Process frame...
+     * }
+     * ```
+     */
+    hasFrame(): boolean;
+    /**
+     * Push an audio frame into the buffer asynchronously.
+     *
+     * The frame's samples are added to the internal FIFO.
+     * Call hasFrame() and pull() to retrieve fixed-size output frames.
+     *
+     * @param frame - Audio frame to buffer
+     *
+     * @example
+     * ```typescript
+     * await buffer.push(filterFrame);
+     * ```
+     *
+     * @see {@link pushSync} For synchronous version
+     */
+    push(frame: Frame): Promise<void>;
+    /**
+     * Push an audio frame into the buffer synchronously.
+     * Synchronous version of push.
+     *
+     * The frame's samples are added to the internal FIFO.
+     * Call hasFrame() and pullSync() to retrieve fixed-size output frames.
+     *
+     * @param frame - Audio frame to buffer
+     *
+     * @example
+     * ```typescript
+     * buffer.pushSync(filterFrame);
+     * ```
+     *
+     * @see {@link push} For async version
+     */
+    pushSync(frame: Frame): void;
+    /**
+     * Pull a fixed-size audio frame from the buffer asynchronously.
+     *
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * Returns null if not enough samples are available.
+     * Reuses internal frame buffer for efficiency (like Decoder does).
+     *
+     * @returns Audio frame with exactly frameSize samples, or null if insufficient samples
+     *
+     * @example
+     * ```typescript
+     * using frame = await buffer.pull();
+     * if (frame) {
+     *   await encoder.encode(frame);
+     * }
+     * ```
+     *
+     * @see {@link pullSync} For synchronous version
+     */
+    pull(): Promise<Frame | null>;
+    /**
+     * Pull a fixed-size audio frame from the buffer synchronously.
+     * Synchronous version of pull.
+     *
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * Returns null if not enough samples are available.
+     * Reuses internal frame buffer for efficiency (like Decoder does).
+     *
+     * @returns Audio frame with exactly frameSize samples, or null if insufficient samples
+     *
+     * @example
+     * ```typescript
+     * using frame = buffer.pullSync();
+     * if (frame) {
+     *   encoder.encodeSync(frame);
+     * }
+     * ```
+     *
+     * @see {@link pull} For async version
+     */
+    pullSync(): Frame | null;
+    /**
+     * Reset the buffer, discarding all buffered samples.
+     *
+     * @example
+     * ```typescript
+     * buffer.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Free the buffer and all resources.
+     *
+     * @example
+     * ```typescript
+     * buffer.free();
+     * ```
+     */
+    [Symbol.dispose](): void;
+}