@mediaway/device 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @mediaway/device — device capability: camera / screen / microphone capture.
+ *
+ * Implements the DX contract in bindings/nodejs/README.md over the
+ * mediaway-ffi C ABI (via @mediaway/ffi). The ABI is domain-split
+ * (`adr/0004-domain-feature-split.md`): this package folds it back into the
+ * three DX functions. CPU-storage only: Camera delivers CPU frames; Screen
+ * capture raises CaptureUnavailableError from the C ABI today (it needs a
+ * live GPU device handle with no CPU fallback). Audio capture delivers raw
+ * interleaved f32le PCM — there is no audio encoder in the ABI.
+ */
+import { MediawayError, type Rational } from "@mediaway/container";
+export type { Rational } from "@mediaway/container";
+export interface VideoFrame {
+    pts: number;
+    duration: number;
+    width: number;
+    height: number;
+    pixelFormat: "nv12" | "bgra8";
+    data: Buffer;
+}
+export interface AudioFrame {
+    pts: number;
+    sampleRate: number;
+    channels: number;
+    data: Buffer;
+}
+/** No capture device/backend is available, or the ABI rejects this
+ * configuration as unsupported (today: Screen capture) — expected outcomes,
+ * not hard failures. */
+export declare class CaptureUnavailableError extends MediawayError {
+}
+/**
+ * A Camera capture session. Negotiated geometry/format are authoritative over
+ * the request — read them from the session properties.
+ */
+export declare class CameraSession {
+    readonly width: number;
+    readonly height: number;
+    readonly pixelFormat: "nv12";
+    readonly timeBase: Rational;
+    private handle;
+    /** Wrap a native camera capture handle. Prefer the openCamera() factory. */
+    constructor(handle: unknown, width: number, height: number, timeBase: Rational);
+    /** Poll the next frame; null when nothing is ready yet. Sync, never blocks. */
+    pollFrame(): VideoFrame | null;
+    /** Joins the backend worker thread — can block up to one frame interval. */
+    close(): Promise<void>;
+}
+/** Open camera `index` at `timeBase`; throws CaptureUnavailableError when no
+ * camera exists on this machine. */
+export declare function openCamera(options: {
+    index: number;
+    timeBase: Rational;
+}): Promise<CameraSession>;
+/** A Microphone capture session (raw interleaved f32le PCM). */
+export declare class MicSession {
+    readonly sampleRate: number;
+    readonly channels: number;
+    private handle;
+    /** Wrap a native mic capture handle. Prefer the openMicrophone() factory. */
+    constructor(handle: unknown, sampleRate: number, channels: number);
+    /** Poll the next PCM chunk; null when nothing is ready yet. */
+    pollFrame(): AudioFrame | null;
+    /** Joins the backend worker thread — can block up to one period interval. */
+    close(): Promise<void>;
+}
+/** Open the microphone at `sampleRate` Hz; throws CaptureUnavailableError
+ * when no mic/backend exists. */
+export declare function openMicrophone(options: {
+    sampleRate: number;
+    channels?: number;
+}): Promise<MicSession>;
+/**
+ * A Screen capture session — NOT available from the C ABI today. Screen needs
+ * a live GPU device handle (ID3D11Device*) with no CPU fallback, and its C
+ * representation is deferred (crates/mediaway-ffi/adr/0001 § Deferred),
+ * so openScreenCapture always throws CaptureUnavailableError. The ideal DX
+ * (BGRA8 CPU frames at the display's native geometry) is what the aspirational
+ * screen-record example targets.
+ */
+export declare class ScreenSession {
+    readonly width = 0;
+    readonly height = 0;
+    readonly pixelFormat: "bgra8";
+    readonly timeBase: Rational;
+    /** Screen session (always throws — no C-ABI screen path yet). */
+    constructor(timeBase: Rational);
+    pollFrame(): VideoFrame | null;
+    close(): Promise<void>;
+}
+export declare function openScreenCapture(options: {
+    timeBase: Rational;
+    monitorIndex?: number;
+}): Promise<ScreenSession>;

package/dist/index.js

@@ -0,0 +1,169 @@
+/**
+ * @mediaway/device — device capability: camera / screen / microphone capture.
+ *
+ * Implements the DX contract in bindings/nodejs/README.md over the
+ * mediaway-ffi C ABI (via @mediaway/ffi). The ABI is domain-split
+ * (`adr/0004-domain-feature-split.md`): this package folds it back into the
+ * three DX functions. CPU-storage only: Camera delivers CPU frames; Screen
+ * capture raises CaptureUnavailableError from the C ABI today (it needs a
+ * live GPU device handle with no CPU fallback). Audio capture delivers raw
+ * interleaved f32le PCM — there is no audio encoder in the ABI.
+ */
+import { MwAudioFrame, MwAudioConfig, MwCameraConfig, MwCameraFrame, device, copyBytes, } from "@mediaway/ffi";
+import { MediawayError } from "@mediaway/container";
+/** No capture device/backend is available, or the ABI rejects this
+ * configuration as unsupported (today: Screen capture) — expected outcomes,
+ * not hard failures. */
+export class CaptureUnavailableError extends MediawayError {
+}
+function checkDevice(status) {
+    if (status === 0)
+        return;
+    if (status === 4 || status === 6 || status === 8) {
+        throw new CaptureUnavailableError(status, "no capture backend or device available");
+    }
+    if (status === 3) {
+        throw new CaptureUnavailableError(status, "this capture configuration is unsupported by the ABI");
+    }
+    const names = {
+        1: "invalid argument",
+        2: "handle poisoned by an earlier panic",
+        5: "bad capture config",
+        7: "session already closed or not open",
+        9: "unknown error",
+        10: "internal panic (handle poisoned)",
+        11: "callback already registered",
+        12: "callback mode active (poll disabled)",
+        13: "timed out waiting for a frame",
+    };
+    throw new MediawayError(status, names[status] ?? "unknown device error");
+}
+// ── Camera ─────────────────────────────────────────────────────────────────────
+/**
+ * A Camera capture session. Negotiated geometry/format are authoritative over
+ * the request — read them from the session properties.
+ */
+export class CameraSession {
+    width;
+    height;
+    pixelFormat;
+    timeBase;
+    handle;
+    /** Wrap a native camera capture handle. Prefer the openCamera() factory. */
+    constructor(handle, width, height, timeBase) {
+        this.handle = handle;
+        this.width = width;
+        this.height = height;
+        this.pixelFormat = "nv12";
+        this.timeBase = timeBase;
+    }
+    /** Poll the next frame; null when nothing is ready yet. Sync, never blocks. */
+    pollFrame() {
+        const raw = {};
+        const has = [false];
+        checkDevice(device.cameraPollFrame(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const data = copyBytes(raw.data, raw.data_len);
+        device.cameraFrameFree(raw);
+        return {
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            width: raw.width,
+            height: raw.height,
+            pixelFormat: "nv12",
+            data,
+        };
+    }
+    /** Joins the backend worker thread — can block up to one frame interval. */
+    async close() {
+        if (this.handle) {
+            checkDevice(device.cameraClose(this.handle));
+            this.handle = null;
+        }
+    }
+}
+/** Open camera `index` at `timeBase`; throws CaptureUnavailableError when no
+ * camera exists on this machine. */
+export async function openCamera(options) {
+    const config = device.cameraConfigDefault(options.index, { num: BigInt(options.timeBase.num), den: options.timeBase.den });
+    const out = [null];
+    checkDevice(device.cameraOpen(config, out));
+    if (!out[0])
+        throw new MediawayError(9, "capture open returned no handle");
+    const width = [0];
+    const height = [0];
+    checkDevice(device.cameraGeometry(out[0], width, height));
+    return new CameraSession(out[0], width[0], height[0], options.timeBase);
+}
+// ── Microphone ─────────────────────────────────────────────────────────────────
+/** A Microphone capture session (raw interleaved f32le PCM). */
+export class MicSession {
+    sampleRate;
+    channels;
+    handle;
+    /** Wrap a native mic capture handle. Prefer the openMicrophone() factory. */
+    constructor(handle, sampleRate, channels) {
+        this.handle = handle;
+        this.sampleRate = sampleRate;
+        this.channels = channels;
+    }
+    /** Poll the next PCM chunk; null when nothing is ready yet. */
+    pollFrame() {
+        const raw = {};
+        const has = [false];
+        checkDevice(device.audioPollFrame(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        const data = copyBytes(raw.data, raw.data_len);
+        device.audioFrameFree(raw);
+        return { pts: Number(raw.pts), sampleRate: raw.sample_rate, channels: raw.channels, data };
+    }
+    /** Joins the backend worker thread — can block up to one period interval. */
+    async close() {
+        if (this.handle) {
+            checkDevice(device.audioClose(this.handle));
+            this.handle = null;
+        }
+    }
+}
+/** Open the microphone at `sampleRate` Hz; throws CaptureUnavailableError
+ * when no mic/backend exists. */
+export async function openMicrophone(options) {
+    const config = device.audioConfigMicrophone({ num: 1n, den: options.sampleRate });
+    const out = [null];
+    checkDevice(device.audioOpen(config, out));
+    if (!out[0])
+        throw new MediawayError(9, "capture open returned no handle");
+    const rate = [0];
+    const channels = [0];
+    checkDevice(device.audioFormat(out[0], rate, channels));
+    return new MicSession(out[0], rate[0], channels[0]);
+}
+// ── Screen (ideal only) ────────────────────────────────────────────────────────
+/**
+ * A Screen capture session — NOT available from the C ABI today. Screen needs
+ * a live GPU device handle (ID3D11Device*) with no CPU fallback, and its C
+ * representation is deferred (crates/mediaway-ffi/adr/0001 § Deferred),
+ * so openScreenCapture always throws CaptureUnavailableError. The ideal DX
+ * (BGRA8 CPU frames at the display's native geometry) is what the aspirational
+ * screen-record example targets.
+ */
+export class ScreenSession {
+    width = 0;
+    height = 0;
+    pixelFormat = "bgra8";
+    timeBase;
+    /** Screen session (always throws — no C-ABI screen path yet). */
+    constructor(timeBase) {
+        this.timeBase = timeBase;
+    }
+    pollFrame() {
+        throw new CaptureUnavailableError(3, "Screen capture is not available from this binding today");
+    }
+    async close() { }
+}
+export async function openScreenCapture(options) {
+    void options;
+    throw new CaptureUnavailableError(3, "Screen capture needs a live GPU device handle with no CPU fallback, and its C representation is deferred — not available from this binding today");
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mediaway/device",
+  "version": "0.1.0",
+  "description": "Mediaway camera/mic/screen capture over the C ABI (mediaway-ffi)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nyxways/mediaway.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@mediaway/ffi": "0.1.0",
+    "@mediaway/container": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}