@mediaway/container 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @mediaway/container — container capability: sans-io fragmented-MP4 mux + demux.
+ *
+ * Implements the DX contract in bindings/nodejs/README.md over the
+ * mediaway-ffi C ABI (via @mediaway/ffi). Typed structs in, typed
+ * structs out; the muxer never touches files — the caller owns byte I/O.
+ * `pts`/`duration` are integer ticks of each track's `timeBase`.
+ */
+export interface Rational {
+    num: number;
+    den: number;
+}
+export type VideoCodec = "h264" | "av1" | "vp9";
+export type AudioCodec = "aac" | "opus";
+export type PixelFormat = "nv12" | "bgra8" | "rgba8" | "i420" | "yuy2";
+export interface VideoTrackInfo {
+    codec: VideoCodec;
+    width: number;
+    height: number;
+    timeBase: Rational;
+    pixelFormat?: PixelFormat;
+    /** Codec config (avcC etc.); empty = placeholder written. */
+    extraData?: Buffer;
+}
+export interface AudioTrackInfo {
+    codec: AudioCodec;
+    sampleRate: number;
+    channels: number;
+    timeBase: Rational;
+    bitDepth?: number;
+    /** Codec config (AudioSpecificConfig); empty = placeholder written. */
+    extraData?: Buffer;
+}
+export type TrackInfo = ({
+    type: "video";
+} & VideoTrackInfo) | ({
+    type: "audio";
+} & AudioTrackInfo);
+export interface Packet {
+    /** Index into `Demuxer.streams()` (demux side) / track index (mux side). */
+    trackIndex: number;
+    data: Buffer;
+    /** Ticks of the track's timeBase. */
+    pts: number;
+    /** Ticks of the track's timeBase. */
+    duration: number;
+    /** Sync sample / keyframe. */
+    key?: boolean;
+}
+/** Raw per-crate ABI status from mediaway-ffi (mediaway_status_t). */
+export declare class MediawayError extends Error {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}
+/**
+ * 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.
+ * `begin()` makes the muxer live; after it, track registration fails.
+ */
+export declare class Muxer {
+    private handle;
+    private nextIndex;
+    constructor();
+    addVideoTrack(info: VideoTrackInfo): number;
+    addAudioTrack(info: AudioTrackInfo): number;
+    /**
+     * Make the muxer live and return the bytes queued so far (the init segment,
+     * ftyp + moov — may be empty until the first media bytes are flushed; the
+     * ABI emits the init segment lazily with the first fragment).
+     */
+    begin(): Buffer;
+    /** Push one packet (sync; the muxer never blocks on I/O). */
+    push(packet: Packet): void;
+    /** End of input — finalizes the last fragment. */
+    flush(): void;
+    /** Drain bytes queued since the last call; empty Buffer when nothing is pending. */
+    pollBytes(): Buffer;
+    close(): void;
+}
+/**
+ * A streaming demuxer: feed container bytes, poll streams and packets.
+ * `packet.trackIndex` indexes the `streams()` list.
+ */
+export declare class Demuxer {
+    private handle;
+    private streamIndexById;
+    constructor();
+    pushBytes(bytes: Buffer): void;
+    /** Streams discovered so far; empty until the init segment has been parsed. */
+    streams(): TrackInfo[];
+    /** The next demuxed packet, or null when the stream is exhausted. */
+    pollPacket(): Packet | null;
+    close(): void;
+}

package/dist/index.js

@@ -0,0 +1,198 @@
+/**
+ * @mediaway/container — container capability: sans-io fragmented-MP4 mux + demux.
+ *
+ * Implements the DX contract in bindings/nodejs/README.md over the
+ * mediaway-ffi C ABI (via @mediaway/ffi). Typed structs in, typed
+ * 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";
+/** Raw per-crate ABI status from mediaway-ffi (mediaway_status_t). */
+export class MediawayError extends Error {
+    status;
+    constructor(status, message) {
+        super(message ?? `mediaway error (status ${status})`);
+        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) {
+    if (status === 0)
+        return;
+    const names = {
+        1: "invalid argument",
+        2: "invalid state (typestate violation)",
+        3: "invalid or duplicate track id",
+        4: "packet does not match a registered track",
+        5: "truncated or malformed container data",
+        6: "unknown error",
+        7: "internal panic (handle poisoned)",
+        8: "handle poisoned by an earlier panic",
+    };
+    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.
+ * `begin()` makes the muxer live; after it, track registration fails.
+ */
+export class Muxer {
+    handle;
+    nextIndex = 0;
+    constructor() {
+        this.handle = container.muxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "muxer creation panicked");
+    }
+    addVideoTrack(info) {
+        const index = this.nextIndex++;
+        const raw = {
+            id: index,
+            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.muxerAddVideoTrack(this.handle, raw));
+        return index;
+    }
+    addAudioTrack(info) {
+        const index = this.nextIndex++;
+        const raw = {
+            id: index,
+            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.muxerAddAudioTrack(this.handle, raw));
+        return index;
+    }
+    /**
+     * Make the muxer live and return the bytes queued so far (the init segment,
+     * ftyp + moov — may be empty until the first media bytes are flushed; the
+     * ABI emits the init segment lazily with the first fragment).
+     */
+    begin() {
+        check(container.muxerBegin(this.handle));
+        return this.pollBytes();
+    }
+    /** Push one packet (sync; the muxer never blocks on I/O). */
+    push(packet) {
+        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)
+            duration: BigInt(packet.duration),
+            is_keyframe: packet.key ?? false,
+            is_discard: false,
+            payload: packet.data,
+            payload_len: packet.data.length,
+        };
+        check(container.muxerPushPacket(this.handle, raw));
+    }
+    /** End of input — finalizes the last fragment. */
+    flush() {
+        check(container.muxerFlush(this.handle));
+    }
+    /** Drain bytes queued since the last call; empty Buffer when nothing is pending. */
+    pollBytes() {
+        const outData = [null];
+        const outLen = [0];
+        check(container.muxerPollBytes(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.muxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+// ── Demuxer ────────────────────────────────────────────────────────────────────
+/**
+ * A streaming demuxer: feed container bytes, poll streams and packets.
+ * `packet.trackIndex` indexes the `streams()` list.
+ */
+export class Demuxer {
+    handle;
+    streamIndexById = new Map();
+    constructor() {
+        this.handle = container.demuxerCreate();
+        if (!this.handle)
+            throw new MediawayError(7, "demuxer creation panicked");
+    }
+    pushBytes(bytes) {
+        check(container.demuxerPushBytes(this.handle, bytes, bytes.length));
+    }
+    /** Streams discovered so far; empty until the init segment has been parsed. */
+    streams() {
+        const count = container.demuxerStreamCount(this.handle);
+        const out = [];
+        this.streamIndexById.clear();
+        for (let i = 0; i < count; i++) {
+            const raw = {};
+            check(container.demuxerStreamAt(this.handle, i, raw));
+            const extra = copyBytes(raw.extra_data, raw.extra_data_len);
+            container.streamInfoFree(raw);
+            this.streamIndexById.set(raw.id, i);
+            const common = {
+                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: extra,
+                    ...common,
+                });
+            }
+            else {
+                out.push({
+                    type: "audio",
+                    codec: (ABI_TO_CODEC[raw.codec] ?? "aac"),
+                    sampleRate: raw.sample_rate,
+                    channels: raw.channels,
+                    extraData: extra,
+                    ...common,
+                });
+            }
+        }
+        return out;
+    }
+    /** The next demuxed packet, or null when the stream is exhausted. */
+    pollPacket() {
+        const raw = {};
+        const has = [false];
+        check(container.demuxerPollPacket(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const payload = copyBytes(raw.payload, raw.payload_len);
+        container.packetFree(raw);
+        const trackIndex = this.streamIndexById.get(raw.stream_id) ?? raw.stream_id;
+        return {
+            trackIndex,
+            data: payload,
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            key: raw.is_keyframe,
+        };
+    }
+    close() {
+        if (this.handle) {
+            container.demuxerClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mediaway/container",
+  "version": "0.1.0",
+  "description": "Mediaway fMP4 mux/demux over the C ABI (mediaway-ffi)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nyxways/mediaway.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@mediaway/ffi": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}