@mediaway/encoder 0.1.6 → 0.2.1

package/README.md

@@ -80,6 +80,35 @@ const mp4 = await session.finish(); // terminal: complete fMP4 bytes
 // -> write `mp4` to a file / stream
 ```
 
+## Streaming a long recording
+
+`finish()` alone holds the whole recording in RAM. Call `pollBytes()` as you go and append each
+chunk to a file: memory is then bounded by the poll cadence, not the recording's length.
+`finish()` afterwards returns only the tail that was not polled yet.
+
+```ts
+const out = openSync("recording.mp4", "w");
+for (let i = 0; i < frames; i++) {
+  await session.writeFrame(frame(i));
+  writeSync(out, await session.pollBytes()); // empty buffer when nothing is ready
+}
+writeSync(out, await session.finish()); // the tail — concatenated, the file is complete
+```
+
+## Probing backends
+
+`encoderSupport(codec, width, height)` reports every backend's availability **at the size you will
+encode** — hardware encoders have minimum and maximum dimensions, so there is no resolution-free
+form. Each row is `{ backend, state, pathClass }` (`pathClass` is `null` unless `state` is
+`"supported"`). **It is costly**: it opens a throwaway session per backend, so call it when a
+settings screen opens, never per frame.
+
+```ts
+for (const row of await encoderSupport("h264", 1920, 1080)) {
+  console.log(row.backend, row.state, row.pathClass); // "nvenc" "supported" "cpu-upload"
+}
+```
+
 ## API
 
 | Member | Notes |
@@ -89,7 +118,9 @@ const mp4 = await session.finish(); // terminal: complete fMP4 bytes
 | `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` |
+| `EncodeSession.pollBytes()` | async; the fMP4 bytes ready now (empty `Buffer` when none) — the streaming exit; never ends the session |
+| `EncodeSession.finish()` | terminal; returns the fMP4 `Buffer` **not yet taken by `pollBytes()`** — the whole file if never polled, only the tail if it was |
+| `encoderSupport(codec, width, height)` | async, **costly**; per-backend `{ backend, state, pathClass }` at that resolution |
 
 ## License
 

package/dist/index.d.ts

@@ -9,7 +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";
+import { type CameraSession, type DesktopCaptureSession, type GpuDevice } from "@mediaway/device";
 export type { Rational } from "@mediaway/container";
 export { MediawayError } from "@mediaway/container";
 export type PixelFormat = "nv12" | "bgra8" | "rgba8" | "i420" | "yuy2";
@@ -69,14 +69,29 @@ export declare class EncodeSession {
      */
     writeFrameFromCameraCapture(capture: CameraSession): Promise<boolean>;
     /**
-     * Same shape as `writeFrameFromCameraCapture`, for a `ScreenSession`
+     * Same shape as `writeFrameFromCameraCapture`, for a `ScreenSession` or `WindowSession`
      * (`@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. */
+    writeFrameFromDesktopCapture(capture: DesktopCaptureSession): Promise<boolean>;
+    /**
+     * Take the fMP4 bytes that are ready now, without ending the session — the streaming exit
+     * (`adr/pipeline/0007` §1). Call it as often as you like (after every `writeFrame`, on a timer,
+     * or never) and the session's memory stays bounded by the poll cadence instead of growing with
+     * the recording: a long capture polled into a file holds a fragment, not the whole file.
+     *
+     * Resolves to an empty buffer when nothing is ready, which is indistinguishable from "already
+     * drained" — track your own running total if you need the difference. Polling never finishes
+     * the stream: the last fragments only appear in `finish()`'s result.
+     */
+    pollBytes(): Promise<Buffer>;
+    /**
+     * Flush the encoder + muxer and return the fMP4 bytes **not yet taken by `pollBytes()`**:
+     * the complete file for a session that was never polled, only its tail for one that was.
+     * A streaming caller appends this to what it already wrote. Terminal.
+     */
     finish(): Promise<Buffer>;
     /** Idempotent; no-op after finish(). Frees the native handle on error paths. */
     close(): void;
@@ -84,6 +99,37 @@ export declare class EncodeSession {
 /** Pick the best available encoder for `config` and open a session on it.
  * Throws EncoderUnavailableError when no backend exists on this machine. */
 export declare function openAutoEncoder(config: AutoVideoEncodeConfig): Promise<EncodeSession>;
+/** A codec the encoder probe accepts. */
+export type ProbeCodec = VideoCodec | "aac" | "opus";
+/** Which encode backend a probe row describes. */
+export type EncodeBackend = "os" | "nvenc" | "quicksync" | "amf" | "vulkan" | "software" | "unknown";
+/** Whether a backend or codec is usable right now. */
+export type SupportState = "supported" | "not-implemented" | "no-device" | "unknown";
+/** The cheapest data path a supported encoder reached. */
+export type EncodePathClass = "zero-copy" | "gpu-copy" | "cpu-upload" | "readback" | "software" | "unknown";
+/** One backend row of `encoderSupport()`. */
+export interface EncoderCapability {
+    backend: EncodeBackend;
+    state: SupportState;
+    /** The data path cost — `null` unless `state === "supported"`. */
+    pathClass: EncodePathClass | null;
+}
+/** Map a `mediaway_support_state_t` value to its name (shared with `@mediaway/decoder`). */
+export declare function supportStateName(state: number): SupportState;
+/**
+ * Probe every encode backend for `codec` **at `width` x `height`**.
+ *
+ * Encoder support is resolution-dependent — a hardware encoder has minimum and maximum
+ * dimensions, so a backend that works at one size says nothing about another — which is why there
+ * is deliberately no resolution-free form. Pass the size you will encode.
+ *
+ * **Costly:** it opens a throwaway session per backend (a real MFT / VA-API / VideoToolbox
+ * session each). Call it when a settings screen opens, never per frame or in a loop. A platform
+ * with no per-backend selection reports an empty list.
+ *
+ * @throws MediawayError status 5 for a zero width or height.
+ */
+export declare function encoderSupport(codec: ProbeCodec, width: number, height: number): Promise<EncoderCapability[]>;
 export type AudioCodec = "aac";
 export type SampleFormat = "s16" | "s32" | "f32";
 export interface AudioEncodeConfig {

package/dist/index.js

@@ -7,7 +7,7 @@
  * `EncodeSession` directly; `finish()` is terminal. Video only — there is no
  * audio encoder in the ABI.
  */
-import { MwAudioEncodeConfig, MwAudioFrameView, MwAudioPacket, MwAudioStreamInfo, MwPipelineFrame, MwRational, pipeline, copyBytes, } from "@mediaway/ffi";
+import { MwAudioEncodeConfig, MwAudioFrameView, MwAudioPacket, MwAudioStreamInfo, MwEncoderCapability, MwPipelineFrame, MwRational, PIPELINE_CODEC, pipeline, copyBytes, decodeArray, } from "@mediaway/ffi";
 import { MediawayError } from "@mediaway/container";
 import { NATIVE_HANDLE } from "@mediaway/device";
 export { MediawayError } from "@mediaway/container";
@@ -122,7 +122,7 @@ export class EncodeSession {
         return wrote[0];
     }
     /**
-     * Same shape as `writeFrameFromCameraCapture`, for a `ScreenSession`
+     * Same shape as `writeFrameFromCameraCapture`, for a `ScreenSession` or `WindowSession`
      * (`@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
@@ -133,7 +133,33 @@ export class EncodeSession {
         checkPipeline(pipeline.sessionWriteFrameFromDesktopCapture(this.handle, capture[NATIVE_HANDLE](), wrote));
         return wrote[0];
     }
-    /** Flush the encoder + muxer and return the complete fMP4 bytes. Terminal. */
+    /**
+     * Take the fMP4 bytes that are ready now, without ending the session — the streaming exit
+     * (`adr/pipeline/0007` §1). Call it as often as you like (after every `writeFrame`, on a timer,
+     * or never) and the session's memory stays bounded by the poll cadence instead of growing with
+     * the recording: a long capture polled into a file holds a fragment, not the whole file.
+     *
+     * Resolves to an empty buffer when nothing is ready, which is indistinguishable from "already
+     * drained" — track your own running total if you need the difference. Polling never finishes
+     * the stream: the last fragments only appear in `finish()`'s result.
+     */
+    async pollBytes() {
+        if (!this.handle)
+            throw new MediawayError(7, "session already finished or not open");
+        const outData = [null];
+        const outLen = [0];
+        checkPipeline(pipeline.sessionPollBytes(this.handle, outData, outLen));
+        if (outLen[0] === 0)
+            return Buffer.alloc(0);
+        const data = copyBytes(outData[0], outLen[0]);
+        pipeline.bufferFree(outData[0], outLen[0]);
+        return data;
+    }
+    /**
+     * Flush the encoder + muxer and return the fMP4 bytes **not yet taken by `pollBytes()`**:
+     * the complete file for a session that was never polled, only its tail for one that was.
+     * A streaming caller appends this to what it already wrote. Terminal.
+     */
     async finish() {
         const outData = [null];
         const outLen = [0];
@@ -166,6 +192,59 @@ export async function openAutoEncoder(config) {
         throw new MediawayError(11, "encoder open returned no handle");
     return new EncodeSession(config, outEncoder[0]);
 }
+const BACKENDS = {
+    0: "os",
+    1: "nvenc",
+    2: "quicksync",
+    3: "amf",
+    4: "vulkan",
+    5: "software",
+};
+const PATH_CLASSES = {
+    1: "zero-copy",
+    2: "gpu-copy",
+    3: "cpu-upload",
+    4: "readback",
+    5: "software",
+};
+const SUPPORT_STATES = {
+    0: "supported",
+    1: "not-implemented",
+    2: "no-device",
+};
+/** Map a `mediaway_support_state_t` value to its name (shared with `@mediaway/decoder`). */
+export function supportStateName(state) {
+    return SUPPORT_STATES[state] ?? "unknown";
+}
+/**
+ * Probe every encode backend for `codec` **at `width` x `height`**.
+ *
+ * Encoder support is resolution-dependent — a hardware encoder has minimum and maximum
+ * dimensions, so a backend that works at one size says nothing about another — which is why there
+ * is deliberately no resolution-free form. Pass the size you will encode.
+ *
+ * **Costly:** it opens a throwaway session per backend (a real MFT / VA-API / VideoToolbox
+ * session each). Call it when a settings screen opens, never per frame or in a loop. A platform
+ * with no per-backend selection reports an empty list.
+ *
+ * @throws MediawayError status 5 for a zero width or height.
+ */
+export async function encoderSupport(codec, width, height) {
+    const outRows = [null];
+    const outCount = [0];
+    checkPipeline(pipeline.encoderSupportAt(PIPELINE_CODEC[codec], width, height, outRows, outCount));
+    const count = outCount[0];
+    if (count === 0)
+        return [];
+    const rows = decodeArray(outRows[0], MwEncoderCapability, count);
+    const result = rows.map((row) => ({
+        backend: BACKENDS[row.backend] ?? "unknown",
+        state: supportStateName(row.state),
+        pathClass: row.state === 0 ? (PATH_CLASSES[row.path_class] ?? "unknown") : null,
+    }));
+    pipeline.encoderSupportFree(outRows[0], count);
+    return result;
+}
 /**
  * An opened auto audio encoder — the session IS the encoder (ABI v2,
  * adr/0003): single-step open, no intermediate handle, no consumption trap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/encoder",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "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",