@mediaway/encoder 0.1.5 → 0.1.8

package/README.md

@@ -8,6 +8,34 @@ session you push frames into.
 Windows is the verified platform. Software fallbacks and other platforms are
 explicit follow-up work — see the [Mediaway roadmap](https://github.com/nyxways/mediaway).
 
+Video/audio **decode** moved to its own peer package, [`@mediaway/decoder`](../decoder)
+— it is not re-exported here anymore.
+
+## Capture-to-encode bridge
+
+`EncodeSession.writeFrameFromCameraCapture(capture)` /
+`.writeFrameFromDesktopCapture(capture)` poll a `CameraSession`/`ScreenSession`
+(`@mediaway/device`) and push straight into the session — no intermediate
+`VideoFrame`, no CPU copy for Screen's GPU frames:
+
+```ts
+import { AutoVideoEncodeConfig, openAutoEncoder } from "@mediaway/encoder";
+import { GpuDevice, openScreenCapture } from "@mediaway/device";
+
+const gpuDevice = await GpuDevice.create();
+const screen = await openScreenCapture({ timeBase: { num: 1, den: 30 }, gpuDevice });
+
+const config = AutoVideoEncodeConfig.defaults("h264", screen.width, screen.height, screen.timeBase);
+config.gpuDevice = gpuDevice; // Zero-Copy GPU input, same device as capture
+config.pixelFormat = "bgra8"; // DXGI Desktop Duplication's native format
+const session = await openAutoEncoder(config);
+
+while (recording) {
+  await session.writeFrameFromDesktopCapture(screen); // returns false if nothing was ready yet
+}
+const mp4 = await session.finish();
+```
+
 ## Install
 
 ```bash
@@ -57,8 +85,10 @@ const mp4 = await session.finish(); // terminal: complete fMP4 bytes
 | Member | Notes |
 | --- | --- |
 | `AutoVideoEncodeConfig.defaults(codec, width, height, timeBase)` | sensible defaults for the resolution; `codec` is `"h264" \| "hevc" \| "av1" \| "vp9"` |
+| `AutoVideoEncodeConfig.gpuDevice` | a `GpuDevice` (`@mediaway/device`) for Zero-Copy GPU input; pair with `pixelFormat: "bgra8"` for Screen |
 | `openAutoEncoder(config)` | resolves a hardware backend or throws `EncoderUnavailableError` |
 | `EncodeSession.writeFrame(frame)` | async; the frame is copied — reuse the buffer |
+| `EncodeSession.writeFrameFromCameraCapture(capture)` / `writeFrameFromDesktopCapture(capture)` | async; polls+pushes a capture session directly, `false` if nothing was ready |
 | `EncodeSession.finish()` | terminal; returns the complete fMP4 `Buffer` |
 
 ## License

package/dist/index.d.ts

@@ -9,6 +9,7 @@
  */
 import { type RawRational } from "@mediaway/ffi";
 import { MediawayError, type Rational } from "@mediaway/container";
+import { type CameraSession, type GpuDevice, type ScreenSession } from "@mediaway/device";
 export type { Rational } from "@mediaway/container";
 export { MediawayError } from "@mediaway/container";
 export type PixelFormat = "nv12" | "bgra8" | "rgba8" | "i420" | "yuy2";
@@ -33,8 +34,14 @@ export declare class AutoVideoEncodeConfig {
     timeBase: Rational;
     bitrateBps?: number;
     pixelFormat?: PixelFormat;
+    /** Zero-Copy GPU input: the same device a Screen capture session was opened
+     * with (or any `GpuDevice`) — set together with `pixelFormat: "bgra8"` for
+     * `writeFrameFromDesktopCapture()`'s GPU frames (DXGI delivers BGRA8, not
+     * the NV12 default). Leave unset for CPU input (Camera, or manual
+     * `writeFrame()` with CPU-storage frames). */
+    gpuDevice?: GpuDevice;
     private constructor();
-    /** The ABI's defaults (backend-default bitrate, NV12 input). */
+    /** The ABI's defaults (backend-default bitrate, NV12 input, CPU-only). */
     static defaults(codec: VideoCodec, width: number, height: number, timeBase: Rational): AutoVideoEncodeConfig;
     toAbi(): RawRational;
 }
@@ -53,6 +60,22 @@ export declare class EncodeSession {
     private finished;
     constructor(config: AutoVideoEncodeConfig, encoderHandle: unknown);
     writeFrame(frame: VideoFrame): Promise<void>;
+    /**
+     * Poll one frame from `capture` (a `CameraSession`, `@mediaway/device`) and
+     * push it straight into this session — no intermediate `VideoFrame`, no
+     * extra copy (`adr/pipeline/0005-capture-encode-bridge-c-abi.md`). Returns
+     * `false` when nothing was ready yet (not an error) — mirrors
+     * `CameraSession.pollFrame()`'s own null-vs-error shape.
+     */
+    writeFrameFromCameraCapture(capture: CameraSession): Promise<boolean>;
+    /**
+     * Same shape as `writeFrameFromCameraCapture`, for a `ScreenSession`
+     * (`@mediaway/device`) instead of Camera. GPU frames pass through
+     * Zero-Copy: the polled frame's GPU handle moves straight into the encoder
+     * with no CPU copy — this is the real way to consume Screen frames (see
+     * `ScreenSession.pollFrame()`'s own doc: it never copies pixels out).
+     */
+    writeFrameFromDesktopCapture(capture: ScreenSession): Promise<boolean>;
     /** Flush the encoder + muxer and return the complete fMP4 bytes. Terminal. */
     finish(): Promise<Buffer>;
     /** Idempotent; no-op after finish(). Frees the native handle on error paths. */
@@ -129,4 +152,3 @@ 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

@@ -9,6 +9,7 @@
  */
 import { MwAudioEncodeConfig, MwAudioFrameView, MwAudioPacket, MwAudioStreamInfo, MwPipelineFrame, MwRational, pipeline, copyBytes, } from "@mediaway/ffi";
 import { MediawayError } from "@mediaway/container";
+import { NATIVE_HANDLE } from "@mediaway/device";
 export { MediawayError } from "@mediaway/container";
 /** No encode backend is openable for this config — expected on machines
  * without a usable encoder; catch it and exit gracefully. */
@@ -21,13 +22,19 @@ export class AutoVideoEncodeConfig {
     timeBase;
     bitrateBps; // 0 / undefined = backend default
     pixelFormat;
+    /** Zero-Copy GPU input: the same device a Screen capture session was opened
+     * with (or any `GpuDevice`) — set together with `pixelFormat: "bgra8"` for
+     * `writeFrameFromDesktopCapture()`'s GPU frames (DXGI delivers BGRA8, not
+     * the NV12 default). Leave unset for CPU input (Camera, or manual
+     * `writeFrame()` with CPU-storage frames). */
+    gpuDevice;
     constructor(codec, width, height, timeBase) {
         this.codec = codec;
         this.width = width;
         this.height = height;
         this.timeBase = timeBase;
     }
-    /** The ABI's defaults (backend-default bitrate, NV12 input). */
+    /** The ABI's defaults (backend-default bitrate, NV12 input, CPU-only). */
     static defaults(codec, width, height, timeBase) {
         return new AutoVideoEncodeConfig(codec, width, height, timeBase);
     }
@@ -39,6 +46,8 @@ export class AutoVideoEncodeConfig {
         const fmtMap = { nv12: 0, i420: 1, bgra8: 2, rgba8: 3, yuy2: 4 };
         if (this.pixelFormat !== undefined)
             raw.pixel_format = fmtMap[this.pixelFormat] ?? 0;
+        if (this.gpuDevice !== undefined)
+            raw.gpu_device = this.gpuDevice[NATIVE_HANDLE]();
         return raw;
     }
 }
@@ -100,6 +109,30 @@ export class EncodeSession {
         };
         checkPipeline(pipeline.sessionWriteFrame(this.handle, raw));
     }
+    /**
+     * Poll one frame from `capture` (a `CameraSession`, `@mediaway/device`) and
+     * push it straight into this session — no intermediate `VideoFrame`, no
+     * extra copy (`adr/pipeline/0005-capture-encode-bridge-c-abi.md`). Returns
+     * `false` when nothing was ready yet (not an error) — mirrors
+     * `CameraSession.pollFrame()`'s own null-vs-error shape.
+     */
+    async writeFrameFromCameraCapture(capture) {
+        const wrote = [false];
+        checkPipeline(pipeline.sessionWriteFrameFromCameraCapture(this.handle, capture[NATIVE_HANDLE](), wrote));
+        return wrote[0];
+    }
+    /**
+     * Same shape as `writeFrameFromCameraCapture`, for a `ScreenSession`
+     * (`@mediaway/device`) instead of Camera. GPU frames pass through
+     * Zero-Copy: the polled frame's GPU handle moves straight into the encoder
+     * with no CPU copy — this is the real way to consume Screen frames (see
+     * `ScreenSession.pollFrame()`'s own doc: it never copies pixels out).
+     */
+    async writeFrameFromDesktopCapture(capture) {
+        const wrote = [false];
+        checkPipeline(pipeline.sessionWriteFrameFromDesktopCapture(this.handle, capture[NATIVE_HANDLE](), wrote));
+        return wrote[0];
+    }
     /** Flush the encoder + muxer and return the complete fMP4 bytes. Terminal. */
     async finish() {
         const outData = [null];
@@ -226,4 +259,3 @@ export class AudioEncoder {
         }
     }
 }
-export * from "./decode.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/encoder",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "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",
@@ -27,7 +27,8 @@
   },
   "dependencies": {
     "@mediaway/ffi": "^0.1.0",
-    "@mediaway/container": "^0.1.0"
+    "@mediaway/container": "^0.1.0",
+    "@mediaway/device": "^0.1.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0"

package/dist/decode.d.ts

@@ -1,106 +0,0 @@
-/**
- * @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

@@ -1,165 +0,0 @@
-/**
- * @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;
-        }
-    }
-}