obsbot-mcp 0.8.0 → 0.9.0

package/dist/tail2/move.d.ts

@@ -0,0 +1,41 @@
+import type { Pose } from "./api.js";
+/**
+ * Absolute gimbal positioning for the Tail 2, built out of the two primitives
+ * the HTTP API actually offers: continuous speed moves (POST ptz/gimbalcontrol)
+ * and a slow pose readback (save-scratch-preset → GET). There is no
+ * move-to-angle endpoint, so this is a closed loop with a very sluggish
+ * sensor — a pose read costs ~1.5 s and the preset list lags the save by up
+ * to ~1 s. The loop is therefore deliberately conservative: undershoot each
+ * jog, re-read, correct; never let a jog run longer than a few seconds.
+ *
+ * Two facts from the 2026-09-30 hardware session shape it:
+ *   - SPEED: yaw command 20 for 1 s moved the recorded pose 7.86°, so roughly
+ *     0.39 °/s per command unit (ramps included in that one sample).
+ *   - SIGN: a POSITIVE yaw command DECREASED the recorded yaw. The command
+ *     sign per axis is a convention we have measured for yaw only; the loop
+ *     assumes the same for pitch and self-corrects per axis on contradiction
+ *     (first jog too far away → flip that axis and continue).
+ */
+export interface MoveDeps {
+    readPose(): Promise<Pose>;
+    speedCmd(yawUnits: number, pitchUnits: number): Promise<void>;
+    stop(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+}
+export interface MoveTarget {
+    yaw?: number;
+    pitch?: number;
+}
+export interface MoveResult {
+    pose: Pose;
+    /** Axis error in degrees when the loop finished, by axis. */
+    error: {
+        yaw: number;
+        pitch: number;
+    };
+    iterations: number;
+    converged: boolean;
+    /** Axes whose command sign had to be flipped after the first jog. */
+    signFlipped: string[];
+}
+export declare function moveAbsolute(deps: MoveDeps, target: MoveTarget): Promise<MoveResult>;

package/dist/tail2/move.js

@@ -0,0 +1,79 @@
+/** Rough °/s per command unit at the speeds this loop uses (measured once, ramps included). */
+const EST_DEG_PER_S_PER_UNIT = 0.39;
+/** Aim to cover this fraction of the remaining error per jog: undershoot, then correct. */
+const COVER_FRACTION = 0.75;
+/** Stop when an axis is within this many degrees. */
+const TOLERANCE_DEG = 1.5;
+const MAX_ITERATIONS = 5;
+const MAX_JOG_MS = 3500;
+const MIN_SPEED_UNITS = 8;
+const MAX_SPEED_UNITS = 40;
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+export async function moveAbsolute(deps, target) {
+    // Command sign per axis: measured, a positive yaw command decreased the
+    // recorded yaw — so to move the record toward +, command −.
+    const sign = { yaw: -1, pitch: -1 };
+    const signFlipped = [];
+    let pose = await deps.readPose();
+    const errOf = (p) => ({
+        yaw: target.yaw !== undefined ? target.yaw - p.yaw : 0,
+        pitch: target.pitch !== undefined ? target.pitch - p.pitch : 0,
+    });
+    const err = errOf(pose);
+    const prevErr = { ...err };
+    let iterations = 0;
+    let lastCmd = null;
+    while (iterations < MAX_ITERATIONS) {
+        const errNow = errOf(pose);
+        if (Math.abs(errNow.yaw) <= TOLERANCE_DEG && Math.abs(errNow.pitch) <= TOLERANCE_DEG)
+            break;
+        if (iterations > 0 && lastCmd) {
+            // Self-calibration: if an axis we drove got FARTHER away, our assumed
+            // command sign for that axis is wrong. Flip it and continue.
+            for (const axis of ["yaw", "pitch"]) {
+                if (lastCmd[axis] === 0)
+                    continue;
+                if (Math.abs(errNow[axis]) > Math.abs(prevErr[axis]) + 0.5) {
+                    sign[axis] = -sign[axis];
+                    if (!signFlipped.includes(axis))
+                        signFlipped.push(axis);
+                }
+            }
+        }
+        // Speed from the larger remaining error, undershooting on purpose.
+        const worst = Math.max(Math.abs(errNow.yaw), Math.abs(errNow.pitch));
+        const units = clamp(worst / EST_DEG_PER_S_PER_UNIT, MIN_SPEED_UNITS, MAX_SPEED_UNITS);
+        const duration = clamp((worst * COVER_FRACTION) / (units * EST_DEG_PER_S_PER_UNIT) * 1000, 250, MAX_JOG_MS);
+        const cmd = {
+            // Command direction: the axis sign convention (Δpose = sign × cmd × k)
+            // applied to the error's own sign — toward the target, whichever side
+            // of it we are on.
+            yaw: Math.abs(errNow.yaw) > TOLERANCE_DEG ? sign.yaw * Math.sign(errNow.yaw) * units : 0,
+            pitch: Math.abs(errNow.pitch) > TOLERANCE_DEG
+                ? sign.pitch * Math.sign(errNow.pitch) * units
+                : 0,
+        };
+        if (cmd.yaw === 0 && cmd.pitch === 0)
+            break;
+        try {
+            await deps.speedCmd(cmd.yaw, cmd.pitch);
+            lastCmd = cmd;
+            Object.assign(prevErr, errNow);
+            await deps.sleep(duration);
+        }
+        finally {
+            await deps.stop();
+        }
+        iterations++;
+        pose = await deps.readPose();
+    }
+    const errFinal = errOf(pose);
+    return {
+        pose,
+        error: errFinal,
+        iterations,
+        converged: Math.abs(errFinal.yaw) <= TOLERANCE_DEG && Math.abs(errFinal.pitch) <= TOLERANCE_DEG,
+        signFlipped,
+    };
+}
+//# sourceMappingURL=move.js.map

package/dist/tail2/move.js.map

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

package/dist/tail2/tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { srtSnapshot, ndiToolsInstalled } from "./snapshot.js";
+import { moveAbsolute } from "./move.js";
 /**
  * MCP tools for the OBSBOT Tail 2 (network camera — HTTP/WS control; its USB
  * UVC mode is not used here, see TAIL2-PROTOCOL.md §11). A separate tool family from the Tiny 2's:
@@ -45,6 +46,17 @@ const zoomSchema = withCamera({
     speed: num().pipe(z.number().int().min(1).max(10)).default(5),
 });
 const recenterSchema = withCamera({});
+const gimbalSpeedSchema = withCamera({
+    yaw: num().pipe(z.number().min(-150).max(150)).optional(),
+    pitch: num().pipe(z.number().min(-150).max(150)).optional(),
+    roll: num().pipe(z.number().min(-150).max(150)).optional(),
+    durationMs: num().pipe(z.number().int().min(100).max(5000)).optional(),
+});
+const gimbalMoveSchema = withCamera({
+    yaw: num().pipe(z.number().min(-178).max(178)).optional(),
+    pitch: num().pipe(z.number().min(-178).max(178)).optional(),
+});
+const gimbalInvertSchema = withCamera({ enable: bool().optional() });
 const portraitSchema = withCamera({ enable: bool() });
 const rollBiasSchema = withCamera({ angle: num().pipe(z.number().min(-90).max(90)) });
 const aiTrackSchema = withCamera({
@@ -162,6 +174,396 @@ export function createTail2Tools(registry, grab = (host, o) => srtSnapshot(host,
                 return { ok: true };
             },
         },
+        {
+            name: "obsbot_tail2_gimbal_position",
+            description: "Read the Tail 2's live gimbal pose in degrees (yaw/pitch/roll) plus the zoom ratio. " +
+                "The API has no direct pose read — this works by saving the current pose into an empty " +
+                "preset slot, reading it back, and deleting the slot (takes ~2s). Requires at least one " +
+                "empty preset slot: overwriting a preset is irreversible (no pose-by-value write exists " +
+                "to restore it). Leftover 'pose-probe' slots from crashed reads are deleted, not trusted.",
+            schema: withCamera({}),
+            handler: async (args) => {
+                const { camera } = withCamera({}).parse(args);
+                const { api } = await registry.resolve(camera);
+                return await api.readPose();
+            },
+        },
+        {
+            name: "obsbot_tail2_gimbal_speed",
+            description: "Jog the Tail 2's gimbal: per-axis SPEED (sign = direction, magnitude = speed, ±150 of " +
+                "the firmware's ±178 range) with an automatic stop after durationMs (default 500, max " +
+                "5000). This is the joystick primitive (POST ptz/gimbalcontrol) — there is no absolute " +
+                "move endpoint, so the camera moves continuously until stopped; this tool always stops " +
+                "it. Measured: command 20 ≈ 7.9°/s, and a POSITIVE yaw command DECREASES the recorded " +
+                "yaw (obsbot_tail2_gimbal_position's convention). Disable AI tracking first or it will " +
+                "fight the move.",
+            schema: gimbalSpeedSchema,
+            handler: async (args) => {
+                const { camera, yaw, pitch, roll, durationMs } = gimbalSpeedSchema.parse(args);
+                if (yaw === undefined && pitch === undefined && roll === undefined) {
+                    throw new Error("give at least one of yaw, pitch, roll (a speed to drive)");
+                }
+                const { api } = await registry.resolve(camera);
+                const t0 = Date.now();
+                try {
+                    await api.gimbalSpeed(yaw ?? 0, pitch ?? 0, roll ?? 0);
+                    await new Promise((r) => setTimeout(r, durationMs ?? 500));
+                }
+                finally {
+                    await api.gimbalStop();
+                }
+                return { ok: true, droveMs: Date.now() - t0, stopped: true };
+            },
+        },
+        {
+            name: "obsbot_tail2_gimbal_move",
+            description: "Move the Tail 2's gimbal to an absolute yaw/pitch in degrees — the Tail 2's pose-record " +
+                "convention (obsbot_tail2_gimbal_position reports the same axes). There is no move-to-" +
+                "angle endpoint in the API, so this is a closed loop over the speed primitive: jog, read " +
+                "the pose (each read ~2s), correct, up to 5 rounds, tolerance ±1.5°. Slow by design — " +
+                "expect ~5-15s. REFUSES while AI tracking is active (tracking drives the gimbal itself " +
+                "and would fight the loop); obsbot_tail2_ai_track enabled:false first.",
+            schema: gimbalMoveSchema,
+            handler: async (args) => {
+                const { camera, yaw, pitch } = gimbalMoveSchema.parse(args);
+                if (yaw === undefined && pitch === undefined) {
+                    throw new Error("give at least one of yaw, pitch to move to");
+                }
+                const { api } = await registry.resolve(camera);
+                const { mode } = await api.aiModeGet();
+                if (mode !== "none") {
+                    throw new Error(`AI tracking is active (${mode}) and drives the gimbal itself — it would fight the move. ` +
+                        `Call obsbot_tail2_ai_track with enabled:false first.`);
+                }
+                const result = await moveAbsolute({
+                    readPose: () => api.readPose(),
+                    speedCmd: (y, p) => api.gimbalSpeed(y, p, 0),
+                    stop: () => api.gimbalStop(),
+                    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+                }, { yaw, pitch });
+                return {
+                    ok: true,
+                    ...result,
+                    note: result.converged
+                        ? undefined
+                        : "did not converge within the iteration budget — the pose is as close as it got; retry or jog with obsbot_tail2_gimbal_speed",
+                };
+            },
+        },
+        {
+            name: "obsbot_tail2_gimbal_invert",
+            description: "Read or set the Tail 2's control-direction inversion (gimbalinvert). Call with no " +
+                "arguments to read; pass enable to write (verified by readback).",
+            schema: gimbalInvertSchema,
+            handler: async (args) => {
+                const { camera, enable } = gimbalInvertSchema.parse(args);
+                const { api } = await registry.resolve(camera);
+                if (enable === undefined)
+                    return await api.gimbalInvertGet();
+                const r = await api.gimbalInvertSet(enable);
+                return { ok: true, ...r };
+            },
+        },
+        {
+            name: "obsbot_tail2_record",
+            description: "Read (bare call) or control (enable) the Tail 2's recording switch over REST. Recording " +
+                "needs storage — with no SD card the state still reads (\"off\") but starting will not " +
+                "succeed; check obsbot_tail2_status's sdcard field first.",
+            schema: withCamera({ enable: bool().optional() }),
+            handler: async (args) => {
+                const { camera, enable } = withCamera({ enable: bool().optional() }).parse(args);
+                const { api } = await registry.resolve(camera);
+                if (enable === undefined)
+                    return await api.recordGet();
+                const r = await api.recordSet(enable);
+                return { ok: true, ...r };
+            },
+        },
+        {
+            name: "obsbot_tail2_capture_photo",
+            description: "Trigger a still-photo capture on the Tail 2 (POST capture/trigger). Needs storage (SD " +
+                "card — check obsbot_tail2_status's sdcard field). The ack means the camera accepted the " +
+                "trigger; the photo lands on the card (see obsbot_tail2_status / album).",
+            schema: withCamera({}),
+            handler: async (args) => {
+                const { camera } = withCamera({}).parse(args);
+                const { api } = await registry.resolve(camera);
+                await api.captureTrigger();
+                return { ok: true };
+            },
+        },
+        {
+            name: "obsbot_tail2_track_target",
+            description: "Tap-to-track: give a normalized frame coordinate (x/y 0.01-0.99, top-left ~0,0) and the " +
+                "camera engages AI tracking on the subject there — measured to arm humanTrackingSingleMode " +
+                "on its own from mode none. Divide a snapshot pixel by frameWidth/frameHeight and pass it " +
+                "straight in. The mode that engages depends on what is at the point, so read it back " +
+                "(obsbot_tail2_status ai_mode) when it matters; objectTracking cannot be entered this way " +
+                "(it demands a bounding box the API grammar for which is not yet decoded).",
+            schema: withCamera({
+                x: num().pipe(z.number().min(0.01).max(0.99)),
+                y: num().pipe(z.number().min(0.01).max(0.99)),
+            }),
+            handler: async (args) => {
+                const schema = withCamera({
+                    x: num().pipe(z.number().min(0.01).max(0.99)),
+                    y: num().pipe(z.number().min(0.01).max(0.99)),
+                });
+                const { camera, x, y } = schema.parse(args);
+                const { api } = await registry.resolve(camera);
+                await api.targetSelect(x, y);
+                const { mode } = await api.aiModeGet();
+                return { ok: true, x, y, aiMode: mode };
+            },
+        },
+        {
+            name: "obsbot_tail2_focus_point",
+            description: "Tap-to-focus: move the focus window to a normalized frame coordinate (x/y 0.01-0.99, " +
+                "top-left ~0,0) AND start a point focus there. Effective in afc/afs focus modes only — " +
+                "in mf the motor position is the tool (obsbot_tail2_focus). Bare call reads the current " +
+                "window. Divide a snapshot pixel by frameWidth/frameHeight and pass it straight in.",
+            schema: withCamera({
+                x: num().pipe(z.number().min(0.01).max(0.99)).optional(),
+                y: num().pipe(z.number().min(0.01).max(0.99)).optional(),
+            }),
+            handler: async (args) => {
+                const schema = withCamera({
+                    x: num().pipe(z.number().min(0.01).max(0.99)).optional(),
+                    y: num().pipe(z.number().min(0.01).max(0.99)).optional(),
+                });
+                const { camera, x, y } = schema.parse(args);
+                const { api } = await registry.resolve(camera);
+                if (x === undefined && y === undefined)
+                    return await api.focusWindowGet();
+                if (x === undefined || y === undefined) {
+                    throw new Error("x and y go together — give both or neither");
+                }
+                const { mode } = await api.focusModeGet();
+                if (mode === "mf") {
+                    throw new Error(`focus window applies in afc/afs only (current: ${mode}). ` +
+                        `In mf, drive the motor with obsbot_tail2_focus position instead.`);
+                }
+                const r = await api.focusWindowSet(x, y);
+                return { ok: true, ...r, pointFocusStarted: true };
+            },
+        },
+        {
+            name: "obsbot_tail2_focus",
+            description: "Read (bare call) or set the Tail 2's focus: mode afc|afs|mf, and position (0-100, the " +
+                "focus motor) which is only valid in mf — the camera errors on it in afc/afs and this " +
+                "tool refuses rather than trigger that. Bare call reports the mode, and the position " +
+                "when in mf.",
+            schema: withCamera({
+                mode: z.enum(["afc", "afs", "mf"]).optional(),
+                position: num().pipe(z.number().min(0).max(100)).optional(),
+            }),
+            handler: async (args) => {
+                const { camera, mode, position } = withCamera({
+                    mode: z.enum(["afc", "afs", "mf"]).optional(),
+                    position: num().pipe(z.number().min(0).max(100)).optional(),
+                }).parse(args);
+                const { api } = await registry.resolve(camera);
+                const out = {};
+                if (mode !== undefined)
+                    Object.assign(out, await api.focusModeSet(mode));
+                const current = await api.focusModeGet();
+                if (position !== undefined) {
+                    if (current.mode !== "mf") {
+                        throw new Error(`focus position is only valid in mf (current: ${current.mode}). Set mode:"mf" first.`);
+                    }
+                    Object.assign(out, await api.focusPositionSet(position));
+                }
+                else if (current.mode === "mf") {
+                    // Readable only in mf (HTTP 500 otherwise — measured).
+                    out.position = (await api.focusPositionGet()).position;
+                }
+                return { mode: current.mode, ...out };
+            },
+        },
+        {
+            name: "obsbot_tail2_exposure",
+            description: "Read (bare call) or set the Tail 2's exposure. mode manual|auto; in AUTO: face " +
+                "(face-priority AE, global|face) and evbias (-3.0..3.0, ~0.3 steps); in MANUAL: iso " +
+                "(100-6400) and shutter (\"1/N\", 1/6400..1/30). Manual values only exist in manual mode " +
+                "and face/evbias only in auto — a bare call reports whichever set the current mode " +
+                "exposes. Note: the camera's manual ISO granularity is finer than the doc claims " +
+                "(a live-AE value like 894 reads back).",
+            schema: withCamera({
+                mode: z.enum(["manual", "auto"]).optional(),
+                face: bool().optional(),
+                evbias: num().pipe(z.number().min(-3).max(3)).optional(),
+                iso: num().pipe(z.number().min(100).max(6400)).optional(),
+                shutter: z.string().regex(/^1\/\d+$/).optional(),
+            }),
+            handler: async (args) => {
+                const schema = withCamera({
+                    mode: z.enum(["manual", "auto"]).optional(),
+                    face: bool().optional(),
+                    evbias: num().pipe(z.number().min(-3).max(3)).optional(),
+                    iso: num().pipe(z.number().min(100).max(6400)).optional(),
+                    shutter: z.string().regex(/^1\/\d+$/).optional(),
+                });
+                const { camera, mode, face, evbias, iso, shutter } = schema.parse(args);
+                const { api } = await registry.resolve(camera);
+                const out = {};
+                if (mode !== undefined)
+                    Object.assign(out, await api.exposureModeSet(mode));
+                if (face !== undefined)
+                    Object.assign(out, await api.exposureAutoModeSet(face ? "face" : "global"));
+                if (evbias !== undefined)
+                    Object.assign(out, await api.exposureEvbiasSet(evbias));
+                if (iso !== undefined)
+                    Object.assign(out, await api.exposureIsoSet(iso));
+                if (shutter !== undefined)
+                    Object.assign(out, await api.exposureShutterSet(shutter));
+                // Mode-appropriate reads (the other mode's values are gated off —
+                // HTTP 500 — so only what exists now is reported). The AE sub-mode's
+                // key is also "mode" — renamed so it cannot clobber the exposure mode.
+                const { mode: current } = await api.exposureModeGet();
+                const read = { mode: current };
+                if (current === "auto") {
+                    read.autoMode = (await api.exposureAutoModeGet()).mode;
+                    Object.assign(read, await api.exposureEvbiasGet());
+                }
+                else {
+                    Object.assign(read, await api.exposureIsoGet());
+                    Object.assign(read, await api.exposureShutterGet());
+                }
+                return { ...read, ...(Object.keys(out).length ? { applied: out } : {}) };
+            },
+        },
+        {
+            name: "obsbot_tail2_image_adjust",
+            description: "Read (bare call) or set the Tail 2's image style: brightness/contrast/hue/saturation/" +
+                "sharpness, each an absolute 0-100, plus styleMode standard|outdoor|pastel|manual. " +
+                "Individual control writes are MODE-GATED (measured): they apply only in styleMode " +
+                "manual — HTTP 500 \"style mode is not manual\" otherwise — so this tool applies a " +
+                "given styleMode FIRST and refuses a control write in a preset mode. A styleMode switch " +
+                "preserves the current values. Bare call returns the full style bundle.",
+            schema: withCamera({
+                control: z.enum(["brightness", "contrast", "hue", "saturation", "sharpness"]).optional(),
+                value: num().pipe(z.number().min(0).max(100)).optional(),
+                styleMode: z.enum(["standard", "outdoor", "pastel", "manual"]).optional(),
+            }),
+            handler: async (args) => {
+                const schema = withCamera({
+                    control: z.enum(["brightness", "contrast", "hue", "saturation", "sharpness"]).optional(),
+                    value: num().pipe(z.number().min(0).max(100)).optional(),
+                    styleMode: z.enum(["standard", "outdoor", "pastel", "manual"]).optional(),
+                });
+                const { camera, control, value, styleMode } = schema.parse(args);
+                if ((control === undefined) !== (value === undefined)) {
+                    throw new Error("control and value go together — give both or neither");
+                }
+                const { api } = await registry.resolve(camera);
+                const out = {};
+                if (styleMode !== undefined)
+                    Object.assign(out, await api.styleModeSet(styleMode));
+                if (control !== undefined && value !== undefined) {
+                    const { mode } = await api.styleGet();
+                    if (mode !== "manual") {
+                        throw new Error(`style writes apply only in styleMode manual (current: ${mode}). ` +
+                            `Pass styleMode:"manual" alongside, or switch first.`);
+                    }
+                    Object.assign(out, await api.styleSet(control, value));
+                }
+                return { ...await api.styleGet(), ...(Object.keys(out).length ? { applied: out } : {}) };
+            },
+        },
+        {
+            name: "obsbot_tail2_hdr",
+            description: "Read (bare call) or set (enabled) the Tail 2's HDR.",
+            schema: withCamera({ enabled: bool().optional() }),
+            handler: async (args) => {
+                const { camera, enabled } = withCamera({ enabled: bool().optional() }).parse(args);
+                const { api } = await registry.resolve(camera);
+                if (enabled === undefined)
+                    return await api.hdrGet();
+                const r = await api.hdrSet(enabled);
+                return { ok: true, ...r };
+            },
+        },
+        {
+            name: "obsbot_tail2_wb",
+            description: "Read (bare call) or set the Tail 2's white balance: mode auto|daylight|fluorescent|" +
+                "tungsten|cloudy|manual, plus temperature in Kelvin (2000-10000) which applies in " +
+                "manual mode.",
+            schema: withCamera({
+                mode: z.enum(["auto", "daylight", "fluorescent", "tungsten", "cloudy", "manual"]).optional(),
+                temperature: num().pipe(z.number().min(2000).max(10000)).optional(),
+            }),
+            handler: async (args) => {
+                const schema = withCamera({
+                    mode: z.enum(["auto", "daylight", "fluorescent", "tungsten", "cloudy", "manual"]).optional(),
+                    temperature: num().pipe(z.number().min(2000).max(10000)).optional(),
+                });
+                const { camera, mode, temperature } = schema.parse(args);
+                const { api } = await registry.resolve(camera);
+                if (mode === undefined && temperature === undefined)
+                    return await api.wbConfigGet();
+                const r = await api.wbConfigSet(mode ?? "manual", temperature);
+                return { ok: true, ...r };
+            },
+        },
+        {
+            name: "obsbot_tail2_stream",
+            description: "Read (bare call) or set the Tail 2's active network output: ndi|rtsp|srt|off — exactly " +
+                "ONE is active at a time (setting srt displaces ndi, and a camera reboot resets to off). " +
+                "This is the programmatic way to arm SRT for obsbot_tail2_snapshot without touching " +
+                "OBSBOT Center.",
+            schema: withCamera({ output: z.enum(["ndi", "rtsp", "srt", "off"]).optional() }),
+            handler: async (args) => {
+                const { camera, output } = withCamera({
+                    output: z.enum(["ndi", "rtsp", "srt", "off"]).optional(),
+                }).parse(args);
+                const { api } = await registry.resolve(camera);
+                if (output === undefined)
+                    return await api.streamControlGet();
+                const r = await api.streamControlSet(output);
+                return { ok: true, ...r };
+            },
+        },
+        {
+            name: "obsbot_tail2_only_me",
+            description: "Read (bare call) or set (enabled) the Tail 2's OnlyMe human-tracking switch — track " +
+                "only the nearest/locked person rather than reframing for everyone.",
+            schema: withCamera({ enabled: bool().optional() }),
+            handler: async (args) => {
+                const { camera, enabled } = withCamera({ enabled: bool().optional() }).parse(args);
+                const { api } = await registry.resolve(camera);
+                if (enabled === undefined)
+                    return await api.onlyMeGet();
+                const r = await api.onlyMeSet(enabled);
+                return { ok: true, ...r };
+            },
+        },
+        {
+            name: "obsbot_tail2_audio",
+            description: "Read (bare call) or set the Tail 2's audio input: volume 0-100 and mute. Changes apply " +
+                "to the encoded/recorded audio stream.",
+            schema: withCamera({
+                volume: num().pipe(z.number().min(0).max(100)).optional(),
+                mute: bool().optional(),
+            }),
+            handler: async (args) => {
+                const schema = withCamera({
+                    volume: num().pipe(z.number().min(0).max(100)).optional(),
+                    mute: bool().optional(),
+                });
+                const { camera, volume, mute } = schema.parse(args);
+                const { api } = await registry.resolve(camera);
+                const out = {};
+                if (volume !== undefined)
+                    Object.assign(out, await api.audioVolumeSet(volume));
+                if (mute !== undefined)
+                    Object.assign(out, await api.audioMuteSet(mute));
+                return {
+                    ...(await api.audioVolumeGet()),
+                    ...(await api.audioMuteGet()),
+                    ...(Object.keys(out).length ? { applied: out } : {}),
+                };
+            },
+        },
         {
             name: "obsbot_tail2_portrait",
             description: "Rotate a Tail 2's barrel 90° for portrait framing (enable) or back to landscape " +