obsbotd

Un demonio MCP para Linux para las cámaras OBSBOT Tiny-series. Un demonio posee la cámara; cada agente — Claude Code, LibreChat, frameworks personalizados, o cualquier cosa que pueda hacer POST JSON — se conecta a él a través de streamable-http.

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

Por qué existe esto

El paquete npm upstream obsbot-mcp hizo la parte difícil — ingeniería inversa del protocolo del proveedor y calibración de la óptica — pero su arquitectura (un servidor MCP stdio por sesión de agente, un binario auxiliar nativo precompilado, elección IPC de propietario único entre sesiones) produjo un dolor operativo crónico en una máquina Linux multiagente: procesos propietarios obsoletos sirviendo código de semanas de antigüedad, fotogramas truncados no validados y un binario cerrado donde vivían los errores.

obsbotd conserva el conocimiento del protocolo y descarta la arquitectura:

• Un demonio, muchos clientes. Sin elecciones, sin procesos por sesión, sin propietarios obsoletos. Se ejecuta como un servicio de usuario systemd.

• Sin binario nativo. La capa V4L2/UVC tiene ~200 líneas de ctypes; los números ioctl se calculan a partir de los tamaños de las estructuras, por lo que un error de diseño falla ruidosamente.

• Hotplug gratuito. No se mantiene ningún identificador de dispositivo entre llamadas — cada llamada de herramienta redescubre /dev/video* (sub-milisegundo). Desconectar la cámara produce {"ok": false, "camera_present": false} como resultado normal; la siguiente llamada después de reconectar simplemente funciona.

• Los fotogramas se validan. La cámara emite esporádicamente fotogramas MJPEG truncados, peor justo después de despertar. Cada instantánea es un fotograma bruto copiado en flujo verificado para un SOI..EOI completo, reintentado hasta 4 veces, luego opcionalmente reducido (por defecto 640 px — los píxeles de instantánea son tokens LLM).

• Errores honestos. Cada fallo es un {ok: false, error} estructurado sobre el que un agente puede actuar — nunca una excepción de herramienta opaca. Los mensajes de rechazo dicen qué hacer en su lugar.

• Pan+inclinación atómicos. Ambos ejes en un solo VIDIOC_S_EXT_CTRLS — de lo contrario, la lectura-modificación-escritura por control de uvcvideo cancela la mitad del movimiento.

• Óptica medida. obsbot_aim_at_pixel / obsbot_zoom_to_fit realizan servovisión con el modelo FOV resuelto por intrínsecos (67° HFOV ancho, corrección vertical 0.957, magnificación = 3·ratio − 2) y apuntado por rotación compuesta heredado del trabajo de calibración upstream.

Soporte de hardware

Desarrollado y verificado con hardware contra un OBSBOT Tiny 2 Lite en Linux (kernel uvcvideo). El Tiny 2 comparte el protocolo del proveedor y debería funcionar sin cambios; otros modelos OBSBOT no han sido probados. Una sola cámara por host.

Limitación conocida del kernel: uvcvideo almacena en caché CT_PANTILT_ABSOLUTE, por lo que la lectura del gimbal es la pose comandada más reciente, no en vivo — las herramientas están etiquetadas en consecuencia, y el flujo de trabajo previsto verifica la orientación visualmente.

Instalación

Requiere Python ≥ 3.12, ffmpeg (y ffplay para la ventana de vista previa), y acceso de lectura/escritura al nodo /dev/video* de la cámara (el grupo video).

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

Como servicio:

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 anulan la dirección de enlace. El valor predeterminado es solo localhost y no hay autenticación — no lo enlace a una interfaz accesible a menos que entienda que cualquiera que pueda alcanzar el puerto puede manejar la cámara y tomar fotos.

Conectar un agente

Configuración nativa MCP (Claude Code, la mayoría de los frameworks):

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

¿Sin biblioteca MCP? El servidor responde a POSTs JSON-RPC simples con JSON plano — un agente ingenuo puede manejarlo con curl. docs/AGENT-GUIDE.md tiene la guía de integración completa, la referencia de las 18 herramientas y las reglas de enfrentamiento (sin esperas, verificar movimiento visualmente, tratar los rechazos como instrucciones).

Herramientas (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

Documentación del protocolo

docs/spec-*.md es una especificación escrita completa del protocolo de cable del proveedor (tramas V3 de 60 bytes, CRC-16/USB, tablas de códigos de operación, el bloque de estado de 60 bytes, mapa de selectores) y la óptica medida — extraída del código fuente upstream como referencia de reimplementación, y útil por sí misma para cualquiera que maneje estas cámaras. La capa de cable se prueba con oro contra los bytes exactos de trama upstream (tests/).

Pruebas

tests/ no requieren hardware: .venv/bin/python -m pytest tests/ -q

Créditos

La ingeniería inversa del protocolo del proveedor, el catálogo de peculiaridades del hardware y la calibración óptica provienen de obsbot-mcp (MIT, © 2026 Michael Jordan). obsbotd es una reimplementación independiente nativa de Linux de la arquitectura de servicio alrededor de ese conocimiento.

Licencia

MIT — consulte LICENSE.