obsbotd

Демон MCP для Linux, предназначенный для камер серии OBSBOT Tiny. Один демон владеет камерой; каждый агент — Claude Code, LibreChat, пользовательские фреймворки или любой другой инструмент, способный отправлять POST-запросы с JSON, — подключается к нему через 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

Зачем это нужно

Пакет obsbot-mcp из репозитория npm выполнил сложную работу — обратную разработку вендорского протокола и калибровку оптики, — но его архитектура (stdio MCP-сервер для каждого сеанса агента, предварительно собранный вспомогательный бинарник, выбор единственного владельца через IPC между сеансами) вызывала хронические эксплуатационные проблемы на многоагентной Linux-машине: устаревшие процессы-владельцы, выполняющие код недельной давности, непроверенные усеченные кадры и закрытый бинарник, в котором жили баги.

obsbotd сохраняет знания о протоколе и отбрасывает архитектуру:

• Один демон, много клиентов. Никаких выборов, никаких процессов на сеанс, никаких устаревших владельцев. Запускается как пользовательский сервис systemd.

• Никакого нативного бинарника. Слой V4L2/UVC — это ~200 строк ctypes; номера ioctl вычисляются на основе размеров структур, так что ошибка в компоновке приводит к громкому сбою.

• Поддержка горячего подключения бесплатна. Ни один дескриптор устройства не удерживается между вызовами — каждый вызов инструмента заново обнаруживает /dev/video* (субмиллисекундно). Отключение камеры возвращает {"ok": false, "camera_present": false} как нормальный результат; следующий вызов после повторного подключения просто работает.

• Кадры проверяются. Камера спорадически выдает усеченные кадры MJPEG, особенно сразу после пробуждения. Каждый снимок — это скопированный потоком сырой кадр, проверенный на наличие полного SOI..EOI, с повторными попытками до 4 раз, а затем опционально масштабированный (по умолчанию 640 px — пиксели снимка — это токены LLM).

• Честные ошибки. Каждый сбой — это структурированный ответ {ok: false, error}, на который агент может реагировать, — никогда не непрозрачное исключение инструмента. Сообщения об отказе объясняют, что делать вместо этого.

• Атомарные панорамирование и наклон. Обе оси в одном вызове VIDIOC_S_EXT_CTRLS — в противном случае периодическое чтение-модификация-запись uvcvideo отменяет половину движения.

• Измеренная оптика. obsbot_aim_at_pixel / obsbot_zoom_to_fit выполняют визуальное сервирование с использованием модели поля зрения (67° широкое горизонтальное поле, 0.957 вертикальная коррекция, magnification = 3·ratio − 2) и прицеливания с составным вращением, унаследованного от калибровочной работы вышестоящего проекта.

Поддержка оборудования

Разработано и проверено на оборудовании с OBSBOT Tiny 2 Lite на Linux (ядро uvcvideo). Tiny 2 использует тот же вендорский протокол и должен работать без изменений; другие модели OBSBOT не тестировались. Одна камера на хост.

Известное ограничение ядра: uvcvideo кэширует CT_PANTILT_ABSOLUTE, поэтому обратное чтение карданного подвеса — это последняя скомандованная поза, а не текущая — инструменты помечены соответствующим образом, и предполагаемый рабочий процесс проверяет наводку визуально.

Установка

Требуется Python ≥ 3.12, ffmpeg (и ffplay для окна предварительного просмотра), а также права на чтение и запись к узлу /dev/video* камеры (группа 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

Как сервис:

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 переопределяют адрес привязки. По умолчанию используется только localhost, и аутентификация отсутствует — не привязывайте его к доступному интерфейсу, если вы не понимаете, что любой, кто может добраться до порта, может управлять камерой и делать снимки.

Подключение агента

Конфигурация для MCP (Claude Code, большинство фреймворков):

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

Нет библиотеки MCP? Сервер отвечает на простые POST-запросы JSON-RPC обычным JSON — наивный агент может управлять им с помощью curl. docs/AGENT-GUIDE.md содержит полное руководство по интеграции, справочник по 18 инструментам и правила взаимодействия (никаких ожиданий, проверяйте движение визуально, относитесь к отказам как к инструкциям).

Инструменты (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

Документация протокола

docs/spec-*.md — это полная письменная спецификация вендорского проводного протокола (60-байтовые кадры V3, CRC-16/USB, таблицы кодов операций, 60-байтовый блок состояния, карта селекторов) и измеренная оптика — извлечено из исходного кода вышестоящего проекта в качестве эталона для повторной реализации и полезно само по себе для всех, кто управляет этими камерами. Проводной уровень проходит золотое тестирование на точных байтах кадров вышестоящего проекта (tests/).

Тесты

tests/ не требуют оборудования: .venv/bin/python -m pytest tests/ -q

Благодарности

Обратная разработка вендорского протокола, каталог аппаратных особенностей и оптическая калибровка взяты из obsbot-mcp (MIT, © 2026 Michael Jordan). obsbotd — это независимая нативная для Linux повторная реализация серверной архитектуры на основе этих знаний.

Лицензия

MIT — см. LICENSE.