obsbotd

Ein Linux-MCP-Daemon für OBSBOT-Tiny-Kameras. Ein Daemon besitzt die Kamera; jeder Agent – Claude Code, LibreChat, benutzerdefinierte Frameworks oder alles, was JSON POSTen kann – verbindet sich über streamable-http damit.

MCP clients (any framework, or bare curl)
        │  streamable-http  http://127.0.0.1:8626/mcp
        ▼
     obsbotd  ──►  V4L2/UVC ioctls (ctypes)   gimbal, zoom, focus, status
              ──►  vendor XU protocol         wake/sleep, AI tracking, exposure
              ──►  ffmpeg                     snapshots (validated), clips, preview

Warum dies existiert

Das Upstream-Paket obsbot-mcp (npm) hat den schwierigen Teil erledigt – das Reverse-Engineering des Herstellerprotokolls und die Kalibrierung der Optik –, aber seine Architektur (ein stdio-MCP-Server pro Agentensitzung, ein vorkompiliertes natives Hilfsprogramm, Single-Owner-IPC-Wahl zwischen Sitzungen) verursachte chronische operative Probleme auf einer Linux-Maschine mit mehreren Agenten: veraltete Owner-Prozesse, die Wochen alte Codeversionen bedienten, unvalidierte, abgeschnittene Frames und eine geschlossene Binärdatei, in der die Fehler lebten.

obsbotd behält das Protokollwissen und verwirft die Architektur:

• Ein Daemon, viele Clients. Keine Wahlen, keine Sitzungsprozesse, keine veralteten Owner. Läuft als systemd-Benutzerdienst.

• Kein natives Binärprogramm. Die V4L2/UVC-Schicht umfasst ~200 Zeilen ctypes; ioctl-Nummern werden aus Strukturgrößen berechnet, sodass ein Layoutfehler laut scheitert.

• Hotplug ist kostenlos. Zwischen Aufrufen wird kein Gerätehandle gehalten – jeder Tool-Aufruf entdeckt /dev/video* neu (submilibisekunde). Das Abziehen der Kamera liefert als normales Ergebnis {"ok": false, "camera_present": false}; der nächste Aufruf nach einem Wiederanschließen funktioniert einfach.

• Frames werden validiert. Die Kamera sendet sporadisch abgeschnittene MJPEG-Frames, am schlimmsten direkt nach dem Aufwachen. Jede Momentaufnahme ist ein stream-copierter Rohframe, der auf vollständiges SOI..EOI geprüft, bis zu 4x wiederholt und dann optional herunterskaliert wird (Standard 640 px – Momentaufnahme-Pixel sind LLM-Tokens).

• Ehrliche Fehler. Jeder Fehler ist ein strukturiertes {ok: false, error}, auf das ein Agent reagieren kann – niemals eine undurchsichtige Tool-Ausnahme. Verweigerungsmeldungen sagen, was stattdessen zu tun ist.

• Atomares Schwenken/Neigen. Beide Achsen in einem VIDIOC_S_EXT_CTRLS – uvcvideo's Per-Control-Read-Modify-Write würde sonst die Hälfte der Bewegung aufheben.

• Vermessene Optik. obsbot_aim_at_pixel / obsbot_zoom_to_fit führen visuelles Servoing mit dem intrinsisch gelösten FOV-Modell durch (67° breites HFOV, 0,957 vertikale Korrektur, Vergrößerung = 3·Verhältnis − 2) und zusammengesetzte Rotationszielung, die von der Kalibrierungsarbeit des Upstreams übernommen wurde.

Hardwareunterstützung

Entwickelt und hardware-verifiziert gegen eine OBSBOT Tiny 2 Lite unter Linux (Kernel uvcvideo). Die Tiny 2 teilt sich das Herstellerprotokoll und sollte unverändert funktionieren; andere OBSBOT-Modelle sind ungetestet. Eine Kamera pro Host.

Bekannte Kernel-Einschränkung: uvcvideo cached CT_PANTILT_ABSOLUTE, daher ist die Gimbal-Rücklesung die zuletzt befohlene Pose, nicht live – die Werkzeuge sind entsprechend gekennzeichnet, und der vorgesehene Arbeitsablauf überprüft die Ausrichtung visuell.

Installation

Erfordert Python ≥ 3.12, ffmpeg (und ffplay für das Vorschaufenster) sowie Lese-/Schreibzugriff auf den /dev/video*-Knoten der Kamera (die video-Gruppe).

git clone https://github.com/LumenPrima/obsbotd ~/obsbotd
cd ~/obsbotd
uv venv && uv pip install -e .        # or: python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m obsbotd.server    # listens on 127.0.0.1:8626

Als Dienst:

cp systemd/obsbotd.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now obsbotd
loginctl enable-linger $USER          # optional: run without an active login

OBSBOTD_HOST / OBSBOTD_PORT überschreiben die Bindungsadresse. Die Voreinstellung ist nur localhost, und es gibt keine Authentifizierung – binden Sie es nicht an eine erreichbare Schnittstelle, es sei denn, Sie verstehen, dass jeder, der den Port erreichen kann, die Kamera steuern und Bilder aufnehmen kann.

Agent verbinden

MCP-native Konfiguration (Claude Code, die meisten Frameworks):

{ "mcpServers": { "obsbot": { "type": "http", "url": "http://127.0.0.1:8626/mcp" } } }

Keine MCP-Bibliothek? Der Server antwortet auf einfache JSON-RPC-POSTs mit plain JSON – ein einfacher Agent kann ihn mit curl steuern. docs/AGENT-GUIDE.md enthält die vollständige Integrationsanleitung, die Referenz der 18 Werkzeuge und die Regeln für das Engagement (keine Schlafbefehle, Bewegung visuell überprüfen, Verweigerungen als Anweisungen behandeln).

Werkzeuge (18)

obsbot_snapshot · obsbot_status · obsbot_wake · obsbot_sleep · obsbot_gimbal_move · obsbot_gimbal_recenter · obsbot_gimbal_position · obsbot_zoom · obsbot_aim_at_pixel · obsbot_zoom_to_fit · obsbot_ai_track · obsbot_ai_track_speed · obsbot_focus · obsbot_exposure · obsbot_image_adjust · obsbot_image_mode · obsbot_record_clip · obsbot_preview

Protokolldokumentation

docs/spec-*.md ist eine vollständige schriftliche Spezifikation des Hersteller-Drahtprotokolls (60-Byte-V3-Frames, CRC-16/USB, Opcode-Tabellen, der 60-Byte-Statusblock, Selektor-Map) und der vermessenen Optik – extrahiert aus dem Quellcode des Upstreams als Referenz für die Neuimplementierung und auch für sich allein nützlich für jeden, der diese Kameras ansteuert. Die Drahtschicht ist golden gegen die exakten Frame-Bytes des Upstreams getestet (tests/).

Tests

tests/ sind hardwarefrei: .venv/bin/python -m pytest tests/ -q

Danksagungen

Das Reverse-Engineering des Herstellerprotokolls, der Katalog der Hardware-Besonderheiten und die optische Kalibrierung stammen alle von obsbot-mcp (MIT, © 2026 Michael Jordan). obsbotd ist eine unabhängige Linux-native Neuimplementierung der Serving-Architektur rund um dieses Wissen.

Lizenz

MIT – siehe LICENSE.