Skip to content

Latest commit

 

History

History
113 lines (83 loc) · 4.55 KB

CLAUDE.md

File metadata and controls

113 lines (83 loc) · 4.55 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MatchBox is a Python desktop application that automates OBS scene switching and match video clipping for FIRST Tech Challenge (FTC) robotics events. It connects to the FTC scoring system via WebSocket, controls OBS via WebSocket, and serves clipped match videos via HTTP with mDNS discovery.

Commands

Install dependencies:

pip install -r requirements.txt

Run the GUI application:

python matchbox.py

Run in CLI mode:

python matchbox-cli.py --ftc-host <host> --event-code <code>

Build standalone executables:

python build.py

Note: There is no test suite.

Type checking:

basedpyright matchbox.py matchbox-cli.py matchbox-sync.py build.py web_api/ local_video_processor.py

The project uses basedpyright in strict mode. When writing or modifying code:

  • Avoid Any types — use object, dict[str, object], or cast() instead
  • Annotate class attributes, function parameters, and return types
  • Use _ = for intentionally unused call results
  • Prefix unused variables with _ (e.g., _dirs)
  • Use from __future__ import annotations with TYPE_CHECKING imports to avoid circular imports at runtime

Architecture

Core Components

matchbox.py - Main application containing:

  • MatchBoxConfig - Configuration dataclass for all settings
  • MatchBoxCore - Application controller handling WebSocket connections, OBS control, and video processing orchestration
  • MatchBoxGUI - Tkinter GUI with sv-ttk theming

matchbox-cli.py - Command-line interface alternative to the GUI

matchbox-sync.py - Standalone rsync daemon for syncing match clips to a remote server

local_video_processor.py - Video clipping engine that uses ffmpeg subprocess calls to extract match segments from OBS recordings

web_api/ - Web server components:

  • handler.py - HTTP request handler with REST API routes, admin UI static file serving, and session-cookie authentication
  • websocket_server.py - WebSocket server for real-time log streaming, status updates, and OBS WebSocket proxy
  • ws_tunnel_client.py - WebSocket tunnel client that connects to a relay server for remote access

web_admin/ - Static HTML/CSS/JS for the browser-based admin dashboard (served by handler.py at /admin/)

pi-server/relay_server.py - Relay server (designed to run on a VPS/Pi) that bridges remote browser clients to MatchBox instances via WebSocket tunneling

Data Flow

FTC Scoring WebSocket → MatchBoxCore → OBS Scene Switch
                              ↓
                     Match Start Event
                              ↓
                  LocalVideoProcessor (delayed)
                              ↓
                     ffmpeg Clip Extraction
                              ↓
                   match_clips/<event_code>/
                              ↓
                   HTTP Server (mDNS: ftcvideo.local)

Threading Model

  • Main thread: Tkinter GUI event loop
  • Background thread: asyncio event loop for WebSocket monitoring
  • Web server: ThreadingHTTPServer with multi-threaded request handling
  • WebSocket server: Separate daemon thread with its own asyncio event loop
  • mDNS: Separate daemon thread for Zeroconf registration

Web Admin & Remote Access

  • Local access: Admin UI served at /admin/, API at /api/, clip downloads at /
  • Remote access: WS tunnel client connects to relay server; relay proxies HTTP/WS requests back through the tunnel
  • Authentication: HMAC-signed session cookies (mb_session), 24h expiry. Two-tier: instance password (per-instance) and admin password (hardcoded hash via ADMIN_SALT/ADMIN_HASH). Localhost requests bypass auth (for tunnel-proxied requests).
  • WebSocket paths: /ws/logs (log streaming), /ws/status (status updates), /ws/obs (OBS WebSocket proxy)

Key Technical Details

  • Uses obs-websocket-py for OBS control with fallback methods for older API versions
  • Custom HTTP handler implements Range requests for progressive video playback
  • Configuration stored as JSON (matchbox_config.json) with CLI args taking priority
  • Version derived from git tags via setuptools-scm
  • Admin password hash generated via generate_admin_hash.py

Build System

PyInstaller builds configured in matchbox.spec:

  • Downloads platform-specific ffmpeg binaries automatically
  • Produces standalone executables for Windows, macOS, and Linux
  • CI/CD via GitHub Actions (.github/workflows/pyinstaller.yml)