@mediaway/encoder 0.1.4 → 0.1.6

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,11 +34,18 @@ 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;
 }
+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
@@ -52,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. */

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,14 +46,16 @@ 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;
     }
 }
-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 +68,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");
 }
@@ -98,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];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediaway/encoder",
-  "version": "0.1.4",
-  "description": "Automatic hardware video encoding to fragmented MP4 for Node.js (NVENC / Vulkan Video / QuickSync)",
+  "version": "0.1.6",
+  "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,9 @@
     "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",
+    "@mediaway/device": "^0.1.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0"