@mediaway/container 0.1.3 → 0.1.5

package/dist/adts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @mediaway/container — ADTS mux + demux (adr/container/0004-ogg-adts-c-abi.md).
+ *
+ * Same dedicated-handle reasoning as `ogg.ts`: ADTS has no track-registration
+ * step and no Open/Live typestate.
+ */
+import { type Packet } from "./index.js";
+export interface AdtsStreamInfo {
+    sampleRate: number;
+    channels: number;
+    extraData: Buffer;
+}
+export declare class AdtsMuxer {
+    private handle;
+    /** `sampleRate` must be a standard ADTS sample rate. */
+    constructor(sampleRate: number, channels: number);
+    /** Append one AAC frame (raw, ADTS header added). Fails with INVALID_PACKET
+     * if the payload is too large for ADTS's 13-bit frame-length field. */
+    push(packet: Packet): void;
+    /** No-op — ADTS frames are independently appendable. */
+    flush(): void;
+    pollBytes(): Buffer;
+    close(): void;
+}
+export declare class AdtsDemuxer {
+    private handle;
+    constructor();
+    pushBytes(bytes: Buffer): void;
+    /** Streams discovered so far — 0 or 1 (ADTS carries a single implicit stream). */
+    streams(): AdtsStreamInfo[];
+    /** pts/duration are synthesized from a running 1024-samples-per-frame
+     * count — ADTS carries no per-frame timing of its own. */
+    pollPacket(): Packet | null;
+    close(): void;
+}

package/dist/adts.js

@@ -0,0 +1,100 @@
+/**
+ * @mediaway/container — ADTS mux + demux (adr/container/0004-ogg-adts-c-abi.md).
+ *
+ * Same dedicated-handle reasoning as `ogg.ts`: ADTS has no track-registration
+ * step and no Open/Live typestate.
+ */
+import { container, copyBytes } from "@mediaway/ffi";
+import { MediawayError, check } from "./index.js";
+export class AdtsMuxer {
+    handle;
+    /** `sampleRate` must be a standard ADTS sample rate. */
+    constructor(sampleRate, channels) {
+        this.handle = container.adtsMuxerCreate(sampleRate, channels);
+        if (!this.handle) {
+            throw new MediawayError(1, `non-standard ADTS sample rate (${sampleRate} Hz), or the native call panicked`);
+        }
+    }
+    /** Append one AAC frame (raw, ADTS header added). Fails with INVALID_PACKET
+     * if the payload is too large for ADTS's 13-bit frame-length field. */
+    push(packet) {
+        const raw = {
+            stream_id: packet.trackIndex,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.pts),
+            duration: BigInt(packet.duration),
+            is_keyframe: packet.key ?? false,
+            is_discard: false,
+            payload: packet.data,
+            payload_len: packet.data.length,
+        };
+        check(container.adtsMuxerPushPacket(this.handle, raw));
+    }
+    /** No-op — ADTS frames are independently appendable. */
+    flush() {
+        check(container.adtsMuxerFlush(this.handle));
+    }
+    pollBytes() {
+        const outData = [null];
+        const outLen = [0];
+        check(container.adtsMuxerPollBytes(this.handle, outData, outLen));
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    close() {
+        if (this.handle) {
+            container.adtsMuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+export class AdtsDemuxer {
+    handle;
+    constructor() {
+        this.handle = container.adtsDemuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "ADTS demuxer creation panicked");
+    }
+    pushBytes(bytes) {
+        check(container.adtsDemuxerPushBytes(this.handle, bytes, bytes.length));
+    }
+    /** Streams discovered so far — 0 or 1 (ADTS carries a single implicit stream). */
+    streams() {
+        const count = container.adtsDemuxerStreamCount(this.handle);
+        const out = [];
+        for (let i = 0; i < count; i++) {
+            const raw = {};
+            check(container.adtsDemuxerStreamAt(this.handle, i, raw));
+            const extraData = copyBytes(raw.extra_data, raw.extra_data_len);
+            container.streamInfoFree(raw);
+            out.push({ sampleRate: raw.sample_rate, channels: raw.channels, extraData });
+        }
+        return out;
+    }
+    /** pts/duration are synthesized from a running 1024-samples-per-frame
+     * count — ADTS carries no per-frame timing of its own. */
+    pollPacket() {
+        const raw = {};
+        const has = [false];
+        check(container.adtsDemuxerPollPacket(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const payload = copyBytes(raw.payload, raw.payload_len);
+        container.packetFree(raw);
+        return {
+            trackIndex: raw.stream_id,
+            data: payload,
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            key: raw.is_keyframe,
+        };
+    }
+    close() {
+        if (this.handle) {
+            container.adtsDemuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/dist/flv.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @mediaway/container — FLV mux + demux (adr/container/0005-flv-c-abi.md).
+ *
+ * Unlike `Muxer`, every write method here returns its own freshly allocated
+ * output buffer directly — there is no separate `pollBytes` step. FLV has
+ * exactly one video and one audio slot (no track-id field in the format
+ * itself); `addVideoTrack`/`addAudioTrack` ignore the info's own id and the
+ * fixed `VIDEO_TRACK_ID`/`AUDIO_TRACK_ID` are used instead.
+ */
+import { type AudioTrackInfo, type Packet, type TrackInfo, type VideoTrackInfo } from "./index.js";
+export declare const VIDEO_TRACK_ID = 0;
+export declare const AUDIO_TRACK_ID = 1;
+export declare class FlvMuxer {
+    private handle;
+    constructor();
+    /** Write the FLV file header. Call before any track registration or packet. */
+    writeHeader(hasAudio: boolean, hasVideo: boolean): Buffer;
+    /** Register the video track. Only H264 is recognized (UNSUPPORTED_CODEC otherwise). */
+    addVideoTrack(info: VideoTrackInfo): number;
+    /** Register the audio track. AAC and MP3 are recognized (UNSUPPORTED_CODEC otherwise). */
+    addAudioTrack(info: AudioTrackInfo): number;
+    /** Mux one packet: writes the track's sequence-header tag first (once,
+     * only for codecs that have one) then the data tag. `packet.trackIndex`
+     * selects `VIDEO_TRACK_ID`/`AUDIO_TRACK_ID` and must have a matching
+     * `addVideoTrack`/`addAudioTrack` call already made, else UNKNOWN_STREAM. */
+    push(packet: Packet): Buffer;
+    close(): void;
+}
+export declare class FlvDemuxer {
+    private handle;
+    constructor();
+    pushBytes(bytes: Buffer): void;
+    /** Streams recognized so far — 0, 1, or 2 (fixed video-then-audio slots). */
+    streams(): TrackInfo[];
+    /** Sequence-header tags (AVC/AAC config) update the matching stream's
+     * extra data internally and are not themselves returned as packets. */
+    pollPacket(): Packet | null;
+    close(): void;
+}

package/dist/flv.js

@@ -0,0 +1,156 @@
+/**
+ * @mediaway/container — FLV mux + demux (adr/container/0005-flv-c-abi.md).
+ *
+ * Unlike `Muxer`, every write method here returns its own freshly allocated
+ * output buffer directly — there is no separate `pollBytes` step. FLV has
+ * exactly one video and one audio slot (no track-id field in the format
+ * itself); `addVideoTrack`/`addAudioTrack` ignore the info's own id and the
+ * fixed `VIDEO_TRACK_ID`/`AUDIO_TRACK_ID` are used instead.
+ */
+import { container, copyBytes, } from "@mediaway/ffi";
+import { ABI_TO_CODEC, CODEC_TO_ABI, MediawayError, check, } from "./index.js";
+export const VIDEO_TRACK_ID = 0;
+export const AUDIO_TRACK_ID = 1;
+export class FlvMuxer {
+    handle;
+    constructor() {
+        this.handle = container.flvMuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "FLV muxer creation panicked");
+    }
+    /** Write the FLV file header. Call before any track registration or packet. */
+    writeHeader(hasAudio, hasVideo) {
+        const outData = [null];
+        const outLen = [0];
+        check(container.flvMuxerWriteHeader(this.handle, hasAudio, hasVideo, outData, outLen));
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    /** Register the video track. Only H264 is recognized (UNSUPPORTED_CODEC otherwise). */
+    addVideoTrack(info) {
+        const raw = {
+            id: 0,
+            codec: CODEC_TO_ABI[info.codec] ?? 0,
+            time_base: { num: BigInt(info.timeBase.num), den: info.timeBase.den },
+            width: info.width,
+            height: info.height,
+            extra_data: info.extraData ?? null,
+            extra_data_len: info.extraData?.length ?? 0,
+        };
+        check(container.flvMuxerAddVideoTrack(this.handle, raw));
+        return VIDEO_TRACK_ID;
+    }
+    /** Register the audio track. AAC and MP3 are recognized (UNSUPPORTED_CODEC otherwise). */
+    addAudioTrack(info) {
+        const raw = {
+            id: 0,
+            codec: CODEC_TO_ABI[info.codec] ?? 4,
+            time_base: { num: BigInt(info.timeBase.num), den: info.timeBase.den },
+            sample_rate: info.sampleRate,
+            channels: info.channels,
+            extra_data: info.extraData ?? null,
+            extra_data_len: info.extraData?.length ?? 0,
+        };
+        check(container.flvMuxerAddAudioTrack(this.handle, raw));
+        return AUDIO_TRACK_ID;
+    }
+    /** Mux one packet: writes the track's sequence-header tag first (once,
+     * only for codecs that have one) then the data tag. `packet.trackIndex`
+     * selects `VIDEO_TRACK_ID`/`AUDIO_TRACK_ID` and must have a matching
+     * `addVideoTrack`/`addAudioTrack` call already made, else UNKNOWN_STREAM. */
+    push(packet) {
+        const raw = {
+            stream_id: packet.trackIndex,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.pts),
+            duration: BigInt(packet.duration),
+            is_keyframe: packet.key ?? false,
+            is_discard: false,
+            payload: packet.data,
+            payload_len: packet.data.length,
+        };
+        const outData = [null];
+        const outLen = [0];
+        check(container.flvMuxerPushPacket(this.handle, raw, outData, outLen));
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    close() {
+        if (this.handle) {
+            container.flvMuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+export class FlvDemuxer {
+    handle;
+    constructor() {
+        this.handle = container.flvDemuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "FLV demuxer creation panicked");
+    }
+    pushBytes(bytes) {
+        check(container.flvDemuxerPushBytes(this.handle, bytes, bytes.length));
+    }
+    /** Streams recognized so far — 0, 1, or 2 (fixed video-then-audio slots). */
+    streams() {
+        const count = container.flvDemuxerStreamCount(this.handle);
+        const out = [];
+        for (let i = 0; i < count; i++) {
+            const raw = {};
+            check(container.flvDemuxerStreamAt(this.handle, i, raw));
+            const extraData = copyBytes(raw.extra_data, raw.extra_data_len);
+            container.streamInfoFree(raw);
+            const timeBase = { num: Number(raw.time_base.num), den: raw.time_base.den };
+            if (raw.has_geometry) {
+                out.push({
+                    type: "video",
+                    codec: (ABI_TO_CODEC[raw.codec] ?? "h264"),
+                    width: raw.width,
+                    height: raw.height,
+                    extraData,
+                    timeBase,
+                });
+            }
+            else {
+                out.push({
+                    type: "audio",
+                    codec: (ABI_TO_CODEC[raw.codec] ?? "aac"),
+                    sampleRate: raw.sample_rate,
+                    channels: raw.channels,
+                    extraData,
+                    timeBase,
+                });
+            }
+        }
+        return out;
+    }
+    /** Sequence-header tags (AVC/AAC config) update the matching stream's
+     * extra data internally and are not themselves returned as packets. */
+    pollPacket() {
+        const raw = {};
+        const has = [false];
+        check(container.flvDemuxerPollPacket(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const payload = copyBytes(raw.payload, raw.payload_len);
+        container.packetFree(raw);
+        return {
+            trackIndex: raw.stream_id,
+            data: payload,
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            key: raw.is_keyframe,
+        };
+    }
+    close() {
+        if (this.handle) {
+            container.flvDemuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/dist/index.d.ts

@@ -10,9 +10,13 @@ export interface Rational {
     num: number;
     den: number;
 }
-export type VideoCodec = "h264" | "av1" | "vp9";
-export type AudioCodec = "aac" | "opus";
+export type VideoCodec = "h264" | "hevc" | "av1" | "vp9" | "vp8";
+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.
+ * Only formats sharing MP4's multi-track, typestated shape are reachable
+ * here; Ogg/ADTS/FLV/MPEG-TS/MP3/WAV have their own dedicated classes. */
+export type ContainerFormat = "mp4" | "webm";
 export interface VideoTrackInfo {
     codec: VideoCodec;
     width: number;
@@ -52,15 +56,20 @@ export declare class MediawayError extends Error {
     readonly status: number;
     constructor(status: number, message?: string);
 }
+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;
 /**
  * A muxer in the track-registration (Open) state. Stream indices are assigned
- * in registration order: the first `add*Track` call returns 0, the second 1.
+ * in registration order starting at 1: the first `add*Track` call returns 1,
+ * the second 2 — not 0, since WebM/Matroska's TrackNumber element must not
+ * be 0 (MP4 tolerates 0, but there is no reason to special-case it).
  * `begin()` makes the muxer live; after it, track registration fails.
  */
 export declare class Muxer {
     private handle;
     private nextIndex;
-    constructor();
+    constructor(format?: ContainerFormat);
     addVideoTrack(info: VideoTrackInfo): number;
     addAudioTrack(info: AudioTrackInfo): number;
     /**
@@ -84,7 +93,7 @@ export declare class Muxer {
 export declare class Demuxer {
     private handle;
     private streamIndexById;
-    constructor();
+    constructor(format?: ContainerFormat);
     pushBytes(bytes: Buffer): void;
     /** Streams discovered so far; empty until the init segment has been parsed. */
     streams(): TrackInfo[];
@@ -92,3 +101,9 @@ export declare class Demuxer {
     pollPacket(): Packet | null;
     close(): void;
 }
+export * from "./ogg.js";
+export * from "./adts.js";
+export * from "./flv.js";
+export * from "./ts.js";
+export * from "./mp3.js";
+export * from "./wav.js";

package/dist/index.js

@@ -7,6 +7,7 @@
  * `pts`/`duration` are integer ticks of each track's `timeBase`.
  */
 import { MwPacket, MwPacketView, MwRational, MwStreamInfo, MwVideoTrackInfo, MwAudioTrackInfo, container, copyBytes, } from "@mediaway/ffi";
+const FORMAT_TO_ABI = { mp4: 0, webm: 1 };
 /** Raw per-crate ABI status from mediaway-ffi (mediaway_status_t). */
 export class MediawayError extends Error {
     status;
@@ -15,9 +16,20 @@ export class MediawayError extends Error {
         this.status = status;
     }
 }
-const CODEC_TO_ABI = { h264: 0, hevc: 1, av1: 2, vp9: 3, aac: 4, opus: 5 };
-const ABI_TO_CODEC = Object.fromEntries(Object.entries(CODEC_TO_ABI).map(([k, v]) => [v, k]));
-function check(status) {
+export const CODEC_TO_ABI = {
+    h264: 0,
+    hevc: 1,
+    av1: 2,
+    vp9: 3,
+    aac: 4,
+    opus: 5,
+    mp3: 6,
+    vorbis: 7,
+    raw_audio: 11,
+    vp8: 12,
+};
+export const ABI_TO_CODEC = Object.fromEntries(Object.entries(CODEC_TO_ABI).map(([k, v]) => [v, k]));
+export function check(status) {
     if (status === 0)
         return;
     const names = {
@@ -29,20 +41,25 @@ function check(status) {
         6: "unknown error",
         7: "internal panic (handle poisoned)",
         8: "handle poisoned by an earlier panic",
+        9: "codec has no encoding in this container format",
+        10: "packet's stream id matches no registered track",
     };
     throw new MediawayError(status, names[status] ?? "unknown container error");
 }
 // ── Muxer ──────────────────────────────────────────────────────────────────────
 /**
  * A muxer in the track-registration (Open) state. Stream indices are assigned
- * in registration order: the first `add*Track` call returns 0, the second 1.
+ * in registration order starting at 1: the first `add*Track` call returns 1,
+ * the second 2 — not 0, since WebM/Matroska's TrackNumber element must not
+ * be 0 (MP4 tolerates 0, but there is no reason to special-case it).
  * `begin()` makes the muxer live; after it, track registration fails.
  */
 export class Muxer {
     handle;
-    nextIndex = 0;
-    constructor() {
-        this.handle = container.muxerCreate();
+    nextIndex = 1;
+    constructor(format = "mp4") {
+        this.handle =
+            format === "mp4" ? container.muxerCreate() : container.muxerCreateForFormat(FORMAT_TO_ABI[format]);
         if (!this.handle)
             throw new MediawayError(7, "muxer creation panicked");
     }
@@ -126,8 +143,9 @@ export class Muxer {
 export class Demuxer {
     handle;
     streamIndexById = new Map();
-    constructor() {
-        this.handle = container.demuxerCreate();
+    constructor(format = "mp4") {
+        this.handle =
+            format === "mp4" ? container.demuxerCreate() : container.demuxerCreateForFormat(FORMAT_TO_ABI[format]);
         if (!this.handle)
             throw new MediawayError(7, "demuxer creation panicked");
     }
@@ -196,3 +214,13 @@ export class Demuxer {
         }
     }
 }
+// ── The 6 dedicated-handle formats ──────────────────────────────────────────
+// 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 "./ogg.js";
+export * from "./adts.js";
+export * from "./flv.js";
+export * from "./ts.js";
+export * from "./mp3.js";
+export * from "./wav.js";

package/dist/mp3.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @mediaway/container — MP3 (MPEG Layer III) mux + demux (adr/container/0007-mp3-c-abi.md).
+ *
+ * A fixed header for the mux session's lifetime (no track registration at
+ * all); `writeFrame` takes an explicit `padding` bit no `Packet` has a slot for.
+ */
+import { type Packet } from "./index.js";
+export type MpegVersion = "mpeg1" | "mpeg2" | "mpeg2_5";
+export type ChannelMode = "stereo" | "joint_stereo" | "dual_channel" | "mono";
+/** Fixed Layer III frame header for `Mp3Muxer` — bitrate/sample rate/
+ * channel mode stay constant for the whole mux session's lifetime. */
+export interface Mp3FrameHeader {
+    version: MpegVersion;
+    /** Must be one of the 14 standard Layer III rates for `version`. */
+    bitrateKbps: number;
+    /** Must be one of the 3 standard rates for `version`. */
+    sampleRate: number;
+    channelMode: ChannelMode;
+}
+export interface Mp3StreamInfo {
+    sampleRate: number;
+    channels: number;
+    extraData: Buffer;
+}
+export declare class Mp3Muxer {
+    private handle;
+    /** `header` must be a standard Layer III bitrate/sample-rate combination for its version. */
+    constructor(header: Mp3FrameHeader);
+    /** Append one already-encoded Layer III frame body. Fails with
+     * INVALID_PACKET when `frameBody`'s length doesn't match what the
+     * header's bitrate/sample-rate/padding combination requires. */
+    writeFrame(frameBody: Buffer, padding: boolean): Buffer;
+    close(): void;
+}
+export declare class Mp3Demuxer {
+    private handle;
+    constructor();
+    pushBytes(bytes: Buffer): void;
+    /** Streams discovered so far — 0 or 1 (MP3 carries a single implicit stream). */
+    streams(): Mp3StreamInfo[];
+    /** pts/duration are synthesized from a running samples-per-frame count —
+     * MPEG audio carries no per-frame timing of its own. */
+    pollPacket(): Packet | null;
+    close(): void;
+}

package/dist/mp3.js

@@ -0,0 +1,97 @@
+/**
+ * @mediaway/container — MP3 (MPEG Layer III) mux + demux (adr/container/0007-mp3-c-abi.md).
+ *
+ * A fixed header for the mux session's lifetime (no track registration at
+ * all); `writeFrame` takes an explicit `padding` bit no `Packet` has a slot for.
+ */
+import { container, copyBytes } from "@mediaway/ffi";
+import { MediawayError, check } from "./index.js";
+const MPEG_VERSION_TO_ABI = { mpeg1: 0, mpeg2: 1, mpeg2_5: 2 };
+const CHANNEL_MODE_TO_ABI = {
+    stereo: 0,
+    joint_stereo: 1,
+    dual_channel: 2,
+    mono: 3,
+};
+export class Mp3Muxer {
+    handle;
+    /** `header` must be a standard Layer III bitrate/sample-rate combination for its version. */
+    constructor(header) {
+        const raw = {
+            version: MPEG_VERSION_TO_ABI[header.version],
+            bitrate_kbps: header.bitrateKbps,
+            sample_rate: header.sampleRate,
+            channel_mode: CHANNEL_MODE_TO_ABI[header.channelMode],
+        };
+        this.handle = container.mp3MuxerCreate(raw);
+        if (!this.handle) {
+            throw new MediawayError(1, "non-standard MP3 bitrate/sample-rate combination, or the native call panicked");
+        }
+    }
+    /** Append one already-encoded Layer III frame body. Fails with
+     * INVALID_PACKET when `frameBody`'s length doesn't match what the
+     * header's bitrate/sample-rate/padding combination requires. */
+    writeFrame(frameBody, padding) {
+        const outData = [null];
+        const outLen = [0];
+        check(container.mp3MuxerWriteFrame(this.handle, frameBody, frameBody.length, padding, outData, outLen));
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    close() {
+        if (this.handle) {
+            container.mp3MuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+export class Mp3Demuxer {
+    handle;
+    constructor() {
+        this.handle = container.mp3DemuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "MP3 demuxer creation panicked");
+    }
+    pushBytes(bytes) {
+        check(container.mp3DemuxerPushBytes(this.handle, bytes, bytes.length));
+    }
+    /** Streams discovered so far — 0 or 1 (MP3 carries a single implicit stream). */
+    streams() {
+        const count = container.mp3DemuxerStreamCount(this.handle);
+        const out = [];
+        for (let i = 0; i < count; i++) {
+            const raw = {};
+            check(container.mp3DemuxerStreamAt(this.handle, i, raw));
+            const extraData = copyBytes(raw.extra_data, raw.extra_data_len);
+            container.streamInfoFree(raw);
+            out.push({ sampleRate: raw.sample_rate, channels: raw.channels, extraData });
+        }
+        return out;
+    }
+    /** pts/duration are synthesized from a running samples-per-frame count —
+     * MPEG audio carries no per-frame timing of its own. */
+    pollPacket() {
+        const raw = {};
+        const has = [false];
+        check(container.mp3DemuxerPollPacket(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const payload = copyBytes(raw.payload, raw.payload_len);
+        container.packetFree(raw);
+        return {
+            trackIndex: raw.stream_id,
+            data: payload,
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            key: raw.is_keyframe,
+        };
+    }
+    close() {
+        if (this.handle) {
+            container.mp3DemuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/dist/ogg.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @mediaway/container — Ogg mux + demux (adr/container/0004-ogg-adts-c-abi.md).
+ *
+ * Dedicated handles, not `Muxer`/`Demuxer`: Ogg has no track-registration
+ * step and no Open/Live typestate — `OggMuxer` is immediately ready for
+ * `push`. Reuses the shared `Packet`/`TrackInfo` shapes and `MediawayError`.
+ */
+import { type AudioCodec, type Packet, type VideoCodec } from "./index.js";
+export interface OggStreamInfo {
+    codec: AudioCodec | VideoCodec;
+    sampleRate: number;
+    channels: number;
+    extraData: Buffer;
+}
+export declare class OggMuxer {
+    private handle;
+    constructor(serial: number);
+    /** Write one Ogg page. `packet.pts` becomes the page's granule position;
+     * fails with INVALID_DATA when the payload exceeds a single page. */
+    push(packet: Packet): void;
+    /** No-op — every `push` call already wrote a complete, independently valid Ogg page. */
+    flush(): void;
+    pollBytes(): Buffer;
+    close(): void;
+}
+export declare class OggDemuxer {
+    private handle;
+    constructor();
+    pushBytes(bytes: Buffer): void;
+    /** Streams discovered so far — 0 or 1 (Ogg carries a single logical bitstream). */
+    streams(): OggStreamInfo[];
+    pollPacket(): Packet | null;
+    close(): void;
+}

package/dist/ogg.js

@@ -0,0 +1,102 @@
+/**
+ * @mediaway/container — Ogg mux + demux (adr/container/0004-ogg-adts-c-abi.md).
+ *
+ * Dedicated handles, not `Muxer`/`Demuxer`: Ogg has no track-registration
+ * step and no Open/Live typestate — `OggMuxer` is immediately ready for
+ * `push`. Reuses the shared `Packet`/`TrackInfo` shapes and `MediawayError`.
+ */
+import { container, copyBytes } from "@mediaway/ffi";
+import { ABI_TO_CODEC, MediawayError, check } from "./index.js";
+export class OggMuxer {
+    handle;
+    constructor(serial) {
+        this.handle = container.oggMuxerCreate(serial);
+        if (!this.handle)
+            throw new MediawayError(7, "Ogg muxer creation panicked");
+    }
+    /** Write one Ogg page. `packet.pts` becomes the page's granule position;
+     * fails with INVALID_DATA when the payload exceeds a single page. */
+    push(packet) {
+        const raw = {
+            stream_id: packet.trackIndex,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.pts),
+            duration: BigInt(packet.duration),
+            is_keyframe: packet.key ?? false,
+            is_discard: false,
+            payload: packet.data,
+            payload_len: packet.data.length,
+        };
+        check(container.oggMuxerPushPacket(this.handle, raw));
+    }
+    /** No-op — every `push` call already wrote a complete, independently valid Ogg page. */
+    flush() {
+        check(container.oggMuxerFlush(this.handle));
+    }
+    pollBytes() {
+        const outData = [null];
+        const outLen = [0];
+        check(container.oggMuxerPollBytes(this.handle, outData, outLen));
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    close() {
+        if (this.handle) {
+            container.oggMuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+export class OggDemuxer {
+    handle;
+    constructor() {
+        this.handle = container.oggDemuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "Ogg demuxer creation panicked");
+    }
+    pushBytes(bytes) {
+        check(container.oggDemuxerPushBytes(this.handle, bytes, bytes.length));
+    }
+    /** Streams discovered so far — 0 or 1 (Ogg carries a single logical bitstream). */
+    streams() {
+        const count = container.oggDemuxerStreamCount(this.handle);
+        const out = [];
+        for (let i = 0; i < count; i++) {
+            const raw = {};
+            check(container.oggDemuxerStreamAt(this.handle, i, raw));
+            const extraData = copyBytes(raw.extra_data, raw.extra_data_len);
+            container.streamInfoFree(raw);
+            out.push({
+                codec: (ABI_TO_CODEC[raw.codec] ?? "opus"),
+                sampleRate: raw.sample_rate,
+                channels: raw.channels,
+                extraData,
+            });
+        }
+        return out;
+    }
+    pollPacket() {
+        const raw = {};
+        const has = [false];
+        check(container.oggDemuxerPollPacket(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const payload = copyBytes(raw.payload, raw.payload_len);
+        container.packetFree(raw);
+        return {
+            trackIndex: raw.stream_id,
+            data: payload,
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            key: raw.is_keyframe,
+        };
+    }
+    close() {
+        if (this.handle) {
+            container.oggDemuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/dist/ts.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @mediaway/container — MPEG-TS mux + demux (adr/container/0006-mpeg-ts-c-abi.md).
+ *
+ * The full elementary-stream list is fixed at construction (no `addTrack`
+ * after); `writePatPmt`/`writeAccessUnit` write directly into a freshly
+ * allocated output buffer with explicit 90 kHz `pts`/`dts` clock values —
+ * not a track-relative time base.
+ */
+import { type AudioCodec, type Packet, type TrackInfo, type VideoCodec } from "./index.js";
+export interface TsElementaryStream {
+    /** TS packet identifier, must be in `2..=0x1FFF` (0/1 are reserved for PAT/CAT). */
+    pid: number;
+    /** Must be H264, HEVC, AAC, or MP3. */
+    codec: VideoCodec | AudioCodec;
+}
+export declare class TsMuxer {
+    private handle;
+    /** `pmtPid` and every stream's `pid` must be in `2..=0x1FFF`; every
+     * stream's codec must be H264/HEVC/AAC/MP3. */
+    constructor(programNumber: number, pmtPid: number, streams: TsElementaryStream[]);
+    /** Write PAT + PMT packets. Call once at the start and periodically
+     * thereafter — real players expect PAT/PMT to repeat. */
+    writePatPmt(): Buffer;
+    /** Packetize one access unit for `pid` into PES + TS packets. `pts90k`/
+     * `dts90k` are the real MPEG-TS 90 kHz clock values; `dts90k === null`
+     * means "no DTS". */
+    writeAccessUnit(pid: number, data: Buffer, pts90k: number, dts90k: number | null, randomAccess: boolean): Buffer;
+    close(): void;
+}
+export declare class TsDemuxer {
+    private handle;
+    constructor();
+    /** Feed bytes — need not be 188-byte aligned across calls. */
+    pushBytes(bytes: Buffer): void;
+    /** Streams whose stream_type maps to a recognized codec (H264/HEVC/AAC/MP3).
+     * Empty until `pollPacket` has actually consumed the PMT (lazy PSI parsing). */
+    streams(): TrackInfo[];
+    /** A PID with no recognized codec mapping is silently skipped. */
+    pollPacket(): Packet | null;
+    /** Force-emit whatever is still accumulating per PID — call once at the
+     * end of a stream so the very last access unit per PID isn't lost
+     * (MPEG-TS only confirms a PES boundary once the next packet on the same
+     * PID starts). */
+    finish(): Packet[];
+    close(): void;
+}

package/dist/ts.js

@@ -0,0 +1,139 @@
+/**
+ * @mediaway/container — MPEG-TS mux + demux (adr/container/0006-mpeg-ts-c-abi.md).
+ *
+ * The full elementary-stream list is fixed at construction (no `addTrack`
+ * after); `writePatPmt`/`writeAccessUnit` write directly into a freshly
+ * allocated output buffer with explicit 90 kHz `pts`/`dts` clock values —
+ * not a track-relative time base.
+ */
+import { MwPacket, container, copyBytes, decodeArray, } from "@mediaway/ffi";
+import { ABI_TO_CODEC, CODEC_TO_ABI, MediawayError, check } from "./index.js";
+export class TsMuxer {
+    handle;
+    /** `pmtPid` and every stream's `pid` must be in `2..=0x1FFF`; every
+     * stream's codec must be H264/HEVC/AAC/MP3. */
+    constructor(programNumber, pmtPid, streams) {
+        const raw = streams.map((s) => ({ pid: s.pid, codec: CODEC_TO_ABI[s.codec] ?? 0 }));
+        this.handle = container.tsMuxerCreate(programNumber, pmtPid, raw, raw.length);
+        if (!this.handle) {
+            throw new MediawayError(1, "invalid PMT/elementary-stream PID, an unsupported elementary-stream codec, or the native call panicked");
+        }
+    }
+    /** Write PAT + PMT packets. Call once at the start and periodically
+     * thereafter — real players expect PAT/PMT to repeat. */
+    writePatPmt() {
+        const outData = [null];
+        const outLen = [0];
+        check(container.tsMuxerWritePatPmt(this.handle, outData, outLen));
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    /** Packetize one access unit for `pid` into PES + TS packets. `pts90k`/
+     * `dts90k` are the real MPEG-TS 90 kHz clock values; `dts90k === null`
+     * means "no DTS". */
+    writeAccessUnit(pid, data, pts90k, dts90k, randomAccess) {
+        const outData = [null];
+        const outLen = [0];
+        check(container.tsMuxerWriteAccessUnit(this.handle, pid, data, data.length, BigInt(pts90k), dts90k !== null, BigInt(dts90k ?? 0), randomAccess, outData, outLen));
+        const result = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return result;
+    }
+    close() {
+        if (this.handle) {
+            container.tsMuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+function streamInfoToManaged(raw, extraData) {
+    const timeBase = { num: Number(raw.time_base.num), den: raw.time_base.den };
+    if (raw.has_geometry) {
+        return {
+            type: "video",
+            codec: (ABI_TO_CODEC[raw.codec] ?? "h264"),
+            width: raw.width,
+            height: raw.height,
+            extraData,
+            timeBase,
+        };
+    }
+    return {
+        type: "audio",
+        codec: (ABI_TO_CODEC[raw.codec] ?? "aac"),
+        sampleRate: raw.sample_rate,
+        channels: raw.channels,
+        extraData,
+        timeBase,
+    };
+}
+function packetToManaged(raw) {
+    return {
+        trackIndex: raw.stream_id,
+        data: copyBytes(raw.payload, raw.payload_len),
+        pts: Number(raw.pts),
+        duration: Number(raw.duration),
+        key: raw.is_keyframe,
+    };
+}
+export class TsDemuxer {
+    handle;
+    constructor() {
+        this.handle = container.tsDemuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "MPEG-TS demuxer creation panicked");
+    }
+    /** Feed bytes — need not be 188-byte aligned across calls. */
+    pushBytes(bytes) {
+        check(container.tsDemuxerPushBytes(this.handle, bytes, bytes.length));
+    }
+    /** Streams whose stream_type maps to a recognized codec (H264/HEVC/AAC/MP3).
+     * Empty until `pollPacket` has actually consumed the PMT (lazy PSI parsing). */
+    streams() {
+        const count = container.tsDemuxerStreamCount(this.handle);
+        const out = [];
+        for (let i = 0; i < count; i++) {
+            const raw = {};
+            check(container.tsDemuxerStreamAt(this.handle, i, raw));
+            const extraData = copyBytes(raw.extra_data, raw.extra_data_len);
+            container.streamInfoFree(raw);
+            out.push(streamInfoToManaged(raw, extraData));
+        }
+        return out;
+    }
+    /** A PID with no recognized codec mapping is silently skipped. */
+    pollPacket() {
+        const raw = {};
+        const has = [false];
+        check(container.tsDemuxerPollPacket(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const packet = packetToManaged(raw);
+        container.packetFree(raw);
+        return packet;
+    }
+    /** Force-emit whatever is still accumulating per PID — call once at the
+     * end of a stream so the very last access unit per PID isn't lost
+     * (MPEG-TS only confirms a PES boundary once the next packet on the same
+     * PID starts). */
+    finish() {
+        const outPackets = [null];
+        const outCount = [0];
+        check(container.tsDemuxerFinish(this.handle, outPackets, outCount));
+        const count = outCount[0];
+        const decoded = decodeArray(outPackets[0], MwPacket, count);
+        const result = decoded.map(packetToManaged);
+        if (count > 0)
+            container.tsDemuxerFinishFree(outPackets[0], count);
+        return result;
+    }
+    close() {
+        if (this.handle) {
+            container.tsDemuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/dist/wav.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @mediaway/container — WAV mux + one-shot parse (adr/container/0008-wav-c-abi.md).
+ *
+ * `wav::Muxer::finish` consumes `self` by value on the Rust side (RIFF chunk
+ * sizes must be known up front), so there is no `pollBytes` step — `finish`
+ * returns the complete byte stream directly. Demux has NO handle at all:
+ * `parseWav` is a one-shot whole-buffer function, unlike every other format
+ * in this package.
+ */
+import { type Packet, type TrackInfo } from "./index.js";
+export type WavSampleFormat = "pcm" | "float";
+/** Explicit RIFF/WAVE fmt chunk for `WavMuxer`. */
+export interface WaveFormat {
+    sampleFormat: WavSampleFormat;
+    channels: number;
+    sampleRate: number;
+    bitsPerSample: number;
+}
+export interface WavParseResult {
+    info: TrackInfo;
+    packet: Packet;
+}
+export declare class WavMuxer {
+    private handle;
+    private finished;
+    /** Start an integer-PCM mux session, or pass a `WaveFormat` for an
+     * explicit format (e.g. IEEE float PCM). */
+    constructor(sampleRateOrFormat: number | WaveFormat, channels?: number, bitsPerSample?: number);
+    /** Append raw interleaved PCM bytes, already encoded per the session's format. */
+    push(packet: Packet): void;
+    /** Finalize the mux session and return the complete RIFF/WAVE byte stream.
+     * Only the native-side internal state is consumed — this `WavMuxer` stays
+     * usable for `close()` afterward. A second call fails with INVALID_STATE
+     * rather than re-finalizing. */
+    finish(): Buffer;
+    get isFinished(): boolean;
+    close(): void;
+}
+/** Parse a complete RIFF/WAVE buffer into its single track's stream info
+ * and one packet holding the whole PCM payload. */
+export declare function parseWav(data: Buffer): WavParseResult;

package/dist/wav.js

@@ -0,0 +1,100 @@
+/**
+ * @mediaway/container — WAV mux + one-shot parse (adr/container/0008-wav-c-abi.md).
+ *
+ * `wav::Muxer::finish` consumes `self` by value on the Rust side (RIFF chunk
+ * sizes must be known up front), so there is no `pollBytes` step — `finish`
+ * returns the complete byte stream directly. Demux has NO handle at all:
+ * `parseWav` is a one-shot whole-buffer function, unlike every other format
+ * in this package.
+ */
+import { container, copyBytes } from "@mediaway/ffi";
+import { ABI_TO_CODEC, MediawayError, check } from "./index.js";
+const WAV_SAMPLE_FORMAT_TO_ABI = { pcm: 0, float: 1 };
+export class WavMuxer {
+    handle;
+    finished = false;
+    /** Start an integer-PCM mux session, or pass a `WaveFormat` for an
+     * explicit format (e.g. IEEE float PCM). */
+    constructor(sampleRateOrFormat, channels, bitsPerSample) {
+        if (typeof sampleRateOrFormat === "number") {
+            this.handle = container.wavMuxerCreate(sampleRateOrFormat, channels, bitsPerSample);
+        }
+        else {
+            const raw = {
+                sample_format: WAV_SAMPLE_FORMAT_TO_ABI[sampleRateOrFormat.sampleFormat],
+                channels: sampleRateOrFormat.channels,
+                sample_rate: sampleRateOrFormat.sampleRate,
+                bits_per_sample: sampleRateOrFormat.bitsPerSample,
+            };
+            this.handle = container.wavMuxerCreateWithFormat(raw);
+        }
+        if (!this.handle)
+            throw new MediawayError(7, "WAV muxer creation panicked");
+    }
+    /** Append raw interleaved PCM bytes, already encoded per the session's format. */
+    push(packet) {
+        const raw = {
+            stream_id: packet.trackIndex,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.pts),
+            duration: BigInt(packet.duration),
+            is_keyframe: packet.key ?? false,
+            is_discard: false,
+            payload: packet.data,
+            payload_len: packet.data.length,
+        };
+        check(container.wavMuxerPushPacket(this.handle, raw));
+    }
+    /** Finalize the mux session and return the complete RIFF/WAVE byte stream.
+     * Only the native-side internal state is consumed — this `WavMuxer` stays
+     * usable for `close()` afterward. A second call fails with INVALID_STATE
+     * rather than re-finalizing. */
+    finish() {
+        const outData = [null];
+        const outLen = [0];
+        check(container.wavMuxerFinish(this.handle, outData, outLen));
+        this.finished = true;
+        const data = copyBytes(outData[0], outLen[0]);
+        if (outLen[0] > 0)
+            container.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    get isFinished() {
+        return this.finished;
+    }
+    close() {
+        if (this.handle) {
+            container.wavMuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+/** Parse a complete RIFF/WAVE buffer into its single track's stream info
+ * and one packet holding the whole PCM payload. */
+export function parseWav(data) {
+    const outInfo = {};
+    const outPacket = {};
+    check(container.wavParse(data, data.length, outInfo, outPacket));
+    const extraData = copyBytes(outInfo.extra_data, outInfo.extra_data_len);
+    const timeBase = { num: Number(outInfo.time_base.num), den: outInfo.time_base.den };
+    // WAV always parses to an audio track (RIFF/WAVE has no video concept).
+    const info = {
+        type: "audio",
+        codec: (ABI_TO_CODEC[outInfo.codec] ?? "raw_audio"),
+        sampleRate: outInfo.sample_rate,
+        channels: outInfo.channels,
+        extraData,
+        timeBase,
+    };
+    container.streamInfoFree(outInfo);
+    const payload = copyBytes(outPacket.payload, outPacket.payload_len);
+    const packet = {
+        trackIndex: outPacket.stream_id,
+        data: payload,
+        pts: Number(outPacket.pts),
+        duration: Number(outPacket.duration),
+        key: outPacket.is_keyframe,
+    };
+    container.packetFree(outPacket);
+    return { info, packet };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediaway/container",
-  "version": "0.1.3",
-  "description": "Sans-IO fragmented MP4 (fMP4) mux and demux for Node.js — push packets in, poll bytes out",
+  "version": "0.1.5",
+  "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",
   "types": "./dist/index.d.ts",
@@ -26,7 +26,7 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@mediaway/ffi": "0.1.0"
+    "@mediaway/ffi": "^0.1.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0"