obsbot-mcp 0.7.0 → 0.9.0

package/dist/tail2/api.d.ts

@@ -0,0 +1,381 @@
+/**
+ * HTTP/WS client for the OBSBOT Tail 2 control API.
+ *
+ * The Tail 2's network control plane is a lighttpd REST API plus a WebSocket
+ * status push (see TAIL2-PROTOCOL.md). Its USB-C UVC mode has a control
+ * surface of its own (§11) that this client does not use.
+ * Everything here is plain HTTP and therefore platform-independent: the same
+ * code runs on Windows, Linux and macOS with no native helper, which is the
+ * whole reason this module exists as a separate family from the Tiny 2's
+ * helper-process transports.
+ *
+ * Identity is the camera's MAC (what OBSBOT Center keys on); device_name and
+ * any of its IPs are accepted as selectors one level up, in the registry.
+ */
+/** `GET /camera/sdk/device_info` — the probe target and identity source. */
+export interface Tail2DeviceInfo {
+    device_name: string;
+    wired_ip: string;
+    wireless_ip: string;
+    mac: string;
+}
+/**
+ * One push from `ws://<host>/ws/`. The camera sends the FULL status block
+ * ~1 Hz with no subscription message. Fields the tools rely on are typed;
+ * the block carries more (and firmware may add some) — unknown fields pass
+ * through untouched via the index signature.
+ *
+ * MEASURED 2026-09-26 against firmware 7.2.13.1; see TAIL2-PROTOCOL.md §4.
+ */
+export interface Tail2Status {
+    [key: string]: unknown;
+    power_on?: boolean;
+    usb_mode?: number;
+    rec?: boolean;
+    rec_time?: number;
+    switch_portrait?: boolean;
+    ai_mode?: string;
+    zoom_ratio?: number;
+    roll_bias?: number;
+    focus_mode?: string;
+    auto_focus_mode?: string;
+    ndi?: {
+        enable?: boolean;
+    };
+    rtsp?: {
+        enable?: boolean;
+    };
+    srt?: {
+        enable?: boolean;
+    };
+    rtmp?: {
+        enable?: boolean;
+    };
+    preset_info?: Array<{
+        id: number;
+        pitch: number;
+        yaw: number;
+        roll: number;
+        ratio: number;
+        name: string;
+    }>;
+    device_status?: Record<string, unknown>;
+}
+/** A saved gimbal pose: degrees + zoom ratio. Names are base64 on the wire only. */
+export interface Preset {
+    id: number;
+    pitch: number;
+    yaw: number;
+    roll: number;
+    ratio: number;
+    name: string;
+}
+/** A live gimbal pose in degrees, plus the zoom ratio the pose read carries. */
+export interface Pose {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    ratio: number;
+}
+export declare class Tail2HttpError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly body: string;
+    constructor(status: number, path: string, body: string);
+}
+/**
+ * `{"code":200,"err_idx":0}` means ACKNOWLEDGED, not applied — MEASURED
+ * 2026-09-26: a rollbias write returned 200 while the portrait motor was in
+ * motion and never landed (TAIL2-PROTOCOL.md §8.1). This is the same failure
+ * class as the Tiny 2's post-replug vendor mailbox, so every setter here
+ * verifies by readback before reporting success, with a bounded retry ladder
+ * sized for the actuator involved (the zoom motor and the portrait rotation
+ * take seconds, not milliseconds).
+ */
+export interface VerifyOpts {
+    attempts?: number;
+    delayMs?: number;
+}
+export declare class Tail2Api {
+    readonly baseUrl: string;
+    private readonly timeoutMs;
+    private readonly wsUrl;
+    constructor(opts: {
+        baseUrl: string;
+        timeoutMs?: number;
+    });
+    private req;
+    /**
+     * PUT/POST with ack checking. `body` may be an object (JSON.stringify'd)
+     * or a pre-built JSON string — evbias needs a float literal like `0.0`
+     * that stringifying a number cannot produce (measured 2026-09-30: JSON
+     * integers 0 and -1 get 400 "Invalid value type"; 0.0 and -1.0 apply).
+     */
+    private send;
+    /**
+     * Read `read()` until `match()` holds, on a bounded ladder. Returns
+     * `settled:false` (NOT a throw) when the ladder runs out — the command was
+     * sent and acknowledged, so the caller decides whether that is failure.
+     * Mirrors `obsbot_zoom_uvc`'s `settled` contract.
+     */
+    verified<T>(read: () => Promise<T>, match: (v: T) => boolean, opts?: VerifyOpts): Promise<{
+        settled: boolean;
+        value: T;
+    }>;
+    info(): Promise<Tail2DeviceInfo>;
+    /** One-shot status: connect, take the first push, close. No persistent socket. */
+    status(): Promise<Tail2Status>;
+    ranges(): Promise<Record<string, unknown>>;
+    networkConfig(): Promise<Record<string, unknown>>;
+    imageState(): Promise<Record<string, unknown>>;
+    zoomGet(): Promise<{
+        ratio: number;
+    }>;
+    /**
+     * Absolute zoom ratio on the Tail 2's own 1.0–12.0 scale (`GET range`).
+     * `speed` is REQUIRED by the firmware (a ratio-only PUT is a 400) — both
+     * fields MEASURED 2026-09-26.
+     */
+    zoomSet(ratio: number, speed: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        ratio: number;
+    }>;
+    /** Gimbal recenter (`POST ptz/reset`). Open-loop: the Tail 2 reports no live pose. */
+    recenter(): Promise<void>;
+    gimbalSpeed(yaw: number, pitch: number, roll: number): Promise<void>;
+    gimbalStop(): Promise<void>;
+    gimbalInvertGet(): Promise<{
+        enable: boolean;
+    }>;
+    /** Reverse (invert) control directions. Readback-verified like every write. */
+    gimbalInvertSet(enable: boolean, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        enable: boolean;
+    }>;
+    /** Marker name for pose-probe scratch slots, so crashed probes are reusable. */
+    static readonly POSE_PROBE_NAME = "pose-probe";
+    readPose(verify?: VerifyOpts): Promise<Pose>;
+    /**
+     * Motorized 90° barrel rotation. Verified against the WS push rather than a
+     * REST readback (none exists) — and the readback MUST be tolerant of the
+     * motor taking ~1.5s, plus the swallowed-write hazard during motion.
+     */
+    portraitSet(enable: boolean, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        switch_portrait: boolean;
+    }>;
+    rollBiasGet(): Promise<{
+        angle: number;
+    }>;
+    /** Roll trim in degrees. MEASURED write + readback 2026-09-26. */
+    rollBiasSet(angle: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        angle: number;
+    }>;
+    aiModeGet(): Promise<{
+        mode: string;
+    }>;
+    /**
+     * `mode` strings are the camera's own enum (bundle-verified, TAIL2-PROTOCOL
+     * §3): none | humanTrackingSingleMode | humanTrackingGroupMode |
+     * animalTrackingNormal | animalTrackingCloseUp | objectTracking |
+     * objectTrackingNormal | objectTrackingCloseUp.
+     */
+    aiModeSet(mode: string, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        mode: string;
+    }>;
+    trackSpeedGet(): Promise<{
+        speed: string;
+    }>;
+    /**
+     * The Tail 2's own six-speed enum (bundle-verified): superLazy | lazy |
+     * slow | fast | crazy | customized. NOT the Tiny 2's standard/sport pair.
+     */
+    trackSpeedSet(speed: string, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        speed: string;
+    }>;
+    recordGet(): Promise<{
+        recording: "on" | "off";
+    }>;
+    recordSet(on: boolean, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        recording: "on" | "off";
+    }>;
+    /** Still-photo trigger. Needs storage; the ack says the camera accepted it. */
+    captureTrigger(): Promise<void>;
+    focusModeGet(): Promise<{
+        mode: "afc" | "afs" | "mf";
+    }>;
+    focusModeSet(mode: "afc" | "afs" | "mf", verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        mode: "afc" | "afs" | "mf";
+    }>;
+    focusPositionGet(): Promise<{
+        position: number;
+    }>;
+    focusPositionSet(position: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        position: number;
+    }>;
+    focusWindowGet(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /** Move the focus window AND start a point focus (per the vendor doc). AFC/AFS only. */
+    focusWindowSet(x: number, y: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Tap-to-track (MEASURED 2026-09-30, undocumented in the Tail 2's own doc):
+     * POST a normalized coordinate and the camera engages tracking on the
+     * subject there — from mode none it armed humanTrackingSingleMode on its
+     * own. Fire-and-ack; which mode engages depends on what (if anything) is
+     * at the coordinate, so the caller reads ai mode back when it matters.
+     */
+    targetSelect(x: number, y: number): Promise<void>;
+    exposureModeGet(): Promise<{
+        mode: "manual" | "auto";
+    }>;
+    exposureModeSet(mode: "manual" | "auto", verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        mode: "manual" | "auto";
+    }>;
+    exposureAutoModeGet(): Promise<{
+        mode: "global" | "face";
+    }>;
+    exposureAutoModeSet(mode: "global" | "face", verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        mode: "global" | "face";
+    }>;
+    exposureEvbiasGet(): Promise<{
+        evbias: number;
+    }>;
+    exposureEvbiasSet(evbias: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        evbias: number;
+    }>;
+    exposureIsoGet(): Promise<{
+        iso: number;
+    }>;
+    exposureIsoSet(iso: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        iso: number;
+    }>;
+    exposureShutterGet(): Promise<{
+        shutter: string;
+    }>;
+    exposureShutterSet(shutter: string, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        shutter: string;
+    }>;
+    styleGet(): Promise<{
+        mode: string;
+        brightness: number;
+        contrast: number;
+        hue: number;
+        saturation: number;
+        sharpness: number;
+    }>;
+    styleSet(control: "brightness" | "contrast" | "hue" | "saturation" | "sharpness", value: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        value: number;
+        mode: string;
+    }>;
+    styleModeSet(mode: "standard" | "outdoor" | "pastel" | "manual", verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        mode: string;
+    }>;
+    hdrGet(): Promise<{
+        control: "on" | "off";
+    }>;
+    hdrSet(on: boolean, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        control: "on" | "off";
+    }>;
+    wbConfigGet(): Promise<{
+        mode: string;
+        temperature: number;
+    }>;
+    wbConfigSet(mode: "auto" | "daylight" | "fluorescent" | "tungsten" | "cloudy" | "manual", temperature: number | undefined, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        mode: string;
+        temperature: number;
+    }>;
+    streamControlGet(): Promise<{
+        control: "ndi" | "rtsp" | "srt" | "off";
+    }>;
+    streamControlSet(control: "ndi" | "rtsp" | "srt" | "off", verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        control: "ndi" | "rtsp" | "srt" | "off";
+    }>;
+    onlyMeGet(): Promise<{
+        enable: boolean;
+    }>;
+    onlyMeSet(enable: boolean, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        enable: boolean;
+    }>;
+    audioVolumeGet(): Promise<{
+        volume: number;
+    }>;
+    audioVolumeSet(volume: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        volume: number;
+    }>;
+    audioMuteGet(): Promise<{
+        enable: boolean;
+    }>;
+    audioMuteSet(enable: boolean, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        enable: boolean;
+    }>;
+    /**
+     * A saved pose: angles in DEGREES plus zoom ratio — the same units the
+     * tools speak. `name` is base64 on the wire; encode/decode lives here so
+     * callers never see it raw.
+     */
+    presetsGet(): Promise<Preset[]>;
+    /**
+     * `PUT ptz/preset {"operation": ..., "id": ..., "name": base64}` — one
+     * endpoint, four operations (grammar decoded from the camera's own web
+     * bundle and hardware-verified 2026-09-26; see TAIL2-PROTOCOL.md §3).
+     * IDs are 0-based (0–2); the tools expose 1-based slots for consistency
+     * with the Tiny 2's preset tools.
+     *
+     * `set` saves the CURRENT live pose — there is NO explicit-pose write
+     * anywhere in this API (measured), and `set` on an occupied slot
+     * OVERWRITES it (unlike the Tiny 2's create-once slots).
+     */
+    private presetOp;
+    /**
+     * Save the current live pose into slot `id`. The preset LIST lags the
+     * write by up to ~1s (measured), so verification is a ladder, and the
+     * pose itself can't be verified at all — the camera reports no live pose,
+     * so "the slot exists afterwards" is the honest success criterion.
+     */
+    presetSave(id: number, name: string, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        presets: Preset[];
+    }>;
+    /**
+     * Recall slot `id`. Physical arrival is verifiable through exactly one
+     * observable: the preset's zoom ratio landing in the live zoom_ratio (the
+     * WS push carries it). The gimbal axes themselves are open-loop.
+     */
+    presetRecall(id: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        zoom: number;
+    }>;
+    presetDelete(id: number, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        presets: Preset[];
+    }>;
+    presetRename(id: number, name: string, verify?: VerifyOpts): Promise<{
+        settled: boolean;
+        presets: Preset[];
+    }>;
+}