@mediaway/encoder 0.1.3 → 0.1.5

package/dist/decode.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @mediaway/encoder — pipeline capability: auto video decode + Opus audio decode.
+ *
+ * Wraps the mediaway-ffi C ABI's decode sessions (adr/0004-auto-decode-c-abi.md,
+ * adr/pipeline/0006-audio-decode-c-abi.md) — the same "C ABI real, no
+ * language binding wired" gap the container format series closed for
+ * mux/demux, closed here for decode. Both sessions mirror
+ * `openAutoEncoder()`/`AudioEncoder`'s single-step shape (the handle IS the
+ * decoder, no consumption trap); `NO_BACKEND` throws
+ * `DecoderUnavailableError`, an expected/graceful outcome.
+ */
+import { MediawayError, type Rational } from "@mediaway/container";
+import { type PixelFormat, type VideoCodec } from "./index.js";
+/** No decoder backend is openable for this config — expected on machines
+ * without a usable decoder; catch it and exit gracefully. */
+export declare class DecoderUnavailableError extends MediawayError {
+}
+export interface VideoDecodeConfig {
+    codec: VideoCodec;
+    /** Expected; may be refined from the bitstream. */
+    width: number;
+    height: number;
+    timeBase: Rational;
+    /** Preferred output format when the backend converts. */
+    pixelFormat?: PixelFormat;
+    /** AVCC / SPS-PPS codec config, required at open time — not supplied via
+     * the first pushed packet (adr/0004 §1: the muxer-track analogy does not
+     * hold for the wrapped decoder). */
+    extraData?: Buffer;
+}
+/** Input to `DecodeSession.pushPacket`/`AudioDecodeSession.pushPacket` — a
+ * pipeline-scoped packet view, distinct from `@mediaway/container`'s
+ * `Packet` (adr/pipeline/0006 §4: shared by both video and audio decode). */
+export interface DecodePacket {
+    pts: number;
+    dts?: number;
+    duration?: number;
+    keyframe?: boolean;
+    /** For audio: an empty payload is Opus's packet-loss-concealment hint for
+     * a lost frame, not an error — pass it whenever a frame is known lost. */
+    payload: Buffer;
+}
+export interface DecodedVideoFrame {
+    pts: number;
+    duration: number;
+    width: number;
+    height: number;
+    pixelFormat: PixelFormat;
+    data: Buffer;
+}
+export interface DecodedAudioFrame {
+    pts: number;
+    duration: number;
+    sampleRate: number;
+    channels: number;
+    data: Buffer;
+}
+/**
+ * The best available video decode session for a config — the handle IS the
+ * decoder (single-step open, no consumption trap, mirrors `openAutoEncoder`'s
+ * `NO_BACKEND` handling). CPU output only (GPU decode output is deferred,
+ * adr/0004 §1/§5).
+ */
+export declare class DecodeSession {
+    private handle;
+    private constructor();
+    /** Open the best available video decoder for `config`. Throws
+     * DecoderUnavailableError when no decode backend exists on this machine. */
+    static open(config: VideoDecodeConfig): Promise<DecodeSession>;
+    /** Push one compressed packet. May produce zero or more frames (drain via
+     * `pollFrame()`). */
+    pushPacket(packet: DecodePacket): Promise<void>;
+    /** Pull the next decoded frame, if one is ready. null is a valid "nothing
+     * ready" result, not an error. */
+    pollFrame(): Promise<DecodedVideoFrame | null>;
+    /** Signal end of input; drain the remaining frames with pollFrame(). */
+    flush(): Promise<void>;
+    /** Always safe — no handle-consumption trap on this surface. */
+    close(): void;
+}
+/**
+ * An Opus audio decode session — the handle IS the decoder (adr/pipeline/0006,
+ * mirrors `DecodeSession`'s video shape; no muxer to wire, no consumption
+ * trap). Cross-platform (mediaway-sw, no OS dependency), unlike
+ * `DecodeSession`'s Windows-only WMF backend.
+ */
+export declare class AudioDecodeSession {
+    readonly sampleRate: number;
+    readonly channels: number;
+    private handle;
+    private constructor();
+    /** Open an Opus decode session. Throws DecoderUnavailableError when no
+     * decode backend exists on this machine. */
+    static open(sampleRate: number, channels: number, timeBase: Rational): Promise<AudioDecodeSession>;
+    /** Push one compressed Opus packet. An empty payload is Opus's
+     * packet-loss-concealment hint for a lost frame, not an error. May produce
+     * zero or more frames (drain via pollFrame()). */
+    pushPacket(packet: DecodePacket): Promise<void>;
+    /** Pull the next decoded PCM frame, if one is ready. null is a valid
+     * "nothing ready" result, not an error. */
+    pollFrame(): Promise<DecodedAudioFrame | null>;
+    /** Signal end of input; drain the remaining frames with pollFrame(). */
+    flush(): Promise<void>;
+    /** Always safe — no handle-consumption trap on this surface. */
+    close(): void;
+}

package/dist/decode.js

@@ -0,0 +1,165 @@
+/**
+ * @mediaway/encoder — pipeline capability: auto video decode + Opus audio decode.
+ *
+ * Wraps the mediaway-ffi C ABI's decode sessions (adr/0004-auto-decode-c-abi.md,
+ * adr/pipeline/0006-audio-decode-c-abi.md) — the same "C ABI real, no
+ * language binding wired" gap the container format series closed for
+ * mux/demux, closed here for decode. Both sessions mirror
+ * `openAutoEncoder()`/`AudioEncoder`'s single-step shape (the handle IS the
+ * decoder, no consumption trap); `NO_BACKEND` throws
+ * `DecoderUnavailableError`, an expected/graceful outcome.
+ */
+import { pipeline, copyBytes, } from "@mediaway/ffi";
+import { MediawayError } from "@mediaway/container";
+import { checkPipeline } from "./index.js";
+/** No decoder backend is openable for this config — expected on machines
+ * without a usable decoder; catch it and exit gracefully. */
+export class DecoderUnavailableError extends MediawayError {
+}
+const codecMap = { h264: 0, hevc: 1, av1: 2, vp9: 3 };
+const pixelFmtMap = { nv12: 0, i420: 1, bgra8: 2, rgba8: 3, yuy2: 4 };
+const pixelFmtRev = ["nv12", "i420", "bgra8", "rgba8", "yuy2"];
+/**
+ * The best available video decode session for a config — the handle IS the
+ * decoder (single-step open, no consumption trap, mirrors `openAutoEncoder`'s
+ * `NO_BACKEND` handling). CPU output only (GPU decode output is deferred,
+ * adr/0004 §1/§5).
+ */
+export class DecodeSession {
+    handle;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Open the best available video decoder for `config`. Throws
+     * DecoderUnavailableError when no decode backend exists on this machine. */
+    static async open(config) {
+        const extraData = config.extraData ?? Buffer.alloc(0);
+        const raw = pipeline.decodeConfigNew(codecMap[config.codec] ?? 0, config.width, config.height, { num: BigInt(config.timeBase.num), den: config.timeBase.den }, extraData.length > 0 ? extraData : null, extraData.length);
+        if (config.pixelFormat !== undefined)
+            raw.pixel_format = pixelFmtMap[config.pixelFormat] ?? 0;
+        const out = [null];
+        checkPipeline(pipeline.decodeSessionOpen(raw, out), DecoderUnavailableError);
+        if (!out[0])
+            throw new MediawayError(11, "decode session open returned no handle");
+        return new DecodeSession(out[0]);
+    }
+    /** Push one compressed packet. May produce zero or more frames (drain via
+     * `pollFrame()`). */
+    async pushPacket(packet) {
+        const raw = {
+            stream_id: 0,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.dts ?? packet.pts),
+            duration: BigInt(packet.duration ?? 0),
+            is_keyframe: packet.keyframe ?? false,
+            is_discard: false,
+            payload: packet.payload,
+            payload_len: packet.payload.length,
+        };
+        checkPipeline(pipeline.decodeSessionPushPacket(this.handle, raw));
+    }
+    /** Pull the next decoded frame, if one is ready. null is a valid "nothing
+     * ready" result, not an error. */
+    async pollFrame() {
+        const raw = {};
+        const has = [false];
+        checkPipeline(pipeline.decodeSessionPollFrame(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const data = copyBytes(raw.data, raw.data_len);
+        pipeline.decodedVideoFrameFree(raw);
+        return {
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            width: raw.width,
+            height: raw.height,
+            pixelFormat: pixelFmtRev[raw.pixel_format] ?? "nv12",
+            data,
+        };
+    }
+    /** Signal end of input; drain the remaining frames with pollFrame(). */
+    async flush() {
+        checkPipeline(pipeline.decodeSessionFlush(this.handle));
+    }
+    /** Always safe — no handle-consumption trap on this surface. */
+    close() {
+        if (this.handle) {
+            pipeline.decodeSessionClose(this.handle);
+            this.handle = null;
+        }
+    }
+}
+/**
+ * An Opus audio decode session — the handle IS the decoder (adr/pipeline/0006,
+ * mirrors `DecodeSession`'s video shape; no muxer to wire, no consumption
+ * trap). Cross-platform (mediaway-sw, no OS dependency), unlike
+ * `DecodeSession`'s Windows-only WMF backend.
+ */
+export class AudioDecodeSession {
+    sampleRate;
+    channels;
+    handle;
+    constructor(handle, sampleRate, channels) {
+        this.handle = handle;
+        this.sampleRate = sampleRate;
+        this.channels = channels;
+    }
+    /** Open an Opus decode session. Throws DecoderUnavailableError when no
+     * decode backend exists on this machine. */
+    static async open(sampleRate, channels, timeBase) {
+        const raw = pipeline.audioDecodeConfigOpus(sampleRate, channels, {
+            num: BigInt(timeBase.num),
+            den: timeBase.den,
+        });
+        const out = [null];
+        checkPipeline(pipeline.audioDecodeSessionOpen(raw, out), DecoderUnavailableError);
+        if (!out[0])
+            throw new MediawayError(11, "audio decode session open returned no handle");
+        return new AudioDecodeSession(out[0], sampleRate, channels);
+    }
+    /** Push one compressed Opus packet. An empty payload is Opus's
+     * packet-loss-concealment hint for a lost frame, not an error. May produce
+     * zero or more frames (drain via pollFrame()). */
+    async pushPacket(packet) {
+        const raw = {
+            stream_id: 0,
+            pts: BigInt(packet.pts),
+            dts: BigInt(packet.dts ?? packet.pts),
+            duration: BigInt(packet.duration ?? 0),
+            is_keyframe: packet.keyframe ?? false,
+            is_discard: false,
+            payload: packet.payload,
+            payload_len: packet.payload.length,
+        };
+        checkPipeline(pipeline.audioDecodeSessionPushPacket(this.handle, raw));
+    }
+    /** Pull the next decoded PCM frame, if one is ready. null is a valid
+     * "nothing ready" result, not an error. */
+    async pollFrame() {
+        const raw = {};
+        const has = [false];
+        checkPipeline(pipeline.audioDecodeSessionPollFrame(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const data = copyBytes(raw.data, raw.data_len);
+        pipeline.decodedAudioFrameFree(raw);
+        return {
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            sampleRate: raw.sample_rate,
+            channels: raw.channels,
+            data,
+        };
+    }
+    /** Signal end of input; drain the remaining frames with pollFrame(). */
+    async flush() {
+        checkPipeline(pipeline.audioDecodeSessionFlush(this.handle));
+    }
+    /** Always safe — no handle-consumption trap on this surface. */
+    close() {
+        if (this.handle) {
+            pipeline.audioDecodeSessionClose(this.handle);
+            this.handle = null;
+        }
+    }
+}

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export declare class AutoVideoEncodeConfig {
     static defaults(codec: VideoCodec, width: number, height: number, timeBase: Rational): AutoVideoEncodeConfig;
     toAbi(): RawRational;
 }
+export declare function checkPipeline(status: number, noBackendError?: new (status: number, message: string) => MediawayError): void;
 /**
  * A single-use encode session. `finish()` is terminal — it consumes the
  * session; `close()` after it is a no-op (idempotent), but is required to free
@@ -128,3 +129,4 @@ export declare class AudioEncoder {
     /** Always safe — no handle-consumption trap on this surface (adr/0003). */
     close(): void;
 }
+export * from "./decode.js";

package/dist/index.js

@@ -42,11 +42,11 @@ export class AutoVideoEncodeConfig {
         return raw;
     }
 }
-function checkPipeline(status) {
+export function checkPipeline(status, noBackendError = EncoderUnavailableError) {
     if (status === 0)
         return;
     if (status === 3)
-        throw new EncoderUnavailableError(status, "no encode backend compiled in or openable");
+        throw new noBackendError(status, "no backend compiled in or openable");
     const names = {
         1: "invalid argument",
         2: "handle poisoned by an earlier panic",
@@ -59,6 +59,8 @@ function checkPipeline(status) {
         10: "malformed container data",
         11: "unknown error",
         12: "internal panic (handle poisoned)",
+        13: "decoder backend OS/API failure",
+        14: "decode session already finished or not open",
     };
     throw new MediawayError(status, names[status] ?? "unknown pipeline error");
 }
@@ -224,3 +226,4 @@ export class AudioEncoder {
         }
     }
 }
+export * from "./decode.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediaway/encoder",
-  "version": "0.1.3",
-  "description": "Automatic hardware video encoding to fragmented MP4 for Node.js (NVENC / Vulkan Video / QuickSync)",
+  "version": "0.1.5",
+  "description": "Rust-based, lightweight, fast — automatic hardware video encoding to fragmented MP4 for Node.js (NVENC / Vulkan Video / QuickSync)",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,8 +26,8 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@mediaway/ffi": "0.1.0",
-    "@mediaway/container": "0.1.0"
+    "@mediaway/ffi": "^0.1.0",
+    "@mediaway/container": "^0.1.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0"