obsbotd

OBSBOT Tiny 시리즈 카메라를 위한 Linux MCP 데몬입니다. 하나의 데몬이 카메라를 소유하며, 모든 에이전트(Claude Code, LibreChat, 사용자 정의 프레임워크, 또는 JSON POST가 가능한 모든 것)는 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*를 다시 발견합니다(1밀리초 미만). 카메라를 분리하면 정상 결과로 {"ok": false, "camera_present": false}가 반환됩니다. 다시 연결한 후의 다음 호출은 정상 작동합니다.

• 프레임이 검증됩니다. 카메라는 간헐적으로 잘린 MJPEG 프레임을 방출하며, 특히 깨어난 직후에 심합니다. 모든 스냅샷은 완전한 SOI..EOI가 확인된 스트림 복사 원시 프레임이며, 최대 4회 재시도한 후 선택적으로 다운스케일됩니다(기본값 640px — 스냅샷 픽셀은 LLM 토큰입니다).

• 정직한 오류. 모든 실패는 에이전트가 조치할 수 있는 구조화된 {ok: false, error}입니다. 불투명한 도구 예외가 아닙니다. 거부 메시지는 대신 수행할 작업을 알려줍니다.

• 원자적 pan+tilt. 두 축이 하나의 VIDIOC_S_EXT_CTRLS에서 처리됩니다. 그렇지 않으면 uvcvideo의 제어별 읽기-수정-쓰기가 이동의 절반을 취소합니다.

• 측정된 광학. obsbot_aim_at_pixel / obsbot_zoom_to_fit은 내부 매개변수가 해결된 FOV 모델(67° 광각 HFOV, 0.957 수직 보정, 배율 = 3·비율 − 2)과 상위의 보정 작업에서 상속된 합성 회전 조준을 사용하여 시각적 서보잉을 수행합니다.

하드웨어 지원

Linux(커널 uvcvideo)에서 OBSBOT Tiny 2 Lite에 대해 개발 및 하드웨어 검증되었습니다. 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 라이브러리가 없나요? 서버는 일반 JSON-RPC POST에 일반 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, opcode 테이블, 60바이트 상태 블록, 선택기 맵) 및 측정된 광학에 대한 완전한 서면 사양입니다. 상위 소스에서 재구현 참조로 추출되었으며, 이 카메라를 구동하는 모든 사람에게 그 자체로 유용합니다. 유선 계층은 상위의 정확한 프레임 바이트(tests/)에 대해 골든 테스트되었습니다.

테스트

tests/는 하드웨어가 필요 없습니다: .venv/bin/python -m pytest tests/ -q

크레딧

벤더 프로토콜 리버스 엔지니어링, 하드웨어 결함 카탈로그 및 광학 보정은 모두 obsbot-mcp(MIT, © 2026 Michael Jordan)에서 비롯되었습니다. obsbotd는 해당 지식을 기반으로 한 서빙 아키텍처의 독립적인 Linux 네이티브 재구현입니다.

라이선스

MIT — LICENSE 참조.