@mediaway/container 0.1.6 → 0.2.1

package/README.md

@@ -89,6 +89,44 @@ demuxer.close();
 WebM works the same way — pass `"webm"` to the `Muxer`/`Demuxer` constructor:
 `new Muxer("webm")` / `new Demuxer("webm")`.
 
+## Replay ring
+
+`ReplayRing` keeps the last N milliseconds of encoded packets and cuts "the last M
+milliseconds" at a keyframe of an anchor stream, in decode order, as a packet sequence
+rebased to zero that a fresh `Muxer` writes as a standalone file. Other streams (audio) are
+cut by time to match. Times are milliseconds.
+
+```ts
+import { ReplayRing, Muxer } from "@mediaway/container";
+
+const ring = ReplayRing.create({
+  anchorStreamId: 1, anchorTimeBase: { num: 1, den: 30 }, windowMs: 30_000, payload: "bytes",
+});
+ring.addStream(2, { num: 1, den: 48_000 });
+ring.push({ streamId: 1, pts, dts, duration: 1, key, data });   // copies `data` in
+
+const clip = ring.clipLast(10_000);   // null until the anchor's first keyframe
+// clip.entries(): { streamId, pts, dts (rebased), duration, isKeyframe, kind, payload }
+// -> muxer.addVideoTrack / addAudioTrack once, then muxer.push({ ..., dts }) per entry
+clip.close();
+```
+
+- A **clip is an owned snapshot**: it stays valid while the ring keeps taking packets and
+  after the ring is closed. A `"bytes"` entry's `payload` is a **copy** out of the clip.
+- It can start up to one keyframe interval **earlier** than asked, never later.
+- `payload: "stored"` keeps only where the bytes are: `pushStored(meta, { file, offset,
+  length })`, with locations from `Muxer.createWithPlacements()` + `pollPlacements()` (the
+  offsets are file offsets when every `pollBytes` chunk is written sequentially from 0).
+- Errors are distinct classes: `ReplayOutOfOrderError` (a stream's `dts` went backwards; the
+  packet was not added, drop it and carry on), `ReplayUnknownStreamError`,
+  `ReplayPayloadKindError` (`push` on a stored ring or `pushStored` on a bytes ring).
+- **Limit:** the C ABI has no video-packet source (`EncodeSession` muxes its encoder's packets
+  internally; packet-level output exists only for the audio encoder). Feed the ring `Demuxer`
+  packets, audio-encoder packets, or packets from an encoder you drive yourself.
+
+`Packet` now carries an optional `dts` (defaults to `pts` when pushing; always set on demuxed
+packets), which a clip with B-frames needs.
+
 ## Other formats
 
 Ogg/ADTS/FLV/MPEG-TS/MP3/WAV are exported from the same package but have their own

package/dist/index.d.ts

@@ -6,11 +6,12 @@
  * structs out; the muxer never touches files — the caller owns byte I/O.
  * `pts`/`duration` are integer ticks of each track's `timeBase`.
  */
+import type { Placement } from "./replay.js";
 export interface Rational {
     num: number;
     den: number;
 }
-export type VideoCodec = "h264" | "hevc" | "av1" | "vp9" | "vp8";
+export type VideoCodec = "h264" | "hevc" | "av1" | "vp9" | "vp8" | "prores_422_proxy" | "prores_422_lt" | "prores_422" | "prores_422_hq" | "prores_4444" | "prores_4444_xq";
 export type AudioCodec = "aac" | "opus" | "mp3" | "raw_audio";
 export type PixelFormat = "nv12" | "bgra8" | "rgba8" | "i420" | "yuy2";
 /** Which format `Muxer`/`Demuxer` open — mirrors mediaway_container_format_t.
@@ -46,6 +47,11 @@ export interface Packet {
     data: Buffer;
     /** Ticks of the track's timeBase. */
     pts: number;
+    /**
+     * Decode timestamp, ticks of the track's timeBase. Optional on input (`Muxer.push` defaults it
+     * to `pts`, i.e. no B-frames); always set on demuxed packets.
+     */
+    dts?: number;
     /** Ticks of the track's timeBase. */
     duration: number;
     /** Sync sample / keyframe. */
@@ -56,6 +62,22 @@ export declare class MediawayError extends Error {
     readonly status: number;
     constructor(status: number, message?: string);
 }
+/**
+ * A replay ring refused a packet whose decode timestamp went backwards within its stream
+ * (status INVALID_PACKET). The packet was NOT added and the ring is still usable: drop it and
+ * carry on.
+ */
+export declare class ReplayOutOfOrderError extends MediawayError {
+    constructor();
+}
+/** A packet for a stream that was never added to the replay ring (status UNKNOWN_STREAM). */
+export declare class ReplayUnknownStreamError extends MediawayError {
+    constructor();
+}
+/** `push` on a `"stored"` ring, or `pushStored` on a `"bytes"` ring (status INVALID_STATE). */
+export declare class ReplayPayloadKindError extends MediawayError {
+    constructor();
+}
 export declare const CODEC_TO_ABI: Record<string, number>;
 export declare const ABI_TO_CODEC: Record<number, string>;
 export declare function check(status: number): void;
@@ -69,7 +91,26 @@ export declare function check(status: number): void;
 export declare class Muxer {
     private handle;
     private nextIndex;
-    constructor(format?: ContainerFormat);
+    /**
+     * @param options.placements MP4 only: also record where every sample's payload lands in the
+     *   output ({@link Muxer.pollPlacements}). The output bytes are identical; the only cost is
+     *   one small record per sample.
+     */
+    constructor(format?: ContainerFormat, options?: {
+        placements?: boolean;
+    });
+    /** An MP4 muxer that records payload placements — see {@link Muxer.pollPlacements}. */
+    static createWithPlacements(): Muxer;
+    /**
+     * Take the placements recorded since the last call, in write order: where each sample's
+     * payload landed in the bytes {@link pollBytes} returned. Feed them to
+     * {@link ReplayRing.pushStored}. A placement's bytes are available from `pollBytes` by the
+     * time the placement is.
+     *
+     * @throws {MediawayError} status 2 (INVALID_STATE) before `begin()`, and on a muxer that
+     *   records none (any not built with `placements`, WebM included).
+     */
+    pollPlacements(): Placement[];
     addVideoTrack(info: VideoTrackInfo): number;
     addAudioTrack(info: AudioTrackInfo): number;
     /**
@@ -101,6 +142,7 @@ export declare class Demuxer {
     pollPacket(): Packet | null;
     close(): void;
 }
+export * from "./replay.js";
 export * from "./ogg.js";
 export * from "./adts.js";
 export * from "./flv.js";

package/dist/index.js

@@ -6,7 +6,8 @@
  * structs out; the muxer never touches files — the caller owns byte I/O.
  * `pts`/`duration` are integer ticks of each track's `timeBase`.
  */
-import { MwPacket, MwPacketView, MwRational, MwStreamInfo, MwVideoTrackInfo, MwAudioTrackInfo, container, copyBytes, } from "@mediaway/ffi";
+import { MwPacket, MwPacketView, MwRational, MwStreamInfo, MwVideoTrackInfo, MwAudioTrackInfo, container, copyBytes, replay, } from "@mediaway/ffi";
+import { takePlacements } from "./replay.js";
 const FORMAT_TO_ABI = { mp4: 0, webm: 1 };
 /** Raw per-crate ABI status from mediaway-ffi (mediaway_status_t). */
 export class MediawayError extends Error {
@@ -16,6 +17,31 @@ export class MediawayError extends Error {
         this.status = status;
     }
 }
+/**
+ * A replay ring refused a packet whose decode timestamp went backwards within its stream
+ * (status INVALID_PACKET). The packet was NOT added and the ring is still usable: drop it and
+ * carry on.
+ */
+export class ReplayOutOfOrderError extends MediawayError {
+    constructor() {
+        super(4, "replay ring: dts went backwards on this stream; packet not added");
+        this.name = "ReplayOutOfOrderError";
+    }
+}
+/** A packet for a stream that was never added to the replay ring (status UNKNOWN_STREAM). */
+export class ReplayUnknownStreamError extends MediawayError {
+    constructor() {
+        super(10, "replay ring: stream was never added");
+        this.name = "ReplayUnknownStreamError";
+    }
+}
+/** `push` on a `"stored"` ring, or `pushStored` on a `"bytes"` ring (status INVALID_STATE). */
+export class ReplayPayloadKindError extends MediawayError {
+    constructor() {
+        super(2, "replay ring: wrong payload kind for this call (push vs pushStored)");
+        this.name = "ReplayPayloadKindError";
+    }
+}
 export const CODEC_TO_ABI = {
     h264: 0,
     hevc: 1,
@@ -27,6 +53,12 @@ export const CODEC_TO_ABI = {
     vorbis: 7,
     raw_audio: 11,
     vp8: 12,
+    prores_422_proxy: 13,
+    prores_422_lt: 14,
+    prores_422: 15,
+    prores_422_hq: 16,
+    prores_4444: 17,
+    prores_4444_xq: 18,
 };
 export const ABI_TO_CODEC = Object.fromEntries(Object.entries(CODEC_TO_ABI).map(([k, v]) => [v, k]));
 export function check(status) {
@@ -57,12 +89,40 @@ export function check(status) {
 export class Muxer {
     handle;
     nextIndex = 1;
-    constructor(format = "mp4") {
-        this.handle =
-            format === "mp4" ? container.muxerCreate() : container.muxerCreateForFormat(FORMAT_TO_ABI[format]);
+    /**
+     * @param options.placements MP4 only: also record where every sample's payload lands in the
+     *   output ({@link Muxer.pollPlacements}). The output bytes are identical; the only cost is
+     *   one small record per sample.
+     */
+    constructor(format = "mp4", options = {}) {
+        if (options.placements) {
+            if (format !== "mp4")
+                throw new MediawayError(1, "placements are MP4-only");
+            this.handle = replay.muxerCreateWithPlacements();
+        }
+        else {
+            this.handle =
+                format === "mp4" ? container.muxerCreate() : container.muxerCreateForFormat(FORMAT_TO_ABI[format]);
+        }
         if (!this.handle)
             throw new MediawayError(7, "muxer creation panicked");
     }
+    /** An MP4 muxer that records payload placements — see {@link Muxer.pollPlacements}. */
+    static createWithPlacements() {
+        return new Muxer("mp4", { placements: true });
+    }
+    /**
+     * Take the placements recorded since the last call, in write order: where each sample's
+     * payload landed in the bytes {@link pollBytes} returned. Feed them to
+     * {@link ReplayRing.pushStored}. A placement's bytes are available from `pollBytes` by the
+     * time the placement is.
+     *
+     * @throws {MediawayError} status 2 (INVALID_STATE) before `begin()`, and on a muxer that
+     *   records none (any not built with `placements`, WebM included).
+     */
+    pollPlacements() {
+        return takePlacements(this.handle);
+    }
     addVideoTrack(info) {
         const index = this.nextIndex++;
         const raw = {
@@ -105,7 +165,7 @@ export class Muxer {
         const raw = {
             stream_id: packet.trackIndex,
             pts: BigInt(packet.pts),
-            dts: BigInt(packet.pts), // dts defaults to pts (no B-frames in the DX contract)
+            dts: BigInt(packet.dts ?? packet.pts), // defaults to pts (no B-frames)
             duration: BigInt(packet.duration),
             is_keyframe: packet.key ?? false,
             is_discard: false,
@@ -203,6 +263,7 @@ export class Demuxer {
             trackIndex,
             data: payload,
             pts: Number(raw.pts),
+            dts: Number(raw.dts),
             duration: Number(raw.duration),
             key: raw.is_keyframe,
         };
@@ -218,6 +279,7 @@ export class Demuxer {
 // Ogg/ADTS/FLV/MPEG-TS/MP3/WAV each need a genuinely different C ABI shape
 // from MP4/WebM's Muxer/Demuxer (no track registration, out-buffer-per-call
 // mux, or a construction-time stream list) — see each module's own top comment.
+export * from "./replay.js";
 export * from "./ogg.js";
 export * from "./adts.js";
 export * from "./flv.js";

package/dist/replay.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Replay ring — keep the last N milliseconds of encoded packets in memory (or just their
+ * locations on disk) and cut "the last M milliseconds" at a keyframe, as a packet sequence
+ * rebased to zero that a fresh {@link Muxer} writes as a standalone file.
+ * (adr/container/0009-replay-ring-c-abi.md)
+ *
+ * **Where the packets come from:** the C ABI has no video-packet source. `EncodeSession` muxes
+ * its encoder's packets internally, and packet-level output exists only for the audio encoder.
+ * Feed the ring packets from a {@link Demuxer}, from the audio encoder, or from an encoder you
+ * drive yourself.
+ *
+ * Ring timestamps are ticks of each stream's own `timeBase`; the anchor stream's keyframes
+ * decide where a clip may start, and other streams (audio) are cut by time to match.
+ */
+import { type Rational } from "./index.js";
+/** What a ring holds for each packet. */
+export type ReplayPayloadKind = "bytes" | "stored";
+export interface ReplayRingOptions {
+    /** The stream whose keyframes decide where a clip may start (normally video). */
+    anchorStreamId: number;
+    /** The anchor's timebase. */
+    anchorTimeBase: Rational;
+    /** How much history to keep, in milliseconds. */
+    windowMs: number;
+    /**
+     * Evict oldest-GOP-first while more than this many payload bytes are held; 0 or omitted = no
+     * ceiling. The newest GOP is always kept, so one larger GOP can exceed it.
+     */
+    maxBytes?: number;
+    /**
+     * `"bytes"`: the ring copies each payload in ({@link ReplayRing.push}). `"stored"`: the ring
+     * keeps only where the bytes are ({@link ReplayRing.pushStored}), for a caller that already
+     * writes packets to a file.
+     */
+    payload: ReplayPayloadKind;
+}
+/** A packet to push into a `"bytes"` ring. Timestamps are ticks of the stream's timebase. */
+export interface ReplayPacket {
+    streamId: number;
+    pts: number;
+    /** Decode timestamp. Must not go backwards within a stream. Defaults to `pts` (no B-frames). */
+    dts?: number;
+    duration: number;
+    key?: boolean;
+    data: Buffer;
+}
+/** A packet's metadata without its payload — input to {@link ReplayRing.pushStored}. */
+export interface ReplayPacketMeta {
+    streamId: number;
+    pts: number;
+    dts?: number;
+    duration: number;
+    key?: boolean;
+}
+/** Where a packet's payload was stored on the caller's disk. */
+export interface StoredLocation {
+    /** The caller's own id for the file. */
+    file: number;
+    /** Byte offset of the payload in that file (exact up to 2^53). */
+    offset: number;
+    /** Payload length in bytes. */
+    length: number;
+}
+interface ReplayEntryBase {
+    streamId: number;
+    /** Rebased so the cut keyframe decodes at zero. */
+    pts: number;
+    dts: number;
+    duration: number;
+    isKeyframe: boolean;
+    isDiscard: boolean;
+}
+/** One packet of a clip cut from a `"bytes"` ring. */
+export interface ReplayBytesEntry extends ReplayEntryBase {
+    kind: "bytes";
+    /** A COPY of the payload: the clip's own pointer is borrowed and never leaves this package. */
+    payload: Buffer;
+}
+/** One packet of a clip cut from a `"stored"` ring. */
+export interface ReplayStoredEntry extends ReplayEntryBase {
+    kind: "stored";
+    stored: StoredLocation;
+}
+export type ReplayEntry = ReplayBytesEntry | ReplayStoredEntry;
+/**
+ * A clip: an OWNED SNAPSHOT of the ring at the moment {@link ReplayRing.clipLast} was called.
+ * Unlike the Rust `Clip` it does not borrow the ring, so it stays valid while the ring keeps
+ * taking packets and after the ring is closed. Release it with {@link close}.
+ */
+export declare class ReplayClip {
+    private handle;
+    /** @internal Use {@link ReplayRing.clipLast}. */
+    constructor(handle: unknown);
+    private live;
+    /** Number of packets. */
+    get length(): number;
+    /** From the cut keyframe to the newest packet pushed when the clip was taken, in ms. */
+    get durationMs(): number;
+    /**
+     * Packet `index` in decode order across streams, timestamps rebased so the cut keyframe
+     * decodes at zero. A `"bytes"` entry's `payload` is a copy.
+     */
+    entry(index: number): ReplayEntry;
+    /** Every entry, in order. Copies each `"bytes"` payload once. */
+    entries(): ReplayEntry[];
+    [Symbol.iterator](): IterableIterator<ReplayEntry>;
+    /** Free the snapshot. Idempotent. */
+    close(): void;
+}
+/**
+ * A rolling buffer of the last `windowMs` of encoded packets.
+ *
+ * Push packets in decode order per stream; {@link clipLast} cuts at a keyframe of the anchor
+ * stream. Anchor packets before the anchor's first keyframe are dropped without error.
+ */
+export declare class ReplayRing {
+    private handle;
+    private readonly kind;
+    private constructor();
+    /** Create a ring. */
+    static create(options: ReplayRingOptions): ReplayRing;
+    private live;
+    /** Carry another stream (e.g. audio), cut by time to match the anchor. */
+    addStream(streamId: number, timeBase: Rational): void;
+    /**
+     * Add a packet to a `"bytes"` ring, then evict whatever fell out of the window.
+     *
+     * The payload is COPIED into the ring (the native call only borrows it), and every clip then
+     * shares that copy.
+     *
+     * @throws {ReplayOutOfOrderError} this stream's `dts` went backwards; the packet was not added
+     *   and the ring is still usable, so drop it and carry on.
+     * @throws {ReplayUnknownStreamError} the stream was never added.
+     * @throws {ReplayPayloadKindError} this is a `"stored"` ring.
+     */
+    push(packet: ReplayPacket): void;
+    /**
+     * Add a packet to a `"stored"` ring: its metadata and where its bytes are. The ring never
+     * reads the file and holds a few dozen bytes per packet. Take the location from
+     * {@link Muxer.pollPlacements} when every polled muxer byte is written to a file.
+     * Errors as {@link push}, with {@link ReplayPayloadKindError} on a `"bytes"` ring.
+     */
+    pushStored(meta: ReplayPacketMeta, stored: StoredLocation): void;
+    /** The longest clip {@link clipLast} can return now, in ms; 0 before the first keyframe. */
+    spanMs(): number;
+    /**
+     * Cut the last `spanMs` of every stream at a keyframe. The clip starts at the latest anchor
+     * keyframe at or before `newest - spanMs`: up to one keyframe interval EARLIER than asked,
+     * never later; with less than `spanMs` held it starts at the oldest keyframe.
+     *
+     * @returns the clip, or `null` until the anchor's first keyframe has been pushed.
+     */
+    clipLast(spanMs: number): ReplayClip | null;
+    /** Whether this ring holds payload bytes or locations. */
+    get payload(): ReplayPayloadKind;
+    /** Close the ring. Clips already taken stay valid. Idempotent. */
+    close(): void;
+}
+/** Where one muxed sample's payload landed in the output stream. */
+export interface Placement {
+    /** The packet's track index (as passed to `Muxer.push`). */
+    trackIndex: number;
+    /** The sample's decode timestamp, as pushed. */
+    dts: number;
+    /**
+     * Absolute byte offset of the payload in the muxer's output: counted from the first byte
+     * `pollBytes` ever returned, so it is the file offset when every polled byte is written
+     * sequentially from 0. Exact up to 2^53.
+     */
+    offset: number;
+    /** Payload length as written: Annex-B becomes length-prefixed and ADTS is stripped. */
+    length: number;
+}
+/** @internal Take the muxer's placements; used by `Muxer.pollPlacements`. */
+export declare function takePlacements(muxer: unknown): Placement[];
+export {};

package/dist/replay.js

@@ -0,0 +1,227 @@
+/**
+ * Replay ring — keep the last N milliseconds of encoded packets in memory (or just their
+ * locations on disk) and cut "the last M milliseconds" at a keyframe, as a packet sequence
+ * rebased to zero that a fresh {@link Muxer} writes as a standalone file.
+ * (adr/container/0009-replay-ring-c-abi.md)
+ *
+ * **Where the packets come from:** the C ABI has no video-packet source. `EncodeSession` muxes
+ * its encoder's packets internally, and packet-level output exists only for the audio encoder.
+ * Feed the ring packets from a {@link Demuxer}, from the audio encoder, or from an encoder you
+ * drive yourself.
+ *
+ * Ring timestamps are ticks of each stream's own `timeBase`; the anchor stream's keyframes
+ * decide where a clip may start, and other streams (audio) are cut by time to match.
+ */
+import { copyBytes, decodeArray, replay, } from "@mediaway/ffi";
+import { MediawayError, ReplayOutOfOrderError, ReplayPayloadKindError, ReplayUnknownStreamError, check, } from "./index.js";
+const PAYLOAD_BYTES = 0;
+const PAYLOAD_STORED = 1;
+/** Map the ring's statuses to distinct classes; everything else is the shared container error. */
+function checkReplay(status) {
+    switch (status) {
+        case 0:
+            return;
+        case 2:
+            throw new ReplayPayloadKindError();
+        case 4:
+            throw new ReplayOutOfOrderError();
+        case 10:
+            throw new ReplayUnknownStreamError();
+        default:
+            check(status);
+    }
+}
+/**
+ * A clip: an OWNED SNAPSHOT of the ring at the moment {@link ReplayRing.clipLast} was called.
+ * Unlike the Rust `Clip` it does not borrow the ring, so it stays valid while the ring keeps
+ * taking packets and after the ring is closed. Release it with {@link close}.
+ */
+export class ReplayClip {
+    handle;
+    /** @internal Use {@link ReplayRing.clipLast}. */
+    constructor(handle) {
+        this.handle = handle;
+    }
+    live() {
+        if (!this.handle)
+            throw new MediawayError(2, "replay clip is closed");
+        return this.handle;
+    }
+    /** Number of packets. */
+    get length() {
+        return Number(replay.clipPacketCount(this.live()));
+    }
+    /** From the cut keyframe to the newest packet pushed when the clip was taken, in ms. */
+    get durationMs() {
+        const out = [0n];
+        checkReplay(replay.clipDurationMs(this.live(), out));
+        return Number(out[0]);
+    }
+    /**
+     * Packet `index` in decode order across streams, timestamps rebased so the cut keyframe
+     * decodes at zero. A `"bytes"` entry's `payload` is a copy.
+     */
+    entry(index) {
+        const raw = {};
+        checkReplay(replay.clipPacketAt(this.live(), index, raw));
+        const base = {
+            streamId: raw.stream_id,
+            pts: Number(raw.pts),
+            dts: Number(raw.dts),
+            duration: Number(raw.duration),
+            isKeyframe: raw.is_keyframe,
+            isDiscard: raw.is_discard,
+        };
+        if (raw.payload_kind === PAYLOAD_STORED) {
+            return {
+                ...base,
+                kind: "stored",
+                stored: { file: raw.stored_file, offset: Number(raw.stored_offset), length: raw.stored_len },
+            };
+        }
+        return { ...base, kind: "bytes", payload: copyBytes(raw.payload, raw.payload_len) };
+    }
+    /** Every entry, in order. Copies each `"bytes"` payload once. */
+    entries() {
+        const n = this.length;
+        const out = [];
+        for (let i = 0; i < n; i++)
+            out.push(this.entry(i));
+        return out;
+    }
+    *[Symbol.iterator]() {
+        const n = this.length;
+        for (let i = 0; i < n; i++)
+            yield this.entry(i);
+    }
+    /** Free the snapshot. Idempotent. */
+    close() {
+        if (this.handle) {
+            replay.clipFree(this.handle);
+            this.handle = null;
+        }
+    }
+}
+/**
+ * A rolling buffer of the last `windowMs` of encoded packets.
+ *
+ * Push packets in decode order per stream; {@link clipLast} cuts at a keyframe of the anchor
+ * stream. Anchor packets before the anchor's first keyframe are dropped without error.
+ */
+export class ReplayRing {
+    handle;
+    kind;
+    constructor(handle, kind) {
+        this.handle = handle;
+        this.kind = kind;
+    }
+    /** Create a ring. */
+    static create(options) {
+        const config = {
+            anchor_stream_id: options.anchorStreamId,
+            anchor_time_base: { num: BigInt(options.anchorTimeBase.num), den: options.anchorTimeBase.den },
+            window_ms: BigInt(options.windowMs),
+            max_bytes: BigInt(options.maxBytes ?? 0),
+            payload_kind: options.payload === "stored" ? PAYLOAD_STORED : PAYLOAD_BYTES,
+        };
+        const out = [null];
+        checkReplay(replay.ringCreate(config, out));
+        return new ReplayRing(out[0], options.payload);
+    }
+    live() {
+        if (!this.handle)
+            throw new MediawayError(2, "replay ring is closed");
+        return this.handle;
+    }
+    /** Carry another stream (e.g. audio), cut by time to match the anchor. */
+    addStream(streamId, timeBase) {
+        checkReplay(replay.ringAddStream(this.live(), streamId, { num: BigInt(timeBase.num), den: timeBase.den }));
+    }
+    /**
+     * Add a packet to a `"bytes"` ring, then evict whatever fell out of the window.
+     *
+     * The payload is COPIED into the ring (the native call only borrows it), and every clip then
+     * shares that copy.
+     *
+     * @throws {ReplayOutOfOrderError} this stream's `dts` went backwards; the packet was not added
+     *   and the ring is still usable, so drop it and carry on.
+     * @throws {ReplayUnknownStreamError} the stream was never added.
+     * @throws {ReplayPayloadKindError} this is a `"stored"` ring.
+     */
+    push(packet) {
+        const raw = {
+            stream_id: packet.streamId,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.dts ?? packet.pts),
+            duration: BigInt(packet.duration),
+            is_keyframe: packet.key ?? false,
+            is_discard: false,
+            payload: packet.data,
+            payload_len: packet.data.length,
+        };
+        checkReplay(replay.ringPush(this.live(), raw));
+    }
+    /**
+     * Add a packet to a `"stored"` ring: its metadata and where its bytes are. The ring never
+     * reads the file and holds a few dozen bytes per packet. Take the location from
+     * {@link Muxer.pollPlacements} when every polled muxer byte is written to a file.
+     * Errors as {@link push}, with {@link ReplayPayloadKindError} on a `"bytes"` ring.
+     */
+    pushStored(meta, stored) {
+        checkReplay(replay.ringPushStored(this.live(), {
+            stream_id: meta.streamId,
+            pts: BigInt(meta.pts),
+            dts: BigInt(meta.dts ?? meta.pts),
+            duration: BigInt(meta.duration),
+            is_keyframe: meta.key ?? false,
+            is_discard: false,
+        }, { file: stored.file, offset: BigInt(stored.offset), len: stored.length }));
+    }
+    /** The longest clip {@link clipLast} can return now, in ms; 0 before the first keyframe. */
+    spanMs() {
+        const out = [0n];
+        checkReplay(replay.ringSpanMs(this.live(), out));
+        return Number(out[0]);
+    }
+    /**
+     * Cut the last `spanMs` of every stream at a keyframe. The clip starts at the latest anchor
+     * keyframe at or before `newest - spanMs`: up to one keyframe interval EARLIER than asked,
+     * never later; with less than `spanMs` held it starts at the oldest keyframe.
+     *
+     * @returns the clip, or `null` until the anchor's first keyframe has been pushed.
+     */
+    clipLast(spanMs) {
+        const clip = [null];
+        const has = [false];
+        checkReplay(replay.ringClipLast(this.live(), BigInt(spanMs), clip, has));
+        return has[0] ? new ReplayClip(clip[0]) : null;
+    }
+    /** Whether this ring holds payload bytes or locations. */
+    get payload() {
+        return this.kind;
+    }
+    /** Close the ring. Clips already taken stay valid. Idempotent. */
+    close() {
+        if (this.handle) {
+            replay.ringClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+/** @internal Take the muxer's placements; used by `Muxer.pollPlacements`. */
+export function takePlacements(muxer) {
+    const rows = [null];
+    const count = [0];
+    checkReplay(replay.muxerPollPlacements(muxer, rows, count));
+    const n = Number(count[0]);
+    const decoded = decodeArray(rows[0], replay.structs.MwPlacement, n);
+    const out = decoded.map((p) => ({
+        trackIndex: p.track_id,
+        dts: Number(p.dts),
+        offset: Number(p.offset),
+        length: p.len,
+    }));
+    if (n > 0)
+        replay.placementsFree(rows[0], n);
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/container",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Rust-based, lightweight, fast — sans-IO fragmented MP4 (fMP4) mux and demux for Node.js — push packets in, poll bytes out",
   "type": "module",
   "main": "./dist/index.js",