node-av-light 0.0.0 → 7.1.0-beta.1

package/dist/api/fmp4-stream.d.ts

@@ -0,0 +1,797 @@
+import { Demuxer } from './demuxer.js';
+import type { AVHWDeviceType, FFHWDeviceType } from '../constants/index.js';
+import type { DemuxerOptions } from './demuxer.js';
+import type { EncoderOptions } from './encoder.js';
+import type { MediaFrameSource } from './types.js';
+export type MP4BoxType = 'ftyp' | 'styp' | 'moov' | 'moof' | 'mdat' | 'free' | 'skip' | 'sidx' | 'emsg' | 'mvhd' | 'trak' | 'mvex' | 'trex' | 'mehd' | 'mfhd' | 'traf' | 'tfhd' | 'tfdt' | 'trun' | 'sdtp' | 'tkhd' | 'mdia' | 'minf' | 'stbl' | 'meta' | 'udta' | (string & {});
+/**
+ * MP4 box information.
+ */
+export interface MP4Box {
+    /** Four-character code identifying the box type (e.g., 'ftyp', 'moov', 'moof') */
+    type: MP4BoxType;
+    /** Total size of the box in bytes (including the 8-byte header, or 16-byte for 64-bit boxes) */
+    size: number;
+    /** Box payload data (excluding the 8-byte header, or 16-byte for 64-bit boxes) */
+    data: Buffer;
+    /** Offset of this box in the original buffer */
+    offset: number;
+}
+/**
+ * A fragment of fMP4 data yielded by {@link FMP4Stream.fragments}.
+ */
+export interface FMP4Fragment {
+    /** fMP4 data buffer */
+    data: Buffer;
+    /** Box information (complete boxes, parsed box details) */
+    info: FMP4Data;
+}
+/**
+ * fMP4 data information provided in onData callback.
+ */
+export interface FMP4Data {
+    /**
+     * True if data contains complete MP4 boxes, false if raw chunks.
+     * When boxMode is enabled, this is always true.
+     */
+    isComplete: boolean;
+    /**
+     * Parsed MP4 boxes (only available when isComplete is true).
+     * Array is empty when isComplete is false.
+     */
+    boxes: MP4Box[];
+}
+/**
+ * Options for configuring fMP4 streaming.
+ */
+export interface FMP4StreamOptions {
+    /**
+     * Callback invoked for fMP4 data (chunks or complete boxes).
+     *
+     * @param data - fMP4 data information with buffer and box details
+     */
+    onData?: (data: Buffer, info: FMP4Data) => void;
+    /**
+     * Callback invoked when the stream is closed or encounters an error.
+     *
+     * Called once per started session. On an error the stream has already been
+     * stopped and its resources (including the input connection) released.
+     * Output the muxer still held at the error is discarded, so no `onData` call
+     * follows the failure. Exceptions thrown by the callback are logged and do
+     * not propagate.
+     *
+     * @param error - Optional error if stream closed due to an error
+     */
+    onClose?: (error?: Error) => void;
+    /**
+     * Supported codec strings from client.
+     * Comma-separated list (e.g., "avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2,flac,opus").
+     *
+     * @example "avc1.640029,mp4a.40.2"
+     */
+    supportedCodecs?: string;
+    /**
+     * Fragment duration in microseconds.
+     *
+     * Passed to the mp4 muxer as `frag_duration`, which creates a new fragment
+     * whenever the current one exceeds this duration (in addition to any cuts
+     * requested via movFlags such as `frag_keyframe`).
+     * Smaller values reduce latency but increase overhead.
+     * Set to 1 to send data as soon as possible.
+     * Transcoded video gets a GOP of the fragment duration from 0.5 s on, so
+     * every fragment starts with a keyframe; below that, and with 0, it gets a
+     * 2 s GOP.
+     *
+     * @default 1
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   fragDuration: 2_000_000, // 2 seconds in microseconds
+     * });
+     * ```
+     */
+    fragDuration?: number;
+    /**
+     * Maximum number of media fragments buffered for a {@link FMP4Stream.fragments}
+     * consumer before the oldest are dropped.
+     *
+     * Live sources (RTSP cameras) produce fragments at a fixed rate regardless of
+     * consumer speed. Without a bound, a slow or stalled consumer would grow the
+     * queue until the process runs out of memory. When the backlog exceeds this
+     * limit, the oldest media fragments are dropped (never the init segment,
+     * which is kept separately via {@link FMP4Stream.initSegment}) and
+     * {@link FMP4Stream.droppedFragments} is incremented.
+     *
+     * @default 16
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   boxMode: true,
+     *   maxQueuedFragments: 8,
+     * });
+     *
+     * await stream.start();
+     * for await (const fragment of stream.fragments()) {
+     *   await sendToClient(fragment.data); // Slow consumer - oldest fragments dropped
+     * }
+     * console.log(`Dropped ${stream.droppedFragments} fragments`);
+     * ```
+     */
+    maxQueuedFragments?: number;
+    /**
+     * Hardware acceleration configuration for video transcoding.
+     *
+     * - `'auto'` - Automatically detect and use available hardware acceleration
+     * - Object with deviceType - Manually specify hardware acceleration type
+     *
+     * @default { deviceType: AV_HWDEVICE_TYPE_NONE }
+     */
+    hardware?: 'auto' | {
+        deviceType: AVHWDeviceType | FFHWDeviceType;
+        device?: string;
+        options?: Record<string, string>;
+    };
+    /**
+     * Input media options passed to Demuxer.
+     */
+    inputOptions?: DemuxerOptions;
+    /**
+     * Video stream configuration.
+     */
+    video?: {
+        fps?: number;
+        width?: number;
+        height?: number;
+        bitrate?: number;
+        /**
+         * Transcode to H.264 even when the source codec is one of `supportedCodecs`, so `width`, `height`, `fps` and `bitrate` apply.
+         */
+        transcode?: boolean;
+        /**
+         * FourCC sample entry tag for the HEVC video stream, e.g. `hvc1`. Only applied to HEVC output.
+         */
+        tag?: string;
+        encoderOptions?: EncoderOptions['options'];
+    };
+    /**
+     * Audio stream configuration.
+     */
+    audio?: {
+        encoderOptions?: EncoderOptions['options'];
+    };
+    /**
+     * Buffer size for I/O operations in bytes (output).
+     *
+     * @default 2 MB
+     */
+    bufferSize?: number;
+    /**
+     * Enable box mode - buffers data until complete MP4 boxes are available.
+     * When true, onData receives complete boxes with parsed box information,
+     * and media fragments are emitted fragment-aligned: a callback that contains
+     * a `moof` always contains its `mdat` too, regardless of how the muxer's
+     * I/O buffer split the write (large fragments arrive in several chunks).
+     * When false, onData receives raw chunks as they arrive from FFmpeg.
+     *
+     * @default false
+     */
+    boxMode?: boolean;
+    /**
+     * MOV flags for fragmented MP4 output.
+     *
+     * @default '+frag_keyframe+separate_moof+default_base_moof+empty_moov'
+     */
+    movFlags?: string;
+    /**
+     * Backward DTS jump in seconds above which the stream ends with an error.
+     *
+     * A live source that restarts its clock (a camera reboot behind a restreamer)
+     * would otherwise leave every following packet clamped to one tick past the
+     * previous one, so fragments carry no media for as long as the jump. The stream
+     * instead stops and reports the error through `onClose(error)`, and the owner
+     * can restart it on a fresh timeline. Smaller jumps are clamped. `0` disables
+     * the check. Same semantics as the `Muxer` option of the same name.
+     *
+     * @default 10
+     */
+    dtsBackwardThreshold?: number;
+    /**
+     * Forward DTS jump in seconds, beyond the real time that passed, above which
+     * the stream ends with an error.
+     *
+     * A live source that restarts its clock (a camera reboot behind a
+     * restreamer) can continue with timestamps far ahead of the time that
+     * passed. Muxing that would leave a sample spanning the jump, or, when the
+     * timeline later returns, a stream clamped behind it. The stream instead
+     * stops and reports the error through `onClose(error)`, and the owner can
+     * restart it on a fresh timeline. Gaps in the source come with a matching
+     * wait and pass. Only meaningful for inputs read in real time, so it is off
+     * for files, a pre-opened Demuxer and frame sources unless set; pass it for
+     * live inputs read over HTTP (HLS, HTTP-FLV) as well. Same semantics as the
+     * `Muxer` option of the same name; `0` disables the check.
+     *
+     * @default 10 for rtsp, rtsps, rtmp (and rtmps, rtmpt, rtmpe, rtmpte, rtmpts), rtp, srtp, udp, srt, tcp, tls and sctp URLs, 0 otherwise
+     */
+    dtsForwardThreshold?: number;
+    /**
+     * Longest time in seconds a packet may wait inside the muxer before it is
+     * emitted in a fragment.
+     *
+     * The mp4 muxer holds packets back to interleave the streams by timestamp.
+     * When a stream's timestamps stop advancing or run far ahead of a silent
+     * stream (a camera restarting its clock behind a restreamer, missing
+     * timestamps), packets can pile up without ever being emitted while memory
+     * grows. The age is measured per stream in real time while the input
+     * delivers packets and is independent of the timestamps; once the oldest
+     * pending packet of any stream is older than this, the stream stops and
+     * reports the error through `onClose(error)`. A pause of the whole input
+     * counts at most 2 s, so a source that goes quiet and resumes does not end
+     * the session. Healthy sessions stay below the default: up to the fragment
+     * duration (the GOP length with `fragDuration: 0`) plus about 10 s of
+     * interleaving delay while a stream is silent. Inputs read faster than real
+     * time can pile up correspondingly more media before it fires, inputs that
+     * deliver packets more than 2 s apart take correspondingly longer. `0`
+     * disables the check.
+     *
+     * @default 60
+     */
+    maxPacketAge?: number;
+    /**
+     * AbortSignal for cancellation.
+     *
+     * When aborted, the stream stops gracefully, equivalent to calling stop().
+     * If already aborted when start() is called, throws AbortError.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Video description of the muxed fMP4 output.
+ */
+export interface FMP4VideoInfo {
+    /** Output codec family. */
+    codec: 'h264' | 'hevc' | 'av1' | 'unknown';
+    /** RFC 6381 codec string of the output (e.g. `hvc1.1.6.L120.B0`). */
+    codecString: string;
+    width: number;
+    height: number;
+    /** Frames per second, 0 when unknown. */
+    fps: number;
+}
+/**
+ * Target codec strings for fMP4 streaming.
+ */
+export declare const FMP4_CODECS: {
+    readonly H264: "avc1.640029";
+    readonly H265: "hvc1.1.6.L153.B0";
+    readonly AV1: "av01.0.00M.08";
+    readonly AAC: "mp4a.40.2";
+    readonly FLAC: "flac";
+    readonly OPUS: "opus";
+};
+/**
+ * High-level fMP4 streaming with automatic codec detection and transcoding.
+ *
+ * Provides fragmented MP4 streaming for clients.
+ * Automatically transcodes video to H.264 and audio to AAC (Opus when the client
+ * lists Opus but not AAC) if not supported by client.
+ * Client sends supported codecs, server transcodes accordingly.
+ * Essential component for building adaptive streaming servers.
+ *
+ * @example
+ * ```typescript
+ * import { FMP4Stream } from 'node-av/api';
+ *
+ * // Client sends supported codecs
+ * const supportedCodecs = 'avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2,flac';
+ *
+ * // Create stream with codec negotiation
+ * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+ *   supportedCodecs,
+ *   onData: (data) => ws.send(data.data)
+ * });
+ *
+ * // Start streaming (auto-transcodes if needed)
+ * await stream.start();
+ *
+ * // Stop when done
+ * await stream.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream with hardware acceleration
+ * const stream = FMP4Stream.create('input.mp4', {
+ *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+ *   hardware: 'auto',
+ *   fragDuration: 1,
+ *   onData: (data) => sendToClient(data.data)
+ * });
+ *
+ * await stream.start();
+ * await stream.stop();
+ * ```
+ */
+export declare class FMP4Stream {
+    private options;
+    private inputUrl;
+    private inputOptions;
+    private liveInput;
+    private input?;
+    private source?;
+    private output?;
+    private hardwareContext?;
+    private videoDecoder?;
+    private videoFilter?;
+    private videoEncoder?;
+    private audioDecoder?;
+    private audioFilter?;
+    private audioEncoder?;
+    private pipeline?;
+    private startPromise?;
+    private signal?;
+    private supportedCodecs;
+    private incompleteBoxBuffer;
+    private pendingFragment;
+    private abortHandler?;
+    private stopRequested;
+    private discardOutput;
+    private stopPromise?;
+    private startAbort?;
+    private stopSignal;
+    private fragmentQueue;
+    private packetAgeWatchdog?;
+    private _droppedFragments;
+    private _initSegment;
+    private _initSegmentResolve;
+    private _initSegmentReject;
+    private _initSegmentPromise;
+    private _ftypData;
+    private _moovData;
+    /**
+     * @param input - Media input URL or pre-opened Demuxer
+     *
+     * @param options - Stream configuration options
+     *
+     * Use {@link create} factory method
+     *
+     * @throws {RangeError} If dtsBackwardThreshold, dtsForwardThreshold or maxPacketAge is not a finite number >= 0
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create a fMP4 stream from a media source.
+     *
+     * Configures the stream with input URL and options. The input is not opened
+     * until start() is called, allowing the stream to be reused after stop().
+     *
+     * @param input - Media source URL (RTSP, file path, HTTP, etc.) or a pre-opened {@link Demuxer}
+     *
+     * @param options - Stream configuration options with supported codecs
+     *
+     * @returns Configured fMP4 stream instance
+     *
+     * @throws {RangeError} If dtsBackwardThreshold, dtsForwardThreshold or maxPacketAge is not a finite number >= 0
+     *
+     * @example
+     * ```typescript
+     * // Stream from file with codec negotiation
+     * const stream = FMP4Stream.create('video.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onData: (data) => ws.send(data.data)
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream from RTSP with auto hardware acceleration
+     * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2',
+     *   hardware: 'auto',
+     *   fragDuration: 0.5
+     * });
+     * ```
+     */
+    static create(input: string | Demuxer | MediaFrameSource, options?: FMP4StreamOptions): FMP4Stream;
+    /**
+     * Promise that resolves with the init segment (ftyp+moov).
+     *
+     * Only available when boxMode is enabled.
+     * Resolves once the first ftyp and moov boxes have been received.
+     * Rejects if the stream fails or is stopped before the init segment
+     * was produced, so awaiting it never hangs.
+     *
+     * @throws {Error} If boxMode is not enabled
+     */
+    get initSegment(): Promise<Buffer>;
+    /**
+     * Number of media fragments dropped due to consumer backpressure.
+     *
+     * Incremented whenever the {@link fragments} backlog exceeds
+     * `maxQueuedFragments` and the oldest fragment is discarded.
+     * Reset to 0 when the stream is (re)started.
+     *
+     * @returns Total dropped fragments for the current run
+     *
+     * @example
+     * ```typescript
+     * for await (const fragment of stream.fragments()) {
+     *   await sendToClient(fragment.data);
+     *   if (stream.droppedFragments > 0) {
+     *     console.warn(`Consumer too slow: ${stream.droppedFragments} fragments dropped`);
+     *   }
+     * }
+     * ```
+     */
+    get droppedFragments(): number;
+    /**
+     * Get the demuxer instance.
+     *
+     * Used for accessing the underlying demuxer.
+     * Only available after start() is called.
+     *
+     * @returns Demuxer instance or undefined if not started
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('input.mp4', {
+     * const input = stream.getInput();
+     * console.log('Bitrate:', input?.bitRate);
+     * ```
+     */
+    getInput(): Demuxer | undefined;
+    /**
+     * Get the codec string that will be used by client.
+     *
+     * Returns the MIME type codec string based on input codecs and transcoding decisions.
+     * Call this after start() is called to know what codec string to use for addSourceBuffer().
+     *
+     * @returns MIME type codec string (e.g., "avc1.640029,mp4a.40.2")
+     *
+     * @throws {Error} If called before start() is called
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     *
+     * await stream.start(); // Must start first
+     * const codecString = stream.getCodecString();
+     * console.log(codecString); // "avc1.640029,mp4a.40.2"
+     * // Use this for: sourceBuffer = mediaSource.addSourceBuffer(`video/mp4; codecs="${codecString}"`);
+     * ```
+     */
+    getCodecString(): string;
+    /**
+     * Video description of the muxed fMP4 output (output codec, RFC 6381 codec string, resolution, fps).
+     *
+     * Available after {@link start} has opened the input.
+     *
+     * @returns The output video info, or `undefined` when there is no video track.
+     *
+     * @example
+     * ```typescript
+     * const videoInfo = stream.getVideoInfo();
+     * if (videoInfo) {
+     *   console.log(`Codec: ${videoInfo.codec}, Resolution: ${videoInfo.width}x${videoInfo.height}, FPS: ${videoInfo.fps}`);
+     * }
+     * ```
+     */
+    getVideoInfo(): FMP4VideoInfo | undefined;
+    /**
+     * Start streaming media to fMP4 chunks.
+     *
+     * Begins the media processing pipeline, reading packets from input,
+     * transcoding based on supported codecs, and generating fMP4 chunks.
+     * Video transcodes to H.264 if H.264/H.265 not supported.
+     * Audio transcodes to AAC (Opus when only Opus is listed) if the input codec is not supported.
+     * This method returns immediately after starting the pipeline.
+     *
+     * @returns Promise that resolves when pipeline is started
+     *
+     * @throws {FFmpegError} If setup fails
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onData: (data) => sendToClient(data.data)
+     * });
+     *
+     * // Start streaming (returns immediately)
+     * await stream.start();
+     *
+     * // Later: stop streaming
+     * await stream.stop();
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Perform the actual startup (see {@link start}).
+     *
+     * @internal
+     */
+    private doStart;
+    /**
+     * Abort an in-flight startup once stop() was requested.
+     *
+     * Checked after every await in the startup path: the resources created so
+     * far are all assigned to instance fields, so the stop() that is waiting on
+     * this startup tears them down the moment it unwinds.
+     *
+     * @throws {Error} If stop() was called while starting
+     *
+     * @internal
+     */
+    private throwIfStopRequested;
+    /**
+     * libx264, the encoder for H.264 output when no hardware encoder is usable.
+     *
+     * @returns The libx264 encoder
+     *
+     * @throws {Error} If the FFmpeg build has no libx264 (node-av-lgpl)
+     *
+     * @internal
+     */
+    private softwareH264Encoder;
+    /**
+     * GOP size for the video encoder that starts every fragment with a keyframe.
+     *
+     * frag_duration flushes a fragment once it is that long, mid-GOP on a
+     * P-frame unless the GOP has the same length, and strict consumers reject
+     * such fragments. Shorter fragments (the 1 µs default flushes after every
+     * frame) are not matched: a GOP of a few frames multiplies the bitrate, so
+     * below MIN_FRAGMENT_GOP the GOP is 2 s, as with a fragDuration of 0.
+     *
+     * @param fps - Output frame rate
+     *
+     * @returns GOP size in frames
+     *
+     * @internal
+     */
+    private gopSize;
+    /**
+     * Create the fMP4 output muxer with the fragment-emitting write callback.
+     *
+     * Uses `this.input` when present (demuxer path) and no input for the
+     * frame-source path. Attaches a fresh packet age watchdog unless
+     * `maxPacketAge` is 0.
+     *
+     * @returns The configured muxer
+     *
+     * @internal
+     */
+    private createOutput;
+    /**
+     * Wire the pipeline completion to the fragment/close callbacks.
+     *
+     * On success ends the fragment iterator and invokes `onClose()`; on error
+     * stops the stream, discarding the output the muxer still holds, and invokes
+     * `onClose(error)`. Either way `onClose` runs exactly once and the detached
+     * chain never rejects. Runs in the background.
+     *
+     * @param completion - The pipeline completion promise
+     *
+     * @internal
+     */
+    private attachCompletion;
+    /**
+     * Invoke the owner's onClose callback.
+     *
+     * The completion chain runs detached, so an exception from the callback
+     * could only surface as an unhandled rejection - it is logged instead.
+     *
+     * @param error - Pipeline error, or undefined for a clean end
+     *
+     * @internal
+     */
+    private emitClose;
+    /**
+     * Whether a pipeline rejection was caused by an intentional shutdown.
+     *
+     * @param error - The pipeline rejection reason
+     *
+     * @returns True when stop() is in flight or the owner's signal aborted
+     *
+     * @internal
+     */
+    private isDeliberateStop;
+    /**
+     * Set up encoders and the fMP4 muxer for a pre-composited frame source and
+     * start encoding. No demuxer or decoder is involved - the provided frames are
+     * encoded straight into the fragmented container. Both streams share the ONE
+     * muxer, so neither may close it on its own: each source is encoded to packets
+     * and written concurrently (the muxer interleaves), and the muxer is closed
+     * once all streams have finished.
+     *
+     * @throws {Error} If the source has neither video nor audio frames
+     *
+     * @internal
+     */
+    private startFromFrames;
+    /**
+     * Stop streaming gracefully and clean up all resources.
+     *
+     * Stops the pipeline, closes output, and releases all FFmpeg resources.
+     * Safe to call multiple times. After stopping, you can call start() again
+     * to restart the stream. Resolves even if the pipeline had failed; that
+     * error is reported through `onClose(error)`.
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     * await stream.start();
+     *
+     * // Stop after 10 seconds
+     * setTimeout(async () => await stream.stop(), 10000);
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Perform the actual teardown (see {@link stop}).
+     *
+     * @internal
+     */
+    private doStop;
+    /**
+     * Async generator that yields media fragments (moof+mdat chunks).
+     *
+     * In box mode, yields only media fragments (chunks containing moof boxes),
+     * NOT the init segment. Use {@link initSegment} to get the ftyp+moov data.
+     *
+     * In chunk mode (boxMode disabled), yields every chunk as-is since
+     * box-level filtering is not possible without box parsing.
+     *
+     * The generator completes when the stream stops or the pipeline ends.
+     *
+     * Only a single consumer is supported: a second concurrent fragments() call
+     * would silently strand the first consumer, so it throws instead. The
+     * backlog is bounded by `maxQueuedFragments` - if the consumer falls behind
+     * a live source, the oldest fragments are dropped (see
+     * {@link droppedFragments}).
+     *
+     * @yields {FMP4Fragment} Media fragment with data buffer and box info
+     *
+     * @throws {Error} If another fragments() iterator is already active
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('rtsp://camera/stream', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   boxMode: true,
+     * });
+     *
+     * await stream.start();
+     * const init = await stream.initSegment;
+     *
+     * for await (const fragment of stream.fragments()) {
+     *   sendToClient(fragment.data);
+     * }
+     * ```
+     */
+    fragments(): AsyncGenerator<FMP4Fragment, void>;
+    /**
+     * Run the streaming pipeline until completion or stopped.
+     *
+     * @internal
+     */
+    private runPipeline;
+    /**
+     * Check if the video is encoded again instead of passed through.
+     *
+     * @param codecId - Codec ID of the source video
+     *
+     * @returns True if `video.transcode` is set or the codec is not in supported codecs
+     *
+     * @internal
+     */
+    private transcodesVideo;
+    /**
+     * Check if video codec is supported.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if H.264, H.265, or AV1 is in supported codecs
+     *
+     * @internal
+     */
+    private isVideoCodecSupported;
+    /**
+     * Codec that unsupported audio is transcoded to.
+     *
+     * @returns Opus when the client lists Opus but not AAC, otherwise AAC
+     *
+     * @internal
+     */
+    private audioTranscodeTarget;
+    /**
+     * Create the audio filter and encoder for the transcode target.
+     *
+     * AAC is resampled to 44.1 kHz stereo. Opus is resampled to 48 kHz, the only
+     * rate it transmits, keeps mono input mono and uses 20 ms frames.
+     *
+     * @param decoder - Input audio decoder, absent for a frame source
+     *
+     * @param channels - Input channel count, 0 when unknown
+     *
+     * @internal
+     */
+    private createAudioEncoder;
+    /**
+     * Check if audio codec is supported.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if AAC, FLAC, or Opus is in supported codecs
+     *
+     * @internal
+     */
+    private isAudioCodecSupported;
+    /**
+     * Process buffer in box mode - buffers until complete boxes are available.
+     *
+     * The muxer splits writes at arbitrary positions, so a chunk may end
+     * anywhere - including inside a box header. Any trailing partial box
+     * (header or body) is buffered for the next chunk; the parser never
+     * loses bytes regardless of where the split falls.
+     *
+     * Emission is fragment-aligned: a `moof` is held back until its `mdat` has
+     * arrived, then both are emitted as ONE onData call. The avio buffer flushes
+     * at arbitrary points (a fragment larger than the buffer always splits), so
+     * without this a consumer would see a bare `moof` followed by a detached
+     * `mdat` - unplayable framing for fMP4 consumers.
+     * Non-fragment boxes (ftyp, moov, mfra, ...) are emitted as they complete.
+     *
+     * @param chunk - Incoming data chunk from FFmpeg
+     *
+     * @internal
+     */
+    private processBoxMode;
+    /**
+     * Emit a group of complete boxes as one onData call.
+     *
+     * Concatenates the raw box bytes, rebuilds the box list with offsets
+     * relative to the emitted buffer, tracks the init segment, and feeds the
+     * fragments() queue when the group is a media fragment.
+     *
+     * @param entries - Complete boxes in stream order
+     *
+     * @internal
+     */
+    private emitBoxGroup;
+    /**
+     * Push a fragment to the fragment queue for the async generator.
+     *
+     * @param data - fMP4 data buffer
+     *
+     * @param info - Parsed box information
+     *
+     * @internal
+     */
+    private pushFragment;
+    /**
+     * Reject a pending initSegment promise so consumers never hang.
+     *
+     * No-op when the promise was never requested or has already settled. The
+     * promise is marked as handled to avoid an unhandled rejection when no
+     * consumer is currently awaiting it.
+     *
+     * @param error - Rejection reason (pipeline error or stop-before-init)
+     *
+     * @internal
+     */
+    private rejectInitSegment;
+    /**
+     * Signal the fragment queue that no more fragments will arrive.
+     *
+     * @internal
+     */
+    private endFragments;
+}