obsbot-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,170 +1,186 @@
-# 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
-```
+# 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 x64** — supported from v0.2. The native helper is in `native/linux/` (CMake + GCC);
+  it uses **V4L2** for standard UVC controls (zoom, focus, exposure, pan/tilt, white balance,
+  image controls) and `UVCIOC_CTRL_QUERY` for vendor Extension Unit commands (gimbal, AI tracking,
+  wake/sleep, HDR, FOV). Snapshots capture a MJPEG or YUYV frame via V4L2 mmap streaming and encode
+  to JPEG using **libjpeg**. The `linux-x64` prebuilt binary ships with the published npm package.
+  Build dependencies: `build-essential cmake libjpeg-dev libv4l-dev`.
+- **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
+  (`AVFoundation`/`IOKit` on macOS) behind the same JSON-RPC-over-stdio contract used by the existing
+  Windows and Linux helpers. Contributions welcome.
+
+### Building the native helper (Linux)
+
+```bash
+cd native/linux
+mkdir build && cd build
+cmake ..
+make -j$(nproc)
+make install  # copies to native/prebuilt/linux-x64/
+```
+
+## 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, `obsbot-helper`
+on Linux) 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

@@ -3,9 +3,20 @@ export interface DshowDevices {
     video: string[];
     audio: string[];
 }
+export interface V4l2DeviceInfo {
+    path: string;
+    card: string;
+}
+export interface V4l2Devices {
+    video: V4l2DeviceInfo[];
+    audio: string[];
+}
+export type DeviceList = DshowDevices | V4l2Devices;
 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 resolveVideoName(devices: DeviceList, source: CaptureSource): string | undefined;
+export declare function resolveAudioName(devices: DeviceList): string | undefined;
+/** Parse the v4l2 device name from `ffmpeg -f v4l2 -i /dev/videoN` stderr. */
+export declare function parseV4l2DeviceName(stderr: string): string | undefined;
 export declare function buildRecordArgs(o: {
     videoName: string;
     audioName?: string;

package/dist/capture/ffmpeg-args.js

@@ -1,6 +1,6 @@
+// ---------- Windows (dshow) helpers ----------
 // 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 = [];
@@ -16,16 +16,61 @@ export function parseDshowDevices(stderr) {
     return { video, audio };
 }
 export function resolveVideoName(devices, source) {
-    if (source === "virtual")
+    const isV4l = (d) => "video" in d && d.video.length > 0 && typeof d.video[0] !== "string";
+    if (source === "virtual") {
+        if (isV4l(devices)) {
+            return devices.video.find((n) => /OBSBOT Virtual Camera/i.test(n.card))?.path;
+        }
         return devices.video.find((n) => /OBSBOT Virtual Camera/i.test(n));
-    if (source === "ndi")
+    }
+    if (source === "ndi") {
+        if (isV4l(devices)) {
+            return devices.video.find((n) => /NDI Webcam/i.test(n.card))?.path;
+        }
         return devices.video.find((n) => /NDI Webcam/i.test(n));
+    }
+    // Platform-specific device matching
+    if (isV4l(devices)) {
+        const found = devices.video.find((n) => /OBSBOT/i.test(n.card));
+        return found ? found.path : undefined;
+    }
+    // dshow on Windows
     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));
+    if ("audio" in devices && Array.isArray(devices.audio)) {
+        return devices.audio.find((n) => /OBSBOT.*Mic/i.test(n));
+    }
+    // Linux v4l2 audio is typically a separate ALSA device
+    // Return undefined — callers should check and warn
+    return undefined;
+}
+// ---------- Linux (v4l2) helpers ----------
+// ffmpeg -f v4l2 -list_formats all -i /dev/videoN lists formats on stderr.
+/** Parse the v4l2 device name from `ffmpeg -f v4l2 -i /dev/videoN` stderr. */
+export function parseV4l2DeviceName(stderr) {
+    // ffmpeg prints something like:
+    //   [video4linux2,v4l2 @ 0x...] VideoDevice: /dev/videoN
+    //   [video4linux2,v4l2 @ 0x...] driver       : uvcvideo
+    //   [video4linux2,v4l2 @ 0x...] card         : OBSBOT Tiny 2 ...
+    const m = stderr.match(/card\s+:\s+(.+)/);
+    return m ? m[1].trim() : undefined;
 }
 export function buildRecordArgs(o) {
+    const isV4l2 = o.videoName.startsWith("/dev/");
+    if (isV4l2) {
+        return [
+            "-hide_banner", "-loglevel", "warning",
+            "-f", "v4l2",
+            "-i", o.videoName,
+            ...(o.audioName ? ["-f", "alsa", "-i", o.audioName] : []),
+            "-t", String(o.durationSec),
+            "-c:v", "libx264", "-pix_fmt", "yuv420p",
+            ...(o.audioName ? ["-c:a", "aac"] : []),
+            "-y", o.outputPath,
+        ];
+    }
+    // dshow path (Windows)
     const input = o.audioName
         ? `video=${o.videoName}:audio=${o.audioName}`
         : `video=${o.videoName}`;
@@ -39,6 +84,18 @@ export function buildRecordArgs(o) {
     ];
 }
 export function buildPreviewArgs(o) {
+    const isV4l2 = o.videoName.startsWith("/dev/");
+    if (isV4l2) {
+        return [
+            "-hide_banner", "-loglevel", "warning",
+            "-f", "v4l2",
+            "-input_format", "mjpeg",
+            "-video_size", "1920x1080",
+            "-i", o.videoName,
+            "-window_title", "OBSBOT preview",
+        ];
+    }
+    // dshow path
     return [
         "-hide_banner", "-loglevel", "warning", "-f", "dshow",
         "-i", `video=${o.videoName}`,

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

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

package/dist/capture/manager.d.ts

@@ -1,5 +1,5 @@
 import { spawn as realSpawn } from "node:child_process";
-import { type CaptureSource } from "./ffmpeg-args.js";
+import { type CaptureSource, type DeviceList } from "./ffmpeg-args.js";
 export interface CaptureSession {
     id: string;
     kind: "record" | "preview";
@@ -27,18 +27,24 @@ interface Deps {
     clock?: () => string;
     hasBinary?: (name: string) => boolean;
     fs?: FsLike;
+    /** Override for device probe logic (used by tests to avoid real V4L2/dshow probing). */
+    probeDevices?: () => Promise<DeviceList>;
 }
 export declare class CaptureManager {
     private readonly spawn;
     private readonly clock;
     private readonly hasBinary;
     private readonly fs;
+    private readonly probeFn;
     private readonly sessions;
     private devices?;
     private seq;
     constructor(deps?: Deps);
     private ensureFfmpeg;
     private probeDevices;
+    private probeV4l2Devices;
+    private probeV4l2Card;
+    private probeDshowDevices;
     private timestampName;
     startRecord(o: {
         source: CaptureSource;

package/dist/capture/manager.js

@@ -1,5 +1,5 @@
 import { spawn as realSpawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { parseDshowDevices, resolveVideoName, resolveAudioName, buildRecordArgs, buildPreviewArgs, } from "./ffmpeg-args.js";
@@ -29,6 +29,7 @@ export class CaptureManager {
     clock;
     hasBinary;
     fs;
+    probeFn;
     sessions = new Map();
     devices;
     seq = 0;
@@ -37,6 +38,7 @@ export class CaptureManager {
         this.clock = deps.clock ?? (() => new Date().toISOString());
         this.hasBinary = deps.hasBinary ?? defaultHasBinary;
         this.fs = deps.fs ?? { existsSync, mkdirSync };
+        this.probeFn = deps.probeDevices;
     }
     ensureFfmpeg() {
         if (!this.hasBinary("ffmpeg") || !this.hasBinary("ffplay")) {
@@ -46,19 +48,64 @@ export class CaptureManager {
     probeDevices() {
         if (this.devices)
             return Promise.resolve(this.devices);
+        // Allow tests to inject a mock probe
+        if (this.probeFn)
+            return this.probeFn();
         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);
-            });
+            if (process.platform === "linux") {
+                // On Linux, list /dev/video* devices and probe each one
+                this.probeV4l2Devices().then(resolve).catch(reject);
+            }
+            else {
+                this.probeDshowDevices(resolve, reject);
+            }
+        });
+    }
+    async probeV4l2Devices() {
+        const video = [];
+        try {
+            const files = readdirSync("/dev");
+            const videoDevs = files
+                .filter((f) => /^video\d+$/.test(f))
+                .map((f) => `/dev/${f}`)
+                .sort();
+            for (const dev of videoDevs) {
+                const name = await this.probeV4l2Card(dev);
+                if (name)
+                    video.push({ path: dev, card: name });
+            }
+        }
+        catch {
+            // /dev not readable
+        }
+        return { video, audio: [] };
+    }
+    probeV4l2Card(dev) {
+        return new Promise((resolve) => {
+            try {
+                const idx = dev.match(/video(\d+)$/)?.[1];
+                if (!idx)
+                    return resolve(undefined);
+                const sysfs = `/sys/class/video4linux/video${idx}/name`;
+                const name = readFileSync(sysfs, 'utf-8').trim();
+                resolve(name || undefined);
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+    }
+    probeDshowDevices(resolve, reject) {
+        const child = this.spawn("ffmpeg", ["-hide_banner", "-f", "dshow", "-list_devices", "true", "-i", "dummy"], { stdio: ["pipe", "pipe", "pipe"] });
+        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`;
@@ -116,7 +163,6 @@ export class CaptureManager {
         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) {
@@ -142,12 +188,10 @@ export class CaptureManager {
         return { kind: session.kind, outputPath: session.outputPath, graceful };
     }
     list() {
-        return [...this.sessions.values()].map((e) => e.session);
+        return Array.from(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()) {
+        for (const { child } of Array.from(this.sessions.values())) {
             try {
                 child.kill();
             }