@mediaway/device 0.1.6 → 0.2.1

package/README.md

@@ -75,6 +75,35 @@ readback path for Screen). For real pixel data, feed the session straight
 into an encoder with `EncodeSession.writeFrameFromDesktopCapture()`
 (`@mediaway/encoder`), Zero-Copy end to end — see that package's README.
 
+## Window capture
+
+One window by `HWND` (Windows, WGC) — GPU-only and Zero-Copy exactly like Screen, and
+`pollFrame()`'s `data` is likewise always empty (`mediaway-ffi` ADR-0005). `WindowSession` also
+feeds `EncodeSession.writeFrameFromDesktopCapture()`.
+
+```ts
+import { openWindowCapture } from "@mediaway/device";
+
+const win = await openWindowCapture({
+  hwnd,                          // bigint | number, caller-owned; 0 is rejected
+  timeBase: { num: 1, den: 30 },
+  cursor: "included",            // default "excluded"
+  border: "hidden",              // default "shown"; Windows 11 build 22000+
+  dimensions: "even-cropped",    // default "native"; any hardware encoder accepts even frames
+  region: { x: 0, y: 0, width: 640, height: 360 }, // optional
+});
+console.log(win.width, win.height, win.borderHidden);
+await win.close();
+```
+
+- `borderHidden` reports what Windows *did*: a refusal is not an error, so check it after
+  asking for `border: "hidden"`.
+- A `region` at the window's origin is free; one anywhere else costs one GPU copy per frame
+  (not Zero-Copy). A window that is or becomes smaller than the region throws
+  `RegionOutOfBoundsError` — distinct from the bad-config error, so it can be retried with a
+  smaller region.
+- Off Windows, `CaptureUnavailableError`.
+
 ## GPU device factory
 
 ```ts
@@ -100,6 +129,7 @@ adapter DXGI reports.
 | `openCamera({ index, timeBase })` | `CameraSession` (`width`, `height`, `pixelFormat` = `"nv12"`) | `pollFrame(): VideoFrame \| null` |
 | `openMicrophone({ sampleRate, channels })` | `MicSession` (`sampleRate`, `channels`) | `pollFrame(): AudioFrame \| null` |
 | `openScreenCapture({ timeBase, monitorIndex?, gpuDevice? })` | `ScreenSession` | `pollFrame(): VideoFrame \| null` (`data` always empty) |
+| `openWindowCapture({ hwnd, timeBase, gpuDevice?, cursor?, border?, dimensions?, region? })` | `WindowSession` (`ScreenSession`'s fields + `borderHidden`) | `pollFrame(): VideoFrame \| null` (`data` always empty) |
 | `listGpuAdapters()` | — | `GpuAdapterInfo[]` |
 | `GpuDevice.create({ adapterIndex?, videoSupport?, debugLayer? })` | `GpuDevice` | — |
 

package/dist/index.d.ts

@@ -42,6 +42,16 @@ export interface AudioFrame {
  * not hard failures. */
 export declare class CaptureUnavailableError extends MediawayError {
 }
+/** A window capture region does not fit the captured window — at open, or because the
+ * window later shrank. A runtime condition a caller can retry with a smaller region,
+ * so it is distinct from the bad-config error (`status` 5). */
+export declare class RegionOutOfBoundsError extends MediawayError {
+}
+/**
+ * @internal The error a non-zero device status maps to, or `undefined` for `0`. Exported
+ * only so the status mapping is testable without provoking every native failure.
+ */
+export declare function deviceStatusError(status: number): MediawayError | undefined;
 /**
  * A Camera capture session. Negotiated geometry/format are authoritative over
  * the request — read them from the session properties.
@@ -130,26 +140,20 @@ export declare class GpuDevice {
     [NATIVE_HANDLE](): RawGpuDeviceHandle;
 }
 /**
- * A Screen capture session — GPU-only, Zero-Copy (`adr/0003-gpu-handle-c-abi.md`
- * §4: no CPU fallback exists in the wrapped Rust backend, so unlike Camera
- * there is no CPU pixel readback path here either). `pollFrame()` proves
- * frames are genuinely arriving (real `pts`/geometry) but its `VideoFrame.data`
- * is always empty — it does not copy pixels out. For real pixel data, feed
- * the session straight into the encoder with
- * `EncodeSession.writeFrameFromDesktopCapture()` (`@mediaway/encoder`), which
- * moves the GPU texture Zero-Copy with no CPU round trip at all.
+ * State and behaviour shared by Screen and Window capture sessions: both are the same
+ * `mediaway_desktop_capture_t*` handle, GPU-only and Zero-Copy.
  */
-export declare class ScreenSession {
+export declare abstract class DesktopSession {
     readonly width: number;
     readonly height: number;
     readonly pixelFormat: "bgra8";
     readonly timeBase: Rational;
     private handle;
     private readonly ownsGpuDevice;
-    /** Wrap a native desktop capture handle. Prefer the openScreenCapture() factory. */
+    /** @internal Wrap a native desktop capture handle. Use the open*Capture() factories. */
     constructor(handle: unknown, width: number, height: number, timeBase: Rational, ownsGpuDevice: GpuDevice | undefined);
     /** Poll the next frame; null when nothing is ready yet. Sync, never blocks.
-     * `data` is always empty — see the class doc. */
+     * `data` is always empty — see the `ScreenSession` class doc. */
     pollFrame(): VideoFrame | null;
     /** Joins the backend worker thread — can block up to one frame interval.
      * Also closes the GPU device this session created internally (auto mode);
@@ -159,6 +163,20 @@ export declare class ScreenSession {
     /** @internal */
     [NATIVE_HANDLE](): unknown;
 }
+/** Either kind of desktop capture session — what `EncodeSession.writeFrameFromDesktopCapture` takes. */
+export type DesktopCaptureSession = ScreenSession | WindowSession;
+/**
+ * A Screen capture session — GPU-only, Zero-Copy (`adr/0003-gpu-handle-c-abi.md`
+ * §4: no CPU fallback exists in the wrapped Rust backend, so unlike Camera
+ * there is no CPU pixel readback path here either). `pollFrame()` proves
+ * frames are genuinely arriving (real `pts`/geometry) but its `VideoFrame.data`
+ * is always empty — it does not copy pixels out. For real pixel data, feed
+ * the session straight into the encoder with
+ * `EncodeSession.writeFrameFromDesktopCapture()` (`@mediaway/encoder`), which
+ * moves the GPU texture Zero-Copy with no CPU round trip at all.
+ */
+export declare class ScreenSession extends DesktopSession {
+}
 /**
  * Open Screen capture for output `monitorIndex` (default the primary
  * display). Creates a `GpuDevice` internally unless `options.gpuDevice` is
@@ -172,3 +190,48 @@ export declare function openScreenCapture(options: {
     monitorIndex?: number;
     gpuDevice?: GpuDevice;
 }): Promise<ScreenSession>;
+/** A rectangle of the captured window to record instead of all of it, in window pixels. */
+export interface CaptureRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface WindowCaptureOptions {
+    /** The window to capture, as its `HWND` bits. Caller-owned: the session does not
+     * extend its lifetime. `0` is rejected as a bad config (`status` 5). */
+    hwnd: bigint | number;
+    timeBase: Rational;
+    /** Share a device with an encoder, or pick an adapter; omitted, one is created and
+     * closed with the session (same rule as `openScreenCapture`). */
+    gpuDevice?: GpuDevice;
+    /** Draw the mouse pointer into frames. Default `"excluded"`. */
+    cursor?: "excluded" | "included";
+    /** Ask Windows 11 (build 22000+) not to draw the capture border. Default `"shown"`.
+     * A refusal is not an error — read `WindowSession.borderHidden` for what happened. */
+    border?: "shown" | "hidden";
+    /** `"even-cropped"` drops an odd axis's last column/row so any hardware encoder
+     * accepts the frames; free on WGC. Default `"native"`. */
+    dimensions?: "native" | "even-cropped";
+    /** Record only this rectangle. A region at the window's origin is free; one anywhere
+     * else costs one GPU copy per frame (not Zero-Copy). A window that shrinks below it
+     * throws `RegionOutOfBoundsError`. */
+    region?: CaptureRegion;
+}
+/**
+ * A Window capture session (Windows, WGC) — GPU-only, Zero-Copy, exactly like
+ * `ScreenSession`; see its doc for why `pollFrame()` returns no pixel data.
+ */
+export declare class WindowSession extends DesktopSession {
+    /** Whether Windows actually hid the capture border. Meaningful with
+     * `border: "hidden"`; `false` otherwise, and on builds before Windows 11 22000. */
+    readonly borderHidden: boolean;
+    /** @internal Use openWindowCapture(). */
+    constructor(handle: unknown, width: number, height: number, timeBase: Rational, ownsGpuDevice: GpuDevice | undefined, borderHidden: boolean);
+}
+/**
+ * Open Window capture for `options.hwnd`. Creates a `GpuDevice` internally unless
+ * `options.gpuDevice` is supplied. Throws `CaptureUnavailableError` off Windows or with
+ * no usable GPU, `RegionOutOfBoundsError` when the region does not fit the window.
+ */
+export declare function openWindowCapture(options: WindowCaptureOptions): Promise<WindowSession>;

package/dist/index.js

@@ -27,14 +27,26 @@ export const NATIVE_HANDLE = Symbol("mediaway.device.nativeHandle");
  * not hard failures. */
 export class CaptureUnavailableError extends MediawayError {
 }
-function checkDevice(status) {
+/** A window capture region does not fit the captured window — at open, or because the
+ * window later shrank. A runtime condition a caller can retry with a smaller region,
+ * so it is distinct from the bad-config error (`status` 5). */
+export class RegionOutOfBoundsError extends MediawayError {
+}
+/**
+ * @internal The error a non-zero device status maps to, or `undefined` for `0`. Exported
+ * only so the status mapping is testable without provoking every native failure.
+ */
+export function deviceStatusError(status) {
     if (status === 0)
-        return;
+        return undefined;
+    if (status === 14) {
+        return new RegionOutOfBoundsError(status, "capture region does not fit the window");
+    }
     if (status === 4 || status === 6 || status === 8) {
-        throw new CaptureUnavailableError(status, "no capture backend or device available");
+        return new CaptureUnavailableError(status, "no capture backend or device available");
     }
     if (status === 3) {
-        throw new CaptureUnavailableError(status, "this capture configuration is unsupported by the ABI");
+        return new CaptureUnavailableError(status, "this capture configuration is unsupported by the ABI");
     }
     const names = {
         1: "invalid argument",
@@ -47,7 +59,12 @@ function checkDevice(status) {
         12: "callback mode active (poll disabled)",
         13: "timed out waiting for a frame",
     };
-    throw new MediawayError(status, names[status] ?? "unknown device error");
+    return new MediawayError(status, names[status] ?? "unknown device error");
+}
+function checkDevice(status) {
+    const err = deviceStatusError(status);
+    if (err !== undefined)
+        throw err;
 }
 // ── Camera ─────────────────────────────────────────────────────────────────────
 /**
@@ -222,25 +239,19 @@ export class GpuDevice {
         return out;
     }
 }
-// ── Screen ───────────────────────────────────────────────────────────────────
+// ── Desktop capture (Screen + Window) ────────────────────────────────────────
 /**
- * A Screen capture session — GPU-only, Zero-Copy (`adr/0003-gpu-handle-c-abi.md`
- * §4: no CPU fallback exists in the wrapped Rust backend, so unlike Camera
- * there is no CPU pixel readback path here either). `pollFrame()` proves
- * frames are genuinely arriving (real `pts`/geometry) but its `VideoFrame.data`
- * is always empty — it does not copy pixels out. For real pixel data, feed
- * the session straight into the encoder with
- * `EncodeSession.writeFrameFromDesktopCapture()` (`@mediaway/encoder`), which
- * moves the GPU texture Zero-Copy with no CPU round trip at all.
+ * State and behaviour shared by Screen and Window capture sessions: both are the same
+ * `mediaway_desktop_capture_t*` handle, GPU-only and Zero-Copy.
  */
-export class ScreenSession {
+export class DesktopSession {
     width;
     height;
     pixelFormat = "bgra8";
     timeBase;
     handle;
     ownsGpuDevice;
-    /** Wrap a native desktop capture handle. Prefer the openScreenCapture() factory. */
+    /** @internal Wrap a native desktop capture handle. Use the open*Capture() factories. */
     constructor(handle, width, height, timeBase, ownsGpuDevice) {
         this.handle = handle;
         this.width = width;
@@ -249,17 +260,17 @@ export class ScreenSession {
         this.ownsGpuDevice = ownsGpuDevice;
     }
     /** Poll the next frame; null when nothing is ready yet. Sync, never blocks.
-     * `data` is always empty — see the class doc. */
+     * `data` is always empty — see the `ScreenSession` class doc. */
     pollFrame() {
         const raw = {};
         const has = [false];
         checkDevice(device.desktopPollFrame(this.handle, raw, has));
         if (!has[0])
             return null;
-        // storage_kind is always GPU (1) for Screen — the frame lives in
-        // gpu_buffer, a BORROWED handle released below (never freed via
-        // desktopFrameFree, which would double-release it; there is nothing to
-        // copy out of raw.data/data_len, which stay empty for GPU storage).
+        // storage_kind is always GPU (1) — the frame lives in gpu_buffer, a BORROWED
+        // handle released below (never freed via desktopFrameFree, which would
+        // double-release it; there is nothing to copy out of raw.data/data_len, which
+        // stay empty for GPU storage).
         checkDevice(device.desktopReleaseFrame(this.handle));
         return {
             pts: Number(raw.pts),
@@ -286,6 +297,18 @@ export class ScreenSession {
         return this.handle;
     }
 }
+/**
+ * A Screen capture session — GPU-only, Zero-Copy (`adr/0003-gpu-handle-c-abi.md`
+ * §4: no CPU fallback exists in the wrapped Rust backend, so unlike Camera
+ * there is no CPU pixel readback path here either). `pollFrame()` proves
+ * frames are genuinely arriving (real `pts`/geometry) but its `VideoFrame.data`
+ * is always empty — it does not copy pixels out. For real pixel data, feed
+ * the session straight into the encoder with
+ * `EncodeSession.writeFrameFromDesktopCapture()` (`@mediaway/encoder`), which
+ * moves the GPU texture Zero-Copy with no CPU round trip at all.
+ */
+export class ScreenSession extends DesktopSession {
+}
 /**
  * Open Screen capture for output `monitorIndex` (default the primary
  * display). Creates a `GpuDevice` internally unless `options.gpuDevice` is
@@ -315,3 +338,55 @@ export async function openScreenCapture(options) {
         throw err;
     }
 }
+/**
+ * A Window capture session (Windows, WGC) — GPU-only, Zero-Copy, exactly like
+ * `ScreenSession`; see its doc for why `pollFrame()` returns no pixel data.
+ */
+export class WindowSession extends DesktopSession {
+    /** Whether Windows actually hid the capture border. Meaningful with
+     * `border: "hidden"`; `false` otherwise, and on builds before Windows 11 22000. */
+    borderHidden;
+    /** @internal Use openWindowCapture(). */
+    constructor(handle, width, height, timeBase, ownsGpuDevice, borderHidden) {
+        super(handle, width, height, timeBase, ownsGpuDevice);
+        this.borderHidden = borderHidden;
+    }
+}
+/**
+ * Open Window capture for `options.hwnd`. Creates a `GpuDevice` internally unless
+ * `options.gpuDevice` is supplied. Throws `CaptureUnavailableError` off Windows or with
+ * no usable GPU, `RegionOutOfBoundsError` when the region does not fit the window.
+ */
+export async function openWindowCapture(options) {
+    const ownsGpuDevice = options.gpuDevice === undefined ? await GpuDevice.create() : undefined;
+    const gpuDevice = options.gpuDevice ?? ownsGpuDevice;
+    if (gpuDevice === undefined)
+        throw new MediawayError(9, "no GPU device available");
+    try {
+        const config = device.desktopConfigWindow(BigInt(options.hwnd), { num: BigInt(options.timeBase.num), den: options.timeBase.den }, gpuDevice[NATIVE_HANDLE]());
+        config.cursor = options.cursor === "included" ? 1 : 0;
+        config.border = options.border === "hidden" ? 1 : 0;
+        config.dimensions = options.dimensions === "even-cropped" ? 1 : 0;
+        if (options.region !== undefined) {
+            config.region_enabled = true;
+            config.region_x = options.region.x;
+            config.region_y = options.region.y;
+            config.region_width = options.region.width;
+            config.region_height = options.region.height;
+        }
+        const out = [null];
+        checkDevice(device.desktopOpen(config, out));
+        if (!out[0])
+            throw new MediawayError(9, "capture open returned no handle");
+        const width = [0];
+        const height = [0];
+        checkDevice(device.desktopGeometry(out[0], width, height));
+        const hidden = [false];
+        checkDevice(device.desktopBorderHidden(out[0], hidden));
+        return new WindowSession(out[0], width[0], height[0], options.timeBase, ownsGpuDevice, hidden[0]);
+    }
+    catch (err) {
+        ownsGpuDevice?.close();
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/device",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Rust-based, lightweight, fast — camera, microphone, and screen capture for Node.js (poll-based, never blocks)",
   "type": "module",
   "main": "./dist/index.js",