obsbot-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Jordan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# obsbot-mcp
+
+A cross-platform [Model Context Protocol](https://modelcontextprotocol.io) server that controls an
+**OBSBOT Tiny 2** camera over its standard UVC/USB interface — pan/tilt/roll the gimbal, zoom, AI
+subject tracking, focus/exposure/white-balance/image controls, HDR and field-of-view, plus snapshot,
+preview, and recording — without any vendor SDK.
+
+## Install
+
+```bash
+npm install obsbot-mcp
+```
+
+## MCP client configuration
+
+Add a stdio server entry pointing at the installed binary (or directly at `dist/index.js`):
+
+```json
+{
+  "mcpServers": {
+    "obsbot": {
+      "command": "obsbot-mcp"
+    }
+  }
+}
+```
+
+If you're running from a local checkout instead of an npm install, point `command`/`args` at
+`node` and the built entry point instead:
+
+```json
+{
+  "mcpServers": {
+    "obsbot": {
+      "command": "node",
+      "args": ["path/to/obsbot-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### Debug / diagnostics tools
+
+By default the server advertises only the normal control surface. Pass `--debug` to additionally
+expose the diagnostics surface — the `obsbot_probe` tool (raw XU byte get/set/query) and the
+`raw` 60-byte status block on `obsbot_get_status`:
+
+```json
+{
+  "mcpServers": {
+    "obsbot": {
+      "command": "node",
+      "args": ["path/to/obsbot-mcp/dist/index.js", "--debug"]
+    }
+  }
+}
+```
+
+With the installed binary, use `"command": "obsbot-mcp"` and `"args": ["--debug"]`.
+
+## Tools
+
+### Device & power
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_list_devices` | — | List connected OBSBOT-compatible video capture devices. |
+| `obsbot_set_run_status` | `state`: `"run" \| "sleep"` | Wake (`"run"`) or sleep the camera/gimbal. |
+| `obsbot_get_status` | — | Read the live status block: `{ awake, hdr, aiMode, trackSpeed }`. Under `--debug`, also returns the raw 60-byte block as hex. |
+
+### Gimbal (PTZ)
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_ptz_move_angle` | `yaw`, `pitch`, `roll` (degrees, `roll` defaults `0`) | Move the gimbal to an absolute angle. Positive yaw pans to the camera's left, positive pitch tilts down. Yaw clamped to `[-150, 150]`, pitch to `[-90, 90]`. Absolute 1:1 degrees, hardware-verified. |
+| `obsbot_ptz_move_speed` | `yaw`, `pitch`, `roll` (deg/s, `roll` defaults `0`), `autoStopMs` (default `800`) | Drive the gimbal at a speed, then auto-stop after `autoStopMs` so it can't run away. Same yaw/pitch sign convention as `move_angle`. |
+| `obsbot_gimbal_recenter` | — | Recenter the gimbal (return to home position). |
+| `obsbot_gimbal_position` | — | Read the gimbal's current absolute `{ yaw, pitch }` in degrees via standard UVC Pan/Tilt. May lag a move still in progress. |
+
+### Zoom
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_zoom_absolute` | `ratio` (`1.0`–`2.0`) | Set absolute zoom ratio, clamped to `[1.0, 2.0]`. |
+| `obsbot_zoom_speed` | `ratio` (`1.0`–`2.0`), `speed` (default `0`) | Zoom to a ratio at a chosen speed: `0` = device default, `1`–`10` slow→fast, `255` = maximum. |
+
+### AI tracking
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_ai_tracking` | `enabled` (bool), `mode` (default `"normal"`) | Enable/disable AI subject tracking and choose framing: `normal \| upper-body \| close-up \| headless \| lower-body`. Polls status and returns `{ verified, matched }` (`matched:false` = no subject tracked yet). |
+| `obsbot_ai_track_speed` | `speed`: `"standard" \| "sport"` | Set the tracking-speed preset (Center's Standard/Sport): `standard` (slower follow) or `sport` (snappier). |
+| `obsbot_face_focus` | `enabled` (bool) | Enable or disable face-priority autofocus. |
+
+### Image & lens
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_fov` | `fov`: `"wide" \| "medium" \| "narrow"` | Set the field of view: wide (86°), medium (78°), narrow (65°). |
+| `obsbot_hdr` | `enabled` (bool) | Toggle HDR/WDR imaging on or off. |
+| `obsbot_focus` | `mode`: `"auto" \| "manual"`, `position` (`0`–`100`, default `50`) | `auto` = continuous autofocus; `manual` = set the focus motor to `position` (near→far). |
+| `obsbot_exposure` | `mode`: `"auto" \| "manual"`, `level` (`0`–`100`, default `50`) | `auto` = auto-exposure; `manual` = set `level` (0 darkest → 100 brightest). |
+| `obsbot_white_balance` | `mode`: `"auto" \| "manual"`, `temperature` (Kelvin, default `5000`) | `auto` = auto white balance; `manual` = set a colour temperature (clamped to device range). |
+| `obsbot_image_control` | `control`, `level` (`0`–`100`) | Adjust `brightness \| contrast \| hue \| saturation \| sharpness \| gain \| backlight-compensation`; `level` maps onto the device range. |
+
+### Capture
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_snapshot` | `maxDim` (`256`–`1920`, default `1024`), `quality` (`1`–`100`, default `80`), `settleMs` (default `600`), `source` (default `"device"`) | Grab one still frame and return it as an image (for framing/lighting/exposure checks). `source`: `device \| virtual \| ndi`. |
+| `obsbot_record_start` | `durationSec` (optional), `audio` (default `true`), `outputPath` (optional), `source` (default `"device"`) | Start recording to MP4. Open-ended recordings auto-stop after 60 min; audio uses the OBSBOT mic; defaults under `Videos/OBSBOT`. Returns a `sessionId`. **Needs ffmpeg.**¹ |
+| `obsbot_preview_start` | `source` (default `"device"`) | Open a live preview window. Returns a `sessionId`. **Needs ffplay.**¹ |
+| `obsbot_capture_stop` | `sessionId` | Stop a recording or preview session (recordings are finalized gracefully). |
+| `obsbot_capture_list` | — | List active recording/preview sessions. |
+
+### Diagnostics (`--debug` only)
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `obsbot_probe` | `mode`: `"get" \| "set" \| "query"`, plus `selector`, `length`, `hex`, `opcode`, `payloadHex` | RE/diagnostics only — raw XU byte get/set and framed table queries. Advertised only under `--debug`. |
+
+¹ `record`/`preview` shell out to **ffmpeg**/**ffplay** (install: `winget install Gyan.FFmpeg`
+on Windows, `brew install ffmpeg` on macOS, `apt install ffmpeg` on Linux). `snapshot` does **not**
+need ffmpeg — it grabs the frame through the native helper.
+
+## Supported platforms
+
+- **Windows x64** — supported today. The native helper is built from source in `native/windows/`
+  (CMake + MSVC); the published npm package ships a prebuilt binary so end users need no toolchain.
+- **Linux / macOS** — not yet implemented. The design is platform-agnostic (see [`PROTOCOL.md`](./PROTOCOL.md));
+  adding support means writing an equivalent native helper for each OS's UVC control APIs
+  (`V4L2` on Linux, `AVFoundation`/`IOKit` on macOS) behind the same JSON-RPC-over-stdio contract used by
+  the Windows helper. Contributions welcome.
+
+## No proprietary SDK
+
+This project speaks the camera's USB protocol directly through the OS's standard UVC driver stack and
+does **not** use, link, bundle, or ship any vendor SDK. See [`PROTOCOL.md`](./PROTOCOL.md) for the
+protocol reference (frame format, checksum, command table).
+
+## How it works
+
+The camera exposes two independent control surfaces, both reachable through the OS's standard UVC
+(USB Video Class) driver stack — this project never talks to the USB device directly, so the OS keeps
+mediating access and the camera remains usable as a normal webcam at the same time commands are sent:
+
+- **Standard UVC controls** — zoom (`CT_ZOOM_ABSOLUTE`), focus and exposure (`IAMCameraControl`),
+  gimbal position readback (UVC Pan/Tilt), and the image controls plus white balance
+  (`IAMVideoProcAmp`) — are the camera's built-in UVC properties, driven via DirectShow on Windows.
+- **Vendor commands** — gimbal moves, recenter, wake/sleep, AI tracking, HDR, and field of view —
+  are sent through the camera's UVC Extension Unit, driven via `IKsControl::KsProperty` against the
+  XU's topology node on Windows.
+
+Both are issued through a small native helper process (`obsbot-helper.exe` on Windows) that the Node
+server spawns and talks to over a line-delimited JSON-RPC protocol on stdin/stdout. The helper is the
+only platform-specific piece; the codec (frame encoding, CRC-16/USB checksum, command table), transport
+abstraction, device manager, and MCP tool definitions are all pure TypeScript/JavaScript and shared across
+platforms.
+
+## Verifying against real hardware
+
+`scripts/e2e.mjs` drives the built stack (`dist/`) against a physically connected camera: it wakes the
+device, zooms in, pans the gimbal, recenters, zooms back out, and puts the camera to sleep, with a short
+pause and console log before each step so a human can watch it happen. **This moves the physical gimbal —
+only run it under supervision:**
+
+```bash
+npm run build
+node scripts/e2e.mjs
+```

package/dist/capture/ffmpeg-args.d.ts

@@ -0,0 +1,17 @@
+export type CaptureSource = "device" | "virtual" | "ndi";
+export interface DshowDevices {
+    video: string[];
+    audio: string[];
+}
+export declare function parseDshowDevices(stderr: string): DshowDevices;
+export declare function resolveVideoName(devices: DshowDevices, source: CaptureSource): string | undefined;
+export declare function resolveAudioName(devices: DshowDevices): string | undefined;
+export declare function buildRecordArgs(o: {
+    videoName: string;
+    audioName?: string;
+    durationSec: number;
+    outputPath: string;
+}): string[];
+export declare function buildPreviewArgs(o: {
+    videoName: string;
+}): string[];

package/dist/capture/ffmpeg-args.js

@@ -0,0 +1,48 @@
+// ffmpeg -f dshow -list_devices prints one line per device on stderr:
+//   [dshow @ ..] "Friendly Name" (video)
+// The name is the first quoted span; the trailing "(video)"/"(audio)" is the type.
+export function parseDshowDevices(stderr) {
+    const video = [];
+    const audio = [];
+    for (const line of stderr.split(/\r?\n/)) {
+        const m = line.match(/"(.+)" \((video|audio)\)\s*$/);
+        if (!m)
+            continue;
+        if (m[2] === "video")
+            video.push(m[1]);
+        else
+            audio.push(m[1]);
+    }
+    return { video, audio };
+}
+export function resolveVideoName(devices, source) {
+    if (source === "virtual")
+        return devices.video.find((n) => /OBSBOT Virtual Camera/i.test(n));
+    if (source === "ndi")
+        return devices.video.find((n) => /NDI Webcam/i.test(n));
+    return devices.video.find((n) => /OBSBOT Tiny 2/i.test(n) && !/Virtual/i.test(n));
+}
+export function resolveAudioName(devices) {
+    return devices.audio.find((n) => /OBSBOT.*Mic/i.test(n));
+}
+export function buildRecordArgs(o) {
+    const input = o.audioName
+        ? `video=${o.videoName}:audio=${o.audioName}`
+        : `video=${o.videoName}`;
+    return [
+        "-hide_banner", "-loglevel", "warning", "-f", "dshow",
+        "-i", input,
+        "-t", String(o.durationSec),
+        "-c:v", "libx264", "-pix_fmt", "yuv420p",
+        ...(o.audioName ? ["-c:a", "aac"] : []),
+        "-y", o.outputPath,
+    ];
+}
+export function buildPreviewArgs(o) {
+    return [
+        "-hide_banner", "-loglevel", "warning", "-f", "dshow",
+        "-i", `video=${o.videoName}`,
+        "-window_title", "OBSBOT preview",
+    ];
+}
+//# sourceMappingURL=ffmpeg-args.js.map

package/dist/capture/ffmpeg-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg-args.js","sourceRoot":"","sources":["../../src/capture/ffmpeg-args.ts"],"names":[],"mappings":"AASA,sEAAsE;AACtE,yCAAyC;AACzC,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;QACrD,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;;YAClC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,OAAqB,EACrB,MAAqB;IAErB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAK/B;IACC,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS;QACvB,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC;IAC3B,OAAO;QACL,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO;QACrD,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QAC3B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS;QACxC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,IAAI,EAAE,CAAC,CAAC,UAAU;KACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAwB;IACvD,OAAO;QACL,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO;QACrD,IAAI,EAAE,SAAS,CAAC,CAAC,SAAS,EAAE;QAC5B,eAAe,EAAE,gBAAgB;KAClC,CAAC;AACJ,CAAC"}

package/dist/capture/manager.d.ts

@@ -0,0 +1,60 @@
+import { spawn as realSpawn } from "node:child_process";
+import { type CaptureSource } from "./ffmpeg-args.js";
+export interface CaptureSession {
+    id: string;
+    kind: "record" | "preview";
+    pid: number;
+    source: CaptureSource;
+    outputPath?: string;
+    durationSec?: number;
+    startedAtIso: string;
+}
+/** Expected operational failure (surfaced to the user as text, not thrown to the client). */
+export declare class CaptureError extends Error {
+    constructor(message: string);
+}
+export declare class FfmpegMissingError extends CaptureError {
+    constructor();
+}
+interface FsLike {
+    existsSync: (p: string) => boolean;
+    mkdirSync: (p: string, opts: {
+        recursive: boolean;
+    }) => void;
+}
+interface Deps {
+    spawn?: typeof realSpawn;
+    clock?: () => string;
+    hasBinary?: (name: string) => boolean;
+    fs?: FsLike;
+}
+export declare class CaptureManager {
+    private readonly spawn;
+    private readonly clock;
+    private readonly hasBinary;
+    private readonly fs;
+    private readonly sessions;
+    private devices?;
+    private seq;
+    constructor(deps?: Deps);
+    private ensureFfmpeg;
+    private probeDevices;
+    private timestampName;
+    startRecord(o: {
+        source: CaptureSource;
+        durationSec?: number;
+        audio: boolean;
+        outputPath?: string;
+    }): Promise<CaptureSession>;
+    startPreview(o: {
+        source: CaptureSource;
+    }): Promise<CaptureSession>;
+    stop(id: string): Promise<{
+        kind: "record" | "preview";
+        outputPath?: string;
+        graceful: boolean;
+    }>;
+    list(): CaptureSession[];
+    stopAll(): void;
+}
+export {};

package/dist/capture/manager.js

@@ -0,0 +1,159 @@
+import { spawn as realSpawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseDshowDevices, resolveVideoName, resolveAudioName, buildRecordArgs, buildPreviewArgs, } from "./ffmpeg-args.js";
+/** Expected operational failure (surfaced to the user as text, not thrown to the client). */
+export class CaptureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CaptureError";
+    }
+}
+export class FfmpegMissingError extends CaptureError {
+    constructor() {
+        super("Recording/preview needs ffmpeg and ffplay, which aren't installed. " +
+            "Install with: winget install Gyan.FFmpeg (Windows) / brew install ffmpeg (mac) / " +
+            "apt install ffmpeg (Linux).");
+        this.name = "FfmpegMissingError";
+    }
+}
+const OPEN_ENDED_CAP_SEC = 3600;
+const GRACEFUL_STOP_MS = 5000;
+function defaultHasBinary(name) {
+    const r = spawnSync(name, ["-version"], { stdio: "ignore" });
+    return !r.error;
+}
+export class CaptureManager {
+    spawn;
+    clock;
+    hasBinary;
+    fs;
+    sessions = new Map();
+    devices;
+    seq = 0;
+    constructor(deps = {}) {
+        this.spawn = deps.spawn ?? realSpawn;
+        this.clock = deps.clock ?? (() => new Date().toISOString());
+        this.hasBinary = deps.hasBinary ?? defaultHasBinary;
+        this.fs = deps.fs ?? { existsSync, mkdirSync };
+    }
+    ensureFfmpeg() {
+        if (!this.hasBinary("ffmpeg") || !this.hasBinary("ffplay")) {
+            throw new FfmpegMissingError();
+        }
+    }
+    probeDevices() {
+        if (this.devices)
+            return Promise.resolve(this.devices);
+        return new Promise((resolve, reject) => {
+            const child = this.spawn("ffmpeg", ["-hide_banner", "-f", "dshow", "-list_devices", "true", "-i", "dummy"]);
+            let err = "";
+            child.stderr?.on("data", (d) => { err += d.toString(); });
+            child.on("error", (e) => reject(new CaptureError(`failed to run ffmpeg for device probe: ${e.message}`)));
+            child.on("close", () => {
+                this.devices = parseDshowDevices(err);
+                resolve(this.devices);
+            });
+        });
+    }
+    timestampName() {
+        // clock() -> "2026-07-13T09:33:58.000Z"; make obsbot-YYYYMMDD-HHMMSS.mp4
+        const iso = this.clock();
+        const compact = iso.replace(/[-:]/g, "").replace("T", "-").replace(/\..*$/, "");
+        return `obsbot-${compact}.mp4`;
+    }
+    async startRecord(o) {
+        this.ensureFfmpeg();
+        const devices = await this.probeDevices();
+        const videoName = resolveVideoName(devices, o.source);
+        if (!videoName)
+            throw new CaptureError(`no '${o.source}' video source found (is OBSBOT Center / NDI running?)`);
+        let audioName;
+        if (o.audio) {
+            audioName = resolveAudioName(devices);
+            if (!audioName)
+                throw new CaptureError("OBSBOT microphone not found; retry with audio:false for a silent clip");
+        }
+        const outputPath = o.outputPath ?? join(homedir(), "Videos", "OBSBOT", this.timestampName());
+        if (o.outputPath && this.fs.existsSync(o.outputPath)) {
+            throw new CaptureError(`output file already exists: ${o.outputPath}`);
+        }
+        this.fs.mkdirSync(dirname(outputPath), { recursive: true });
+        const durationSec = o.durationSec ?? OPEN_ENDED_CAP_SEC;
+        const args = buildRecordArgs({ videoName, audioName, durationSec, outputPath });
+        const child = this.spawn("ffmpeg", args, { stdio: ["pipe", "ignore", "ignore"] });
+        const session = {
+            id: `cap${++this.seq}`, kind: "record", pid: child.pid ?? -1,
+            source: o.source, outputPath, durationSec, startedAtIso: this.clock(),
+        };
+        this.sessions.set(session.id, { session, child });
+        child.once("exit", () => this.sessions.delete(session.id));
+        child.on("error", () => this.sessions.delete(session.id));
+        return session;
+    }
+    async startPreview(o) {
+        this.ensureFfmpeg();
+        const devices = await this.probeDevices();
+        const videoName = resolveVideoName(devices, o.source);
+        if (!videoName)
+            throw new CaptureError(`no '${o.source}' video source found (is OBSBOT Center / NDI running?)`);
+        const args = buildPreviewArgs({ videoName });
+        const child = this.spawn("ffplay", args, { stdio: "ignore" });
+        const session = {
+            id: `cap${++this.seq}`, kind: "preview", pid: child.pid ?? -1,
+            source: o.source, startedAtIso: this.clock(),
+        };
+        this.sessions.set(session.id, { session, child });
+        child.once("exit", () => this.sessions.delete(session.id));
+        child.on("error", () => this.sessions.delete(session.id));
+        return session;
+    }
+    async stop(id) {
+        const entry = this.sessions.get(id);
+        if (!entry)
+            throw new CaptureError(`no such capture session: ${id}`);
+        const { session, child } = entry;
+        let graceful = true;
+        if (session.kind === "record") {
+            // 'q' on stdin is ffmpeg's clean stop (finalizes the MP4 moov atom).
+            graceful = await new Promise((resolve) => {
+                let done = false;
+                const timer = setTimeout(() => { if (!done) {
+                    done = true;
+                    child.kill();
+                    resolve(false);
+                } }, GRACEFUL_STOP_MS);
+                child.once("exit", () => { if (!done) {
+                    done = true;
+                    clearTimeout(timer);
+                    resolve(true);
+                } });
+                try {
+                    child.stdin?.write("q");
+                }
+                catch { /* already gone */ }
+            });
+        }
+        else {
+            child.kill();
+        }
+        this.sessions.delete(id);
+        return { kind: session.kind, outputPath: session.outputPath, graceful };
+    }
+    list() {
+        return [...this.sessions.values()].map((e) => e.session);
+    }
+    // Hard-kill every child. Wired to server shutdown so nothing orphans; this is
+    // last-resort cleanup, not a graceful stop.
+    stopAll() {
+        for (const { child } of this.sessions.values()) {
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+        }
+        this.sessions.clear();
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/capture/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/capture/manager.ts"],"names":[],"mappings":"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"}

package/dist/codec/commands.d.ts

@@ -0,0 +1,63 @@
+import { VendorFrame, RunState } from "./types.js";
+/**
+ * RE/diagnostics: build ANY opcode-table entry as a V3 frame with an arbitrary
+ * payload. Used by the obsbot_probe tool to exercise unmapped GET/query opcodes
+ * (e.g. AI_GET_QUICK_STATUS) while reverse-engineering the feedback surface.
+ */
+export declare const encodeVendorProbe: (name: string, payload: Buffer) => VendorFrame;
+export declare const encodeSetRunStatus: (state: RunState) => VendorFrame;
+export declare const encodePtzMoveAngle: (yaw: number, pitch: number, roll: number) => VendorFrame;
+export declare const encodePtzMoveSpeed: (yaw: number, pitch: number, roll: number) => VendorFrame;
+export declare const encodeRecenter: () => VendorFrame;
+export declare const zoomRatioToUnits: (ratio: number, min: number, max: number) => number;
+export type AiTrackMode = "human-normal" | "human-full-body" | "human-half-body" | "human-close-up" | "human-auto-view" | "animal-normal" | "animal-close-up" | "animal-auto-view";
+export declare const AI_TRACK_MODES: AiTrackMode[];
+/** Enable AI tracking in a specific framing mode (AI_SET_AI_TRACK_MODE, cmd 0x6f). */
+export declare const encodeAiTrackEnable: (mode: AiTrackMode) => VendorFrame;
+/** Disable AI tracking of the current target (AI_SET_CANCEL_TARGET, cmd 0x6e — no payload). */
+export declare const encodeAiTrackDisable: () => VendorFrame;
+/** Enable auto group-framing (AI_SET_AUTO_GROUP, cmd 0x70 — 8 zero bytes). */
+export declare const encodeAiGroupEnable: () => VendorFrame;
+/** Disable auto group-framing (AI_CANCEL_AUTO_GROUP, cmd 0x71 — no payload). */
+export declare const encodeAiGroupDisable: () => VendorFrame;
+export type AiTrackSpeed = "standard" | "sport";
+export declare const AI_TRACK_SPEEDS: AiTrackSpeed[];
+export declare const encodeAiTrackSpeed: (speed: AiTrackSpeed) => VendorFrame;
+export declare const encodeZoomWithSpeed: (ratioX100: number, speed: number) => VendorFrame;
+export declare const encodeFaceFocus: (enable: boolean) => VendorFrame;
+/** Request the current face-priority autofocus state (CAM_GET_FACE_FOCUS, cmd 0x35c2). */
+export declare const encodeGetFaceFocus: () => VendorFrame;
+export interface FaceFocusState {
+    enabled: boolean;
+}
+/** Decode a CAM_GET_FACE_FOCUS reply payload: int32le enable flag at offset 0. */
+export declare const decodeFaceFocus: (payload: Buffer) => FaceFocusState;
+export declare const UVC_XU_SELECTOR = 6;
+export type FovType = "wide" | "medium" | "narrow";
+export declare const FOV_TYPES: FovType[];
+export declare const encodeFov: (fov: FovType) => Buffer;
+export declare const encodeHdr: (on: boolean) => Buffer;
+export type AiFramingMode = "normal" | "upper-body" | "close-up" | "headless" | "lower-body";
+export declare const AI_FRAMING_MODES: AiFramingMode[];
+export declare const encodeAiTracking: (on: boolean, mode?: AiFramingMode) => Buffer;
+export declare const CAMERA_CONTROL_PAN = 0;
+export declare const CAMERA_CONTROL_TILT = 1;
+export declare const CAMERA_CONTROL_FOCUS = 6;
+export declare const CAMERA_CONTROL_EXPOSURE = 4;
+export declare const VIDEO_PROCAMP_WHITE_BALANCE = 7;
+export declare const UVC_FLAG_AUTO = 1;
+export declare const UVC_FLAG_MANUAL = 2;
+export type ImageControl = "brightness" | "contrast" | "hue" | "saturation" | "sharpness" | "backlight-compensation" | "gain";
+export declare const IMAGE_CONTROL_PROP: Record<ImageControl, number>;
+export declare const IMAGE_CONTROLS: ImageControl[];
+/** Map a 0..100 percentage onto an inclusive [min,max] device-unit range. */
+export declare const percentToRange: (pct: number, min: number, max: number) => number;
+export type AiModeStatus = "no-tracking" | "normal" | "upper-body" | "close-up" | "headless" | "lower-body" | "desk" | "whiteboard" | "hand" | "group" | "unknown";
+export type TrackSpeedStatus = "standard" | "sport" | "unknown";
+export interface CameraStatus {
+    awake: boolean;
+    hdr: boolean;
+    aiMode: AiModeStatus;
+    trackSpeed: TrackSpeedStatus;
+}
+export declare const decodeStatus: (block: Buffer) => CameraStatus;