OBS Camera Controller for DroidCam

A desktop controller that turns one stationary DroidCam phone into a multi-angle virtual camera, driven from the laptop. Zoom, pan and jump between framings without touching the phone — built for streaming to YouTube in 16:9 and TikTok in 9:16 from the same physical setup.

Highlights

• The camera moves because the canvas is smaller than the source — OBS is configured with a 960×540 base canvas scaled to a 1280×720 output. The crop-and-transform headroom that difference creates is exactly what pan and zoom operate on, so the "virtual camera" is geometry, not a second physical device.
• Output resolution is a deliberate choice, not a default — setting the scaled output to match the canvas would put the stream into YouTube's 480p class. The documented setup keeps them different for that reason and pins 30 fps, since 10 fps turns a broadcast into a slideshow.
• A diagnostic mode that names the failure — run.py --check inspects every prerequisite and writes out precisely what is wrong. It exists because the failure modes here are environmental (OBS closed, DroidCam not in the scene, WebSocket disabled) and guessing at them wastes a stream.
• Control over OBS WebSocket v5 — obsws-python drives a live OBS instance on port 4455, so the tool cooperates with an existing streaming setup instead of replacing it, running against a dedicated OBS profile so other configurations stay untouched.
• The roadmap is published with its status honest — camera mathematics with OBS connectivity and manual control with the GUI are both marked complete and hardware-tested; the setup wizard, the audio/light/motion analyzer, autopilot, joystick and timeline, and the AI agent hook are all openly marked not done.
• Beat detection avoids an unbuildable dependency — a spectral-flux onset detector on SciPy is the default because aubio publishes no Windows wheel for Python 3.11+ and would require MSVC build tools to install.

Key Features

1. Angle presets — save framings and jump between them, managed by a dedicated preset manager.
2. Manual pan and zoom — smooth, eased movement driven from the desktop GUI rather than by handling the phone.
3. Dual aspect ratio — landscape 16:9 for YouTube and portrait 9:16 for TikTok from one camera.
4. Connect-and-go GUI — a CustomTkinter window whose main interaction is a single Connect button.
5. Configuration in YAML — camera and behaviour settings live in files a human can read and diff.
6. Preflight checking — a single command that validates OBS, the WebSocket server and the DroidCam source before a session starts.

Tech Stack

• Python with obsws-python ≥ 1.6 (OBS WebSocket v5 client)
• CustomTkinter ≥ 5.2 + Pillow (desktop GUI)
• NumPy (camera geometry and easing)
• PyYAML (configuration)
• OpenCV ≥ 4.8, PyAudio, SciPy (frame, audio and motion analysis)
• pytest (108 test functions)

Status & Maturity

Active and already usable for real streaming with manual control. It is the best-tested Python project in this catalogue — 108 test functions, all passing, concentrated exactly where correctness is not obvious by reading: geometry, easing, the camera director and configuration handling. The GUI and the OBS connection were verified on hardware rather than mocked, and the unfinished stages are listed as unfinished rather than described as planned features.

Measured Metrics