node-av 3.1.2 → 4.0.0

package/dist/lib/sync-queue.d.ts

@@ -0,0 +1,179 @@
+import type { NativeSyncQueue, NativeWrapper } from './native-types.js';
+import type { Packet } from './packet.js';
+/**
+ * Sync Queue Type
+ *
+ * Determines the sync queue behavior for different media types.
+ */
+export declare enum SyncQueueType {
+    /**
+     * Buffer packets based on their duration in time base units.
+     * Used for audio and video streams.
+     */
+    PACKETS = 0,
+    /**
+     * Buffer frames based on their sample count.
+     * Used for audio frames where synchronization is sample-based.
+     */
+    FRAMES = 1
+}
+/**
+ * Sync Queue for packet synchronization
+ *
+ * FFmpeg's native sync_queue from fftools that synchronizes packets from multiple
+ * streams before muxing. Prevents streams from getting ahead of each other and
+ * ensures proper interleaving for containers with strict timing requirements.
+ *
+ * This is the same synchronization mechanism used by FFmpeg CLI (fftools).
+ *
+ * Direct mapping to FFmpeg's SyncQueue from fftools/sync_queue.h.
+ *
+ * @example
+ * ```typescript
+ * import { SyncQueue, SyncQueueType } from 'node-av';
+ *
+ * // Create sync queue with 1 second buffer
+ * const sq = SyncQueue.create(SyncQueueType.PACKETS, 1000000);
+ *
+ * // Add streams
+ * const videoIdx = sq.addStream(1);  // 1 = limiting stream
+ * const audioIdx = sq.addStream(1);
+ *
+ * // Send packets to queue
+ * sq.send(videoIdx, videoPacket);
+ * sq.send(audioIdx, audioPacket);
+ *
+ * // Receive synchronized packets
+ * const result = sq.receive(-1);  // -1 = any stream
+ * if (result.error === 0) {
+ *   console.log(`Stream ${result.streamIdx}: ${result.packet}`);
+ *   // Write packet to muxer...
+ * }
+ *
+ * // Cleanup
+ * sq.free();
+ * ```
+ *
+ * @see [sync_queue.h](https://github.com/FFmpeg/FFmpeg/blob/master/fftools/sync_queue.h) - FFmpeg source
+ */
+export declare class SyncQueue implements Disposable, NativeWrapper<NativeSyncQueue> {
+    /** @internal */
+    native: NativeSyncQueue;
+    private constructor();
+    /**
+     * Create a new sync queue.
+     *
+     * @param type - Queue type (PACKETS or FRAMES)
+     *
+     * @param bufferSizeUs - Buffer size in microseconds (default: 100ms)
+     *
+     * @returns New SyncQueue instance
+     *
+     * @example
+     * ```typescript
+     * // 500ms buffer for RTSP streams
+     * const sq = SyncQueue.create(SyncQueueType.PACKETS, 500000);
+     * ```
+     */
+    static create(type?: SyncQueueType, bufferSizeUs?: number): SyncQueue;
+    /**
+     * Add a stream to the sync queue.
+     *
+     * @param limiting - Whether this stream should limit other streams (1 = yes, 0 = no).
+     *                   Limiting streams control the head position - other streams cannot get ahead.
+     *
+     * @returns Stream index in the sync queue
+     *
+     * @example
+     * ```typescript
+     * const videoIdx = sq.addStream(1);  // Video limits timing
+     * const audioIdx = sq.addStream(1);  // Audio limits timing
+     * const subtitleIdx = sq.addStream(0);  // Subtitles don't limit
+     * ```
+     */
+    addStream(limiting?: number): number;
+    /**
+     * Send a packet to the sync queue.
+     *
+     * The packet is cloned internally, so the original can be reused/freed.
+     *
+     * To signal EOF for a stream, pass null as the packet.
+     * This tells the sync queue that no more packets will be sent for this stream.
+     *
+     * @param streamIdx - Stream index returned from addStream()
+     *
+     * @param packet - Packet to send, or null to signal EOF
+     *
+     * @returns 0 on success, AVERROR_EOF if EOF, negative on error
+     *
+     * @example
+     * ```typescript
+     * // Send normal packet
+     * const ret = sq.send(videoIdx, packet);
+     * if (ret === AVERROR_EOF) {
+     *   console.log('Stream finished');
+     * }
+     *
+     * // Signal EOF for stream
+     * sq.send(videoIdx, null);
+     * ```
+     */
+    send(streamIdx: number, packet: Packet | null): number;
+    /**
+     * Receive a packet from the sync queue.
+     *
+     * This will receive the next packet that should be written to maintain
+     * proper synchronization between streams. The packet parameter is filled
+     * with the received data.
+     *
+     * @param streamIdx - Stream index to receive from, or -1 for any stream
+     *
+     * @param packet - Packet to fill with received data (output parameter)
+     *
+     * @returns Stream index (>= 0) on success, or negative error code:
+     *          - >= 0: Stream index that the packet belongs to
+     *          - AVERROR(EAGAIN): No packets ready yet, more frames needed
+     *          - AVERROR_EOF: All streams finished
+     *
+     * @example
+     * ```typescript
+     * import { AVERROR } from 'node-av';
+     *
+     * // Receive from any stream (FFmpeg mux pattern)
+     * const packet = new Packet();
+     * while (true) {
+     *   const ret = sq.receive(-1, packet);
+     *   if (ret === AVERROR('EAGAIN')) {
+     *     break;  // No packets ready
+     *   }
+     *   if (ret === AVERROR_EOF) {
+     *     break;  // All streams finished
+     *   }
+     *   if (ret >= 0) {
+     *     // ret is the stream index
+     *     await muxer.interleavedWriteFrame(packet);
+     *   }
+     * }
+     * ```
+     */
+    receive(streamIdx: number, packet: Packet): number;
+    /**
+     * Free the sync queue and all buffered packets.
+     * After calling this, the queue cannot be used anymore.
+     *
+     * @example
+     * ```typescript
+     * sq.free();
+     * ```
+     */
+    free(): void;
+    /**
+     * Get the underlying native SyncQueue object.
+     *
+     * @returns The native SyncQueue binding object
+     *
+     * @internal
+     */
+    getNative(): NativeSyncQueue;
+    [Symbol.dispose](): void;
+}

package/dist/lib/sync-queue.js

@@ -0,0 +1,197 @@
+import { bindings } from './binding.js';
+/**
+ * Sync Queue Type
+ *
+ * Determines the sync queue behavior for different media types.
+ */
+export var SyncQueueType;
+(function (SyncQueueType) {
+    /**
+     * Buffer packets based on their duration in time base units.
+     * Used for audio and video streams.
+     */
+    SyncQueueType[SyncQueueType["PACKETS"] = 0] = "PACKETS";
+    /**
+     * Buffer frames based on their sample count.
+     * Used for audio frames where synchronization is sample-based.
+     */
+    SyncQueueType[SyncQueueType["FRAMES"] = 1] = "FRAMES";
+})(SyncQueueType || (SyncQueueType = {}));
+/**
+ * Sync Queue for packet synchronization
+ *
+ * FFmpeg's native sync_queue from fftools that synchronizes packets from multiple
+ * streams before muxing. Prevents streams from getting ahead of each other and
+ * ensures proper interleaving for containers with strict timing requirements.
+ *
+ * This is the same synchronization mechanism used by FFmpeg CLI (fftools).
+ *
+ * Direct mapping to FFmpeg's SyncQueue from fftools/sync_queue.h.
+ *
+ * @example
+ * ```typescript
+ * import { SyncQueue, SyncQueueType } from 'node-av';
+ *
+ * // Create sync queue with 1 second buffer
+ * const sq = SyncQueue.create(SyncQueueType.PACKETS, 1000000);
+ *
+ * // Add streams
+ * const videoIdx = sq.addStream(1);  // 1 = limiting stream
+ * const audioIdx = sq.addStream(1);
+ *
+ * // Send packets to queue
+ * sq.send(videoIdx, videoPacket);
+ * sq.send(audioIdx, audioPacket);
+ *
+ * // Receive synchronized packets
+ * const result = sq.receive(-1);  // -1 = any stream
+ * if (result.error === 0) {
+ *   console.log(`Stream ${result.streamIdx}: ${result.packet}`);
+ *   // Write packet to muxer...
+ * }
+ *
+ * // Cleanup
+ * sq.free();
+ * ```
+ *
+ * @see [sync_queue.h](https://github.com/FFmpeg/FFmpeg/blob/master/fftools/sync_queue.h) - FFmpeg source
+ */
+export class SyncQueue {
+    /** @internal */
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    /**
+     * Create a new sync queue.
+     *
+     * @param type - Queue type (PACKETS or FRAMES)
+     *
+     * @param bufferSizeUs - Buffer size in microseconds (default: 100ms)
+     *
+     * @returns New SyncQueue instance
+     *
+     * @example
+     * ```typescript
+     * // 500ms buffer for RTSP streams
+     * const sq = SyncQueue.create(SyncQueueType.PACKETS, 500000);
+     * ```
+     */
+    static create(type = SyncQueueType.PACKETS, bufferSizeUs = 100000) {
+        const native = bindings.SyncQueue.create(type, bufferSizeUs);
+        return new SyncQueue(native);
+    }
+    /**
+     * Add a stream to the sync queue.
+     *
+     * @param limiting - Whether this stream should limit other streams (1 = yes, 0 = no).
+     *                   Limiting streams control the head position - other streams cannot get ahead.
+     *
+     * @returns Stream index in the sync queue
+     *
+     * @example
+     * ```typescript
+     * const videoIdx = sq.addStream(1);  // Video limits timing
+     * const audioIdx = sq.addStream(1);  // Audio limits timing
+     * const subtitleIdx = sq.addStream(0);  // Subtitles don't limit
+     * ```
+     */
+    addStream(limiting = 1) {
+        return this.native.addStream(limiting);
+    }
+    /**
+     * Send a packet to the sync queue.
+     *
+     * The packet is cloned internally, so the original can be reused/freed.
+     *
+     * To signal EOF for a stream, pass null as the packet.
+     * This tells the sync queue that no more packets will be sent for this stream.
+     *
+     * @param streamIdx - Stream index returned from addStream()
+     *
+     * @param packet - Packet to send, or null to signal EOF
+     *
+     * @returns 0 on success, AVERROR_EOF if EOF, negative on error
+     *
+     * @example
+     * ```typescript
+     * // Send normal packet
+     * const ret = sq.send(videoIdx, packet);
+     * if (ret === AVERROR_EOF) {
+     *   console.log('Stream finished');
+     * }
+     *
+     * // Signal EOF for stream
+     * sq.send(videoIdx, null);
+     * ```
+     */
+    send(streamIdx, packet) {
+        return this.native.send(streamIdx, packet?.getNative() ?? null);
+    }
+    /**
+     * Receive a packet from the sync queue.
+     *
+     * This will receive the next packet that should be written to maintain
+     * proper synchronization between streams. The packet parameter is filled
+     * with the received data.
+     *
+     * @param streamIdx - Stream index to receive from, or -1 for any stream
+     *
+     * @param packet - Packet to fill with received data (output parameter)
+     *
+     * @returns Stream index (>= 0) on success, or negative error code:
+     *          - >= 0: Stream index that the packet belongs to
+     *          - AVERROR(EAGAIN): No packets ready yet, more frames needed
+     *          - AVERROR_EOF: All streams finished
+     *
+     * @example
+     * ```typescript
+     * import { AVERROR } from 'node-av';
+     *
+     * // Receive from any stream (FFmpeg mux pattern)
+     * const packet = new Packet();
+     * while (true) {
+     *   const ret = sq.receive(-1, packet);
+     *   if (ret === AVERROR('EAGAIN')) {
+     *     break;  // No packets ready
+     *   }
+     *   if (ret === AVERROR_EOF) {
+     *     break;  // All streams finished
+     *   }
+     *   if (ret >= 0) {
+     *     // ret is the stream index
+     *     await muxer.interleavedWriteFrame(packet);
+     *   }
+     * }
+     * ```
+     */
+    receive(streamIdx, packet) {
+        return this.native.receive(streamIdx, packet.getNative());
+    }
+    /**
+     * Free the sync queue and all buffered packets.
+     * After calling this, the queue cannot be used anymore.
+     *
+     * @example
+     * ```typescript
+     * sq.free();
+     * ```
+     */
+    free() {
+        this.native.free();
+    }
+    /**
+     * Get the underlying native SyncQueue object.
+     *
+     * @returns The native SyncQueue binding object
+     *
+     * @internal
+     */
+    getNative() {
+        return this.native;
+    }
+    [Symbol.dispose]() {
+        this.free();
+    }
+}
+//# sourceMappingURL=sync-queue.js.map

package/dist/lib/sync-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-queue.js","sourceRoot":"","sources":["../../src/lib/sync-queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC;;;;GAIG;AACH,MAAM,CAAN,IAAY,aAYX;AAZD,WAAY,aAAa;IACvB;;;OAGG;IACH,uDAAW,CAAA;IAEX;;;OAGG;IACH,qDAAU,CAAA;AACZ,CAAC,EAZW,aAAa,KAAb,aAAa,QAYxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,OAAO,SAAS;IACpB,gBAAgB;IACT,MAAM,CAAkB;IAE/B,YAAoB,MAAuB;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,MAAM,CAAC,OAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;QAC9E,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC7D,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,QAAQ,GAAG,CAAC;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,IAAI,CAAC,SAAiB,EAAE,MAAqB;QAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,OAAO,CAAC,SAAiB,EAAE,MAAc;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF"}

package/dist/lib/types.d.ts

@@ -4,7 +4,7 @@
  * Types that are used across multiple modules but are not
  * directly from FFmpeg constants.
  */
-import type { AVLogLevel, AVMediaType } from '../constants/constants.ts';
+import type { AVCodecID, AVLogLevel, AVMediaType } from '../constants/constants.ts';
 /**
  * Rational number (fraction) interface
  * Maps to AVRational in FFmpeg
@@ -16,6 +16,15 @@ export interface IRational {
     /** Denominator */
     den: number;
 }
+/**
+ * Video dimension interface
+ */
+export interface IDimension {
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
 /**
  * Audio channel layout description
  * Maps to AVChannelLayout in FFmpeg
@@ -91,3 +100,20 @@ export interface ImageOptions {
     crop?: ImageCrop;
     resize?: ImageResize;
 }
+/**
+ * RTSP stream information interface
+ * Maps to RTSPStreamInfo returned by FormatContext.getRTSPStreamInfo()
+ */
+export interface RTSPStreamInfo {
+    streamIndex: number;
+    controlUrl: string;
+    transport: 'tcp' | 'udp' | 'udp_multicast' | 'unknown';
+    payloadType: number;
+    codecId: AVCodecID;
+    mediaType: 'video' | 'audio' | 'data' | 'subtitle' | 'unknown';
+    mimeType: string;
+    sampleRate?: number;
+    channels?: number;
+    direction: 'sendonly' | 'recvonly' | 'sendrecv' | 'inactive';
+    fmtp?: string;
+}