homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/ffmpeg/mp4-assembler.d.ts

@@ -0,0 +1,161 @@
+import type { Readable } from "node:stream";
+/**
+ * Construction-time options for {@link Mp4SegmentAssembler}.
+ *
+ * @property segmentTimeout   - Optional watchdog window, in milliseconds. The timer arms when the initialization segment resolves (we begin expecting media segments)
+ *                              and re-arms on each completed media segment. If no segment arrives within the window, the assembler aborts with
+ *                              `HbpuAbortError("timeout")` and the generator terminates cleanly. Typical value for HKSV is a little under five seconds.
+ * @property signal           - Optional parent {@link AbortSignal} to compose with the assembler's internal controller. When the parent aborts, the assembler tears
+ *                              down and the segment generator exits.
+ *
+ * @category FFmpeg
+ */
+export interface Mp4SegmentAssemblerInit {
+    segmentTimeout?: number;
+    signal?: AbortSignal;
+}
+/**
+ * The kind of a segment yielded by {@link Mp4SegmentAssembler.stream}. `"init"` is the one-shot initialization segment; `"media"` is a continuous media fragment. A
+ * consumer that paces or forwards every item uniformly can read {@link Mp4Segment.bytes} without branching; a consumer that must treat the init segment specially
+ * branches on this field.
+ *
+ * @category FFmpeg
+ */
+export type Mp4SegmentKind = "init" | "media";
+/**
+ * A single fMP4 segment yielded by {@link Mp4SegmentAssembler.stream}, tagged with its kind so a consumer can tell the one-shot initialization segment apart from the
+ * media fragments that follow it without relying on positional ordering.
+ *
+ * @property bytes  - The complete segment bytes: for `"init"`, the concatenated initialization boxes (typically `ftyp` + `moov`); for `"media"`, a concatenated
+ *                    `moof` + `mdat` pair.
+ * @property kind   - `"init"` for the single leading initialization segment, `"media"` for each subsequent media fragment.
+ *
+ * @category FFmpeg
+ */
+export interface Mp4Segment {
+    bytes: Buffer;
+    kind: Mp4SegmentKind;
+}
+/**
+ * AsyncDisposable fMP4 segment assembler that converts a Readable byte source into an init segment promise and a media-segment async generator.
+ *
+ * Construction kicks off a background drain loop that feeds {@link Mp4BoxParser} from the source's `data` events and routes each parsed box through a small state
+ * machine: everything before the first `moof` accumulates into the initialization segment; from the first `moof` onward, boxes accumulate into the current media
+ * segment until an `mdat` flushes the accumulated pair to the output queue.
+ *
+ * The single public teardown verb is {@link Mp4SegmentAssembler.abort}, mirroring `AbortController.abort()`. `Symbol.asyncDispose` is implemented in terms of it and
+ * awaits the drain loop's completion before returning, so `await using` guarantees the assembler has fully unwound by the time the surrounding scope exits.
+ *
+ * @example
+ *
+ * ```ts
+ * import { Mp4SegmentAssembler } from "homebridge-plugin-utils";
+ *
+ * await using assembler = new Mp4SegmentAssembler(ffmpegStdout, { segmentTimeout: 4500, signal: session.signal });
+ *
+ * const initSegment = await assembler.initSegment;
+ *
+ * for await (const segment of assembler.segments()) {
+ *
+ *   // Forward segment bytes to HomeKit.
+ * }
+ * ```
+ *
+ * @see Mp4BoxParser
+ *
+ * @category FFmpeg
+ */
+export declare class Mp4SegmentAssembler implements AsyncDisposable {
+    #private;
+    /**
+     * The composed abort signal representing this assembler's lifetime. Aborts exactly once when the source ends, the source errors, the parent signal fires, the
+     * watchdog timeout expires, or {@link Mp4SegmentAssembler.abort} is called; the reason encoded on `signal.reason` names the cause.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Promise that resolves with the concatenated initialization-segment bytes (typically `ftyp` + `moov`) once the first `moof` box arrives on the source. Rejects with
+     * `this.signal.reason` if the assembler is aborted before the initialization segment completes.
+     */
+    readonly initSegment: Promise<Buffer>;
+    /**
+     * Construct and start a new fMP4 segment assembler.
+     *
+     * The drain loop starts synchronously as part of construction: by the time the constructor returns, the source's `data` events are being observed and the parser is
+     * ready to emit boxes. There is no separate `start()` step.
+     *
+     * @param source - Any {@link Readable} producing fMP4 byte chunks. Typically an FFmpeg process's stdout; any Readable works, which keeps the class testable in
+     *                 isolation with in-memory fixture streams.
+     * @param init   - Optional init options. See {@link Mp4SegmentAssemblerInit}.
+     */
+    constructor(source: Readable, init?: Mp4SegmentAssemblerInit);
+    /**
+     * Abort the assembler and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * Safe to call more than once: subsequent calls are no-ops because the underlying signal only aborts once. Calling `abort()` after natural completion is also safe
+     * for the same reason.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors (`TimeoutError`, `AbortError`) also interoperate by convention.
+     */
+    abort(reason?: unknown): void;
+    /**
+     * `AsyncDisposable` implementation. Aborts the assembler (defaulting to `"shutdown"`) and awaits actual drain-loop completion before returning, so callers using
+     * `await using` are guaranteed every internal listener has been detached by the time the block exits.
+     *
+     * @returns A promise that resolves once the drain loop has fully exited.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
+     */
+    get aborted(): boolean;
+    /**
+     * `true` when the abort reason indicates a timeout. Matches both the canonical `HbpuAbortError("timeout")` emitted by the inter-segment watchdog and the platform
+     * `TimeoutError` emitted by `AbortSignal.timeout()`. The branching lives in {@link isTimeoutReason} so this getter stays a one-line delegation and every
+     * resource class in the library shares one definition of "timeout."
+     */
+    get isTimedOut(): boolean;
+    /**
+     * The number of completed media segments buffered between the drain loop and the {@link Mp4SegmentAssembler.segments} consumer - the segments the producer has
+     * assembled but the consumer has not yet pulled. A consumer pacing its reads slower than the source produces accrues a reserve here, and that reserve is what
+     * absorbs an upstream stall: the consumer keeps pulling buffered segments while no new ones arrive. It is zero in steady state when the consumer keeps pace.
+     */
+    get bufferedSegments(): number;
+    /**
+     * Async generator yielding each completed media segment (concatenated `moof` + `mdat` pair) as a single Buffer.
+     *
+     * Yields only after {@link Mp4SegmentAssembler.initSegment} has resolved - the init segment is not surfaced through this stream. Terminates cleanly when the source
+     * ends, the assembler aborts, or the optional caller signal aborts; in every case the queue is drained before the generator returns, so a consumer never loses a
+     * segment that was already assembled before teardown.
+     *
+     * **Single-consumer only.** The internal parked-waiter slot is single-writer; calling `segments()` concurrently with another consumer on the same assembler - including
+     * the {@link Mp4SegmentAssembler.stream} view, which drives this generator internally - is unsupported and will hang one of the consumers when the producer's wake-up
+     * resolves only the later parker. If fan-out is needed, tee at the consumer side by replicating each yielded Buffer into per-consumer queues external to the assembler.
+     *
+     * @param init - Optional init options. `signal` composes with the assembler's own signal - aborting it terminates only this generator call, not the assembler.
+     *
+     * @returns An async generator yielding concatenated `moof` + `mdat` pair buffers in stream order.
+     */
+    segments(init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Buffer>;
+    /**
+     * Async generator yielding the whole segment stream as a kind-tagged sequence: exactly one {@link Mp4Segment} of kind `"init"` carrying the initialization bytes,
+     * followed by one of kind `"media"` per completed media fragment. This is a third view over the same single-pass pipeline, composed from {@link initSegment} and
+     * {@link segments} - it lets a consumer forward the init segment and the media segments through a single loop without tracking which item is which by position.
+     *
+     * Terminates cleanly on the same conditions as {@link segments}: the source ends, the assembler aborts, or the optional caller signal aborts; queued media drains
+     * before the generator returns, so no assembled segment is lost. If the assembler is aborted before the initialization segment arrives, the generator returns without
+     * yielding anything.
+     *
+     * **Single-consumer only.** `stream()` drives {@link segments} internally, so it shares the one parked-waiter slot. Use `stream()` OR the {@link initSegment} /
+     * {@link segments} pair on a single assembler, never both concurrently - mixing them competes for the same drain and hangs one consumer.
+     *
+     * @param init - Optional init options. `signal` composes with the assembler's own signal - aborting it terminates only this generator call, not the assembler.
+     *
+     * @returns An async generator yielding one `"init"` segment followed by `"media"` segments in stream order.
+     */
+    stream(init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Mp4Segment>;
+}
+//# sourceMappingURL=mp4-assembler.d.ts.map

package/dist/ffmpeg/mp4-assembler.js

@@ -0,0 +1,424 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ffmpeg/mp4-assembler.ts: AsyncDisposable fMP4 segment assembler composing Mp4BoxParser against a Readable byte source.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+ * AsyncDisposable fMP4 segment assembler.
+ *
+ * The assembler composes a {@link Mp4BoxParser} against an arbitrary Node {@link Readable} source (typically an FFmpeg process's stdout, but any Readable of well-formed
+ * fMP4 bytes works - including in-memory fixtures for tests) and exposes complementary views over the single-pass box pipeline:
+ *
+ *   - `initSegment: Promise<Buffer>` - resolves once with the concatenated bytes of every box that appeared before the first `moof` (typically ftyp + moov).
+ *   - `segments(): AsyncGenerator<Buffer>` - yields each subsequent `moof` / `mdat` pair concatenated into a single Buffer.
+ *   - `stream(): AsyncGenerator<Mp4Segment>` - yields the whole sequence tagged by kind: one `"init"` item carrying the initialization bytes, then a `"media"`
+ *     item per fragment, so a caller can forward init and media through one loop.
+ *
+ * One-shot artifacts (the init segment) are promises; continuous streams (media segments) are async generators. Lifetime is governed by
+ * a composed {@link AbortSignal}: external abort, parent signal propagation, source error, source end, or an optional inter-segment watchdog timeout all converge on the
+ * same signal. The class is single-consumer by design - these views share one internal drain loop, not independent subscriptions, so a caller uses `stream()` OR the
+ * `initSegment` / `segments()` pair, never both concurrently.
+ *
+ * @module
+ */
+import { BOX_TYPE_MDAT, BOX_TYPE_MOOF, Mp4BoxParser } from "./mp4-parser.js";
+import { HbpuAbortError, Watchdog, composeSignals, isTimeoutReason, markHandled, onAbort, waitWithSignal } from "../util.js";
+import { on } from "node:events";
+/**
+ * AsyncDisposable fMP4 segment assembler that converts a Readable byte source into an init segment promise and a media-segment async generator.
+ *
+ * Construction kicks off a background drain loop that feeds {@link Mp4BoxParser} from the source's `data` events and routes each parsed box through a small state
+ * machine: everything before the first `moof` accumulates into the initialization segment; from the first `moof` onward, boxes accumulate into the current media
+ * segment until an `mdat` flushes the accumulated pair to the output queue.
+ *
+ * The single public teardown verb is {@link Mp4SegmentAssembler.abort}, mirroring `AbortController.abort()`. `Symbol.asyncDispose` is implemented in terms of it and
+ * awaits the drain loop's completion before returning, so `await using` guarantees the assembler has fully unwound by the time the surrounding scope exits.
+ *
+ * @example
+ *
+ * ```ts
+ * import { Mp4SegmentAssembler } from "homebridge-plugin-utils";
+ *
+ * await using assembler = new Mp4SegmentAssembler(ffmpegStdout, { segmentTimeout: 4500, signal: session.signal });
+ *
+ * const initSegment = await assembler.initSegment;
+ *
+ * for await (const segment of assembler.segments()) {
+ *
+ *   // Forward segment bytes to HomeKit.
+ * }
+ * ```
+ *
+ * @see Mp4BoxParser
+ *
+ * @category FFmpeg
+ */
+export class Mp4SegmentAssembler {
+    /**
+     * The composed abort signal representing this assembler's lifetime. Aborts exactly once when the source ends, the source errors, the parent signal fires, the
+     * watchdog timeout expires, or {@link Mp4SegmentAssembler.abort} is called; the reason encoded on `signal.reason` names the cause.
+     */
+    signal;
+    /**
+     * Promise that resolves with the concatenated initialization-segment bytes (typically `ftyp` + `moov`) once the first `moof` box arrives on the source. Rejects with
+     * `this.signal.reason` if the assembler is aborted before the initialization segment completes.
+     */
+    initSegment;
+    // The private AbortController whose signal is composed into `this.signal`. Owning the controller internally keeps teardown reachable from any handler - the parser,
+    // the source error listener, the watchdog - without giving callers a handle to the raw controller.
+    #controller;
+    // The byte source. Held so drain-path listeners (`end`, `error`) can be attached and detached in one place.
+    #source;
+    // The box parser driving the drain loop. Stateful: carries residual bytes across chunks.
+    #parser;
+    // Inter-segment watchdog composed over this.signal, or `undefined` when no `segmentTimeout` was configured. Armed when the init segment resolves and re-armed on each
+    // completed media segment; fires the composed controller with `HbpuAbortError("timeout")` on lapse. Self-cleans when the signal aborts for any other reason.
+    #watchdog;
+    // Resolver pair for {@link initSegment}. Resolved when the first `moof` arrives (with the accumulated init parts); rejected from the teardown path if still pending.
+    #initResolvers;
+    // Accumulated box bytes for the initialization segment. Flipped to empty and concatenated once the first `moof` flushes them into `initSegment`.
+    #initParts = [];
+    // Set `true` once the initialization segment has resolved. The phase flag for the drain state machine: `false` means "collecting init boxes"; `true` means "collecting
+    // media boxes."
+    #initResolved = false;
+    // Accumulated box bytes for the media segment currently being built. Reset to empty each time an `mdat` flushes the pair into the output queue.
+    #segmentParts = [];
+    // Completed media segments waiting to be yielded from `segments()`. A FIFO queue decouples the drain loop (producer) from the generator (consumer), which lets the
+    // consumer fall behind momentarily without dropping data.
+    #segmentQueue = [];
+    // Parked waiter the generator uses to block until a segment is pushed or the signal aborts. A single-slot optional field is enough because the class is
+    // single-consumer by design.
+    #segmentWaiter;
+    // The drain loop's promise. Held so `[Symbol.asyncDispose]` can await actual completion before returning, so callers using `await using` are guaranteed all drain
+    // listeners have been detached by the time the block exits.
+    #drainTask;
+    /**
+     * Construct and start a new fMP4 segment assembler.
+     *
+     * The drain loop starts synchronously as part of construction: by the time the constructor returns, the source's `data` events are being observed and the parser is
+     * ready to emit boxes. There is no separate `start()` step.
+     *
+     * @param source - Any {@link Readable} producing fMP4 byte chunks. Typically an FFmpeg process's stdout; any Readable works, which keeps the class testable in
+     *                 isolation with in-memory fixture streams.
+     * @param init   - Optional init options. See {@link Mp4SegmentAssemblerInit}.
+     */
+    constructor(source, init = {}) {
+        const { signal: parentSignal, segmentTimeout } = init;
+        this.#controller = new AbortController();
+        this.signal = composeSignals(parentSignal, this.#controller.signal);
+        this.#source = source;
+        this.#parser = new Mp4BoxParser();
+        // Instantiate the inter-segment watchdog only when the caller opted into timeout enforcement. When undefined, no watchdog is constructed and every `arm()` site
+        // becomes a cheap `?.` no-op. The watchdog self-cleans when the composed signal aborts, so nothing else in this class needs to know about it.
+        this.#watchdog = (segmentTimeout !== undefined) ? new Watchdog({
+            onFire: () => {
+                this.#controller.abort(new HbpuAbortError("timeout"));
+            },
+            signal: this.signal,
+            timeoutMs: segmentTimeout
+        }) : undefined;
+        // Wire up the init resolvers before starting any listeners. Callers reading `initSegment` should see a promise that can be awaited regardless of whether the source
+        // has already emitted anything by the time they get the reference. `markHandled` opts the promise out of Node's unhandled-rejection tracker for the case where a
+        // consumer uses only `segments()` and never awaits the init segment directly.
+        this.#initResolvers = Promise.withResolvers();
+        this.initSegment = markHandled(this.#initResolvers.promise);
+        // Attach a permanent source `"error"` absorber. Node's EventEmitter crashes the host process when `"error"` is emitted with no listeners, and the
+        // `events.on`-driven error handling inside `#drain` only protects while the drain loop is active. A phantom listener that lives for the assembler's lifetime
+        // guarantees no stray source error can crash the host - even during the sub-microtask window between drain termination and our teardown, or after teardown if the
+        // caller keeps the source alive past the assembler's useful life. During drain, Node dispatches `"error"` to every listener in registration order so `events.on`
+        // still rejects the iterator; the absorber just backstops the cases `events.on` does not cover. Released with the assembler instance.
+        this.#source.on("error", () => { });
+        // Single teardown convergence point. `onAbort` registers the one-shot teardown listener for the normal abort path AND handles the "pre-aborted signal" edge case
+        // where `addEventListener("abort", ...)` would otherwise silently skip the handler (the AbortSignal spec does not re-dispatch historical events). Pairing it with
+        // the `signal.aborted` short-circuit below means `initSegment` settles consistently regardless of whether the parent signal was live at construction time.
+        onAbort(this.signal, () => this.#teardown());
+        if (this.signal.aborted) {
+            return;
+        }
+        // Start the drain pipeline. The returned promise is retained so `[Symbol.asyncDispose]` can await the drain's completion before returning. `#drain` is written to
+        // always resolve - its body catches and classifies errors inline - so nothing can reject out of it, and no `markHandled` wrapper is needed here.
+        this.#drainTask = this.#drain();
+    }
+    /**
+     * Abort the assembler and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * Safe to call more than once: subsequent calls are no-ops because the underlying signal only aborts once. Calling `abort()` after natural completion is also safe
+     * for the same reason.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors (`TimeoutError`, `AbortError`) also interoperate by convention.
+     */
+    abort(reason) {
+        if (this.aborted) {
+            return;
+        }
+        this.#controller.abort(reason ?? new HbpuAbortError("shutdown"));
+    }
+    /**
+     * `AsyncDisposable` implementation. Aborts the assembler (defaulting to `"shutdown"`) and awaits actual drain-loop completion before returning, so callers using
+     * `await using` are guaranteed every internal listener has been detached by the time the block exits.
+     *
+     * @returns A promise that resolves once the drain loop has fully exited.
+     */
+    async [Symbol.asyncDispose]() {
+        this.abort();
+        if (this.#drainTask) {
+            // Drain failures are already observed internally; swallow here so `await using` does not surface cleanup-side errors the caller cannot react to.
+            await this.#drainTask.catch(() => { });
+        }
+    }
+    /**
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
+     */
+    get aborted() {
+        return this.signal.aborted;
+    }
+    /**
+     * `true` when the abort reason indicates a timeout. Matches both the canonical `HbpuAbortError("timeout")` emitted by the inter-segment watchdog and the platform
+     * `TimeoutError` emitted by `AbortSignal.timeout()`. The branching lives in {@link isTimeoutReason} so this getter stays a one-line delegation and every
+     * resource class in the library shares one definition of "timeout."
+     */
+    get isTimedOut() {
+        return isTimeoutReason(this.signal.reason);
+    }
+    /**
+     * The number of completed media segments buffered between the drain loop and the {@link Mp4SegmentAssembler.segments} consumer - the segments the producer has
+     * assembled but the consumer has not yet pulled. A consumer pacing its reads slower than the source produces accrues a reserve here, and that reserve is what
+     * absorbs an upstream stall: the consumer keeps pulling buffered segments while no new ones arrive. It is zero in steady state when the consumer keeps pace.
+     */
+    get bufferedSegments() {
+        return this.#segmentQueue.length;
+    }
+    /**
+     * Async generator yielding each completed media segment (concatenated `moof` + `mdat` pair) as a single Buffer.
+     *
+     * Yields only after {@link Mp4SegmentAssembler.initSegment} has resolved - the init segment is not surfaced through this stream. Terminates cleanly when the source
+     * ends, the assembler aborts, or the optional caller signal aborts; in every case the queue is drained before the generator returns, so a consumer never loses a
+     * segment that was already assembled before teardown.
+     *
+     * **Single-consumer only.** The internal parked-waiter slot is single-writer; calling `segments()` concurrently with another consumer on the same assembler - including
+     * the {@link Mp4SegmentAssembler.stream} view, which drives this generator internally - is unsupported and will hang one of the consumers when the producer's wake-up
+     * resolves only the later parker. If fan-out is needed, tee at the consumer side by replicating each yielded Buffer into per-consumer queues external to the assembler.
+     *
+     * @param init - Optional init options. `signal` composes with the assembler's own signal - aborting it terminates only this generator call, not the assembler.
+     *
+     * @returns An async generator yielding concatenated `moof` + `mdat` pair buffers in stream order.
+     */
+    async *segments(init = {}) {
+        // Compose the per-call signal with the assembler's own signal upfront so every wait in this method honors caller cancellation uniformly. A caller who passes
+        // `init.signal` can terminate just this iterator (e.g., to drop a per-session consumer while the assembler keeps running for another session), while the
+        // assembler's signal still governs the underlying pipeline.
+        const composed = composeSignals(this.signal, init.signal);
+        // Gate media-segment delivery on the init-first contract. `waitWithSignal` races the init promise against the composed signal so a caller abort during the init
+        // wait terminates the iterator immediately rather than hanging until the assembler's own signal settles init.
+        try {
+            await waitWithSignal(this.initSegment, composed);
+        }
+        catch {
+            return;
+        }
+        for (;;) {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                // Swap-drain the queue: hand ourselves whatever the producer has staged, leave a fresh empty array for the producer to push into, then yield the snapshot. The
+                // outer for-loop re-enters on every yielded batch so segments pushed while the consumer awaited a previous yield are picked up on the next pass. Drain
+                // unconditionally before checking abort - "no bytes lost" is the rule for segments already assembled before teardown.
+                while (this.#segmentQueue.length > 0) {
+                    const drained = this.#segmentQueue;
+                    this.#segmentQueue = [];
+                    for (const segment of drained) {
+                        yield segment;
+                    }
+                }
+                if (composed.aborted) {
+                    return;
+                }
+                // Park until either a new segment is pushed (producer resolves the waiter) or the composed signal aborts. A per-iteration resolver is used so the waiter is
+                // always fresh; sharing a resolver across iterations would require manual reset logic.
+                const waiter = Promise.withResolvers();
+                this.#segmentWaiter = waiter;
+                // `onAbort` handles listener registration, the pre-aborted-signal pitfall, and the one-shot `{ once: true }` semantic through one primitive; the returned
+                // `Disposable` is handed to `using` so the listener is deterministically removed on every scope-exit path (segment push via `#handleBox`, caller signal abort,
+                // assembler abort, thrown error in the generator). The single unified primitive matches the shape `waitWithSignal` uses for exactly the same kind of parked wait.
+                const _abortRegistration = __addDisposableResource(env_1, onAbort(composed, () => waiter.resolve()), false);
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    await waiter.promise;
+                }
+                finally {
+                    this.#segmentWaiter = undefined;
+                }
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+    }
+    /**
+     * Async generator yielding the whole segment stream as a kind-tagged sequence: exactly one {@link Mp4Segment} of kind `"init"` carrying the initialization bytes,
+     * followed by one of kind `"media"` per completed media fragment. This is a third view over the same single-pass pipeline, composed from {@link initSegment} and
+     * {@link segments} - it lets a consumer forward the init segment and the media segments through a single loop without tracking which item is which by position.
+     *
+     * Terminates cleanly on the same conditions as {@link segments}: the source ends, the assembler aborts, or the optional caller signal aborts; queued media drains
+     * before the generator returns, so no assembled segment is lost. If the assembler is aborted before the initialization segment arrives, the generator returns without
+     * yielding anything.
+     *
+     * **Single-consumer only.** `stream()` drives {@link segments} internally, so it shares the one parked-waiter slot. Use `stream()` OR the {@link initSegment} /
+     * {@link segments} pair on a single assembler, never both concurrently - mixing them competes for the same drain and hangs one consumer.
+     *
+     * @param init - Optional init options. `signal` composes with the assembler's own signal - aborting it terminates only this generator call, not the assembler.
+     *
+     * @returns An async generator yielding one `"init"` segment followed by `"media"` segments in stream order.
+     */
+    async *stream(init = {}) {
+        // Wait for the initialization segment first, racing the caller signal exactly as segments() does, so a caller abort during the init wait ends this stream at once
+        // rather than hanging until the assembler's own signal settles init. A rejection here (aborted before the first moof) ends the stream with nothing yielded.
+        const composed = composeSignals(this.signal, init.signal);
+        let initBytes;
+        try {
+            initBytes = await waitWithSignal(this.initSegment, composed);
+        }
+        catch {
+            return;
+        }
+        // The one init item, then every media segment relabeled. The media loop delegates to segments() so the swap-drain, the parked wait, and the no-bytes-lost teardown
+        // stay in exactly one place rather than being reimplemented here.
+        yield { bytes: initBytes, kind: "init" };
+        for await (const segment of this.segments(init)) {
+            yield { bytes: segment, kind: "media" };
+        }
+    }
+    // Drain loop. Attaches the source's `end` listener, then iterates `events.on(source, "data", { signal })` until the composed signal aborts. For each chunk, the
+    // parser is fed and every complete box is dispatched through `#handleBox`. Every exit path - source end, source error, external abort - converges on the signal
+    // being aborted, which lets the generator's park loop unwind uniformly via `composed.aborted`.
+    async #drain() {
+        // Source end: the byte producer has nothing more to say. Drive teardown through the signal with reason `"closed"`; the signal's teardown listener will resolve the
+        // generator's parked waiter and reject any pending init. Guard against double-abort when the signal already fired (e.g., external teardown that destroyed the
+        // source and produced both `end` and our own abort).
+        const onEnd = () => {
+            if (this.aborted) {
+                return;
+            }
+            this.#controller.abort(new HbpuAbortError("closed"));
+        };
+        this.#source.once("end", onEnd);
+        try {
+            // `events.on` yields each emission as an array of event arguments. For Readable's `data` event the array is `[chunk]`; we destructure inside the loop so the
+            // typing stays explicit. The `{ signal }` option wires abort-driven termination into the iterator directly - when the signal fires, the iterator rejects its next
+            // call with the signal's reason. `events.on` also listens to the source's `"error"` events internally and rejects the iterator with the emitted error; the catch
+            // block below classifies both exit paths.
+            for await (const eventArgs of on(this.#source, "data", { signal: this.signal })) {
+                const [chunk] = eventArgs;
+                for (const box of this.#parser.consume(chunk)) {
+                    this.#handleBox(box);
+                }
+            }
+        }
+        catch (error) {
+            // Single classification point. Every rejection this loop can produce lands here, classified into one of two reasons today: our composed signal aborted
+            // (already carries a structured `signal.reason`, `this.aborted` is true, pass through unchanged) or the source emitted an `"error"` event (the emitted error
+            // is our `cause`, wrap into the `"failed"` reason so every consumer sees the same taxonomy). Parser failures would also land here if the parser ever threw,
+            // which today it does not - `#handleBox` is synchronous and side-effect-only.
+            if (!this.aborted) {
+                this.#controller.abort(new HbpuAbortError("failed", { cause: error }));
+            }
+        }
+        finally {
+            this.#source.off("end", onEnd);
+        }
+    }
+    // Single-box state machine. Before init resolves, boxes accumulate into `#initParts`; the first `moof` flushes them into the init promise, transitions to media
+    // collection, and starts the first media segment with itself as the opening box. From there, each box is appended to the current segment; an `mdat` closes the pair
+    // and pushes it to the output queue.
+    #handleBox(box) {
+        if (!this.#initResolved) {
+            if (box.type === BOX_TYPE_MOOF) {
+                // First `moof` - the preceding boxes (typically ftyp + moov) are the complete init segment. Concatenate them once, resolve the promise, and transition into
+                // media-collection mode with this `moof` starting the first segment.
+                const init = Buffer.concat(this.#initParts);
+                this.#initParts = [];
+                this.#initResolved = true;
+                this.#initResolvers.resolve(init);
+                this.#segmentParts.push(box.bytes);
+                this.#watchdog?.arm();
+                return;
+            }
+            this.#initParts.push(box.bytes);
+            return;
+        }
+        // Media-collection phase: every box contributes to the current pair, and `mdat` is the flush signal. Non-moof/non-mdat boxes (uncommon in fMP4 fragments, but
+        // possible) are appended to the current pair so the downstream consumer sees the stream verbatim.
+        this.#segmentParts.push(box.bytes);
+        if (box.type === BOX_TYPE_MDAT) {
+            const segment = Buffer.concat(this.#segmentParts);
+            this.#segmentParts = [];
+            this.#segmentQueue.push(segment);
+            this.#segmentWaiter?.resolve();
+            this.#watchdog?.arm();
+        }
+    }
+    // Single teardown convergence point, fired exactly once when `this.signal` aborts. Rejects a pending init promise and unblocks the generator so the drain-and-return
+    // sequence can run. The watchdog self-cleans through its own signal listener, and `exited`-style promises are not in this class's contract - the generator is the
+    // exit surface and it wakes up via the resolved waiter.
+    #teardown() {
+        // Promise resolvers are inert after first settlement, so calling reject on an already-resolved init promise is a safe no-op. This lets us keep the teardown
+        // path uniform regardless of whether init arrived before the abort or not.
+        this.#initResolvers.reject(this.signal.reason);
+        this.#segmentWaiter?.resolve();
+    }
+}
+//# sourceMappingURL=mp4-assembler.js.map

package/dist/ffmpeg/mp4-assembler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mp4-assembler.js","sourceRoot":"","sources":["../../src/ffmpeg/mp4-assembler.ts"],"names":[],"mappings":"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"}