djhud-pi 0.1.0

DJ HUD headless/Pi camera source node for the DJ HUD collective

djhud-pi

Pi Zero 2 W camera source node for the DJ HUD collective.

Points a Pi Camera at a screen (laptop, CDJ display, mixer) and streams cropped / perspective-corrected regions to the main DJ HUD app over the WireGuard VPN — or directly to VDO.Ninja / a virtual camera device.

---

Architecture

Pi Camera (picamera2)
    │
    ▼
CameraCapture  ──►  RegionSet (per-region perspective de-warp via OpenCV)
                         │
                         ▼
                   HUD Strip (numpy composite, 1280×100)
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
         VPN WebSocket  VDO.Ninja  Virtual Cam
         (aiohttp)      (aiortc)   (pyvirtualcam)
              │
              ▼
        Main DJ HUD app
        (StreamClient receiver — ws://10.66.66.x:8765/stream)

---

Install

# On a Pi Zero 2 W with Raspberry Pi OS (Bookworm)
pip install djhud-pi

# With Pi Camera support
pip install "djhud-pi[pi]"

# Everything
pip install "djhud-pi[all]"

System dependencies (Pi)

sudo apt install python3-tk python3-opencv libatlas-base-dev
sudo apt install python3-picamera2   # or: pip install picamera2
# For virtual camera output:
sudo modprobe v4l2loopback

---

Run

djhudpi
# or
python -m djhudpi

---

Workflow

1. Start Camera — select resolution & FPS, click ▶ Start Camera
2. Add Regions — click + Add, name your region
3. Place crop — click in the preview to set crop origin, edit W/H in Edit dialog
4. Perspective correction — select a region, click 📐 Pick Warp Corners, then click the 4 corners of the screen/display in the preview (TL→TR→BR→BL). Drag dots to fine-tune. Click Apply.
5. Enable output — tick VPN WebSocket Stream, enter your VPN port. The stream URL (e.g. ws://10.66.66.3:8765/stream) appears — paste it into the main DJ HUD app's StreamClient source field.
6. Config auto-saves on close to ~/.djhudpi_config.json.

---

Perspective de-warp

When pointing the Pi Camera at a screen at an angle, use Pick Warp Corners to click the 4 corners of the screen content area. djhud-pi computes a homography (cv2.findHomography) and cv2.warpPerspective to produce a flat, front-on crop regardless of camera angle.

---

Outputs

Output	Protocol	Notes
VPN WebSocket	JPEG over WS (aiohttp)	Matches main DJ HUD StreamClient
VDO.Ninja	WebRTC (aiortc)	Stub — port vdoninja_client.py from main app
Virtual Camera	v4l2loopback + pyvirtualcam	Use as webcam source in OBS/browser

---

File structure

src/djhudpi/
├── __init__.py       version
├── __main__.py       entry point
├── app.py            tkinter GUI
├── camera.py         picamera2 / OpenCV capture
├── region.py         Region model + perspective warp + composite
├── warp_picker.py    4-corner picker dialog
└── output.py         VPN stream / VDO.Ninja / virtual cam backends

---

Development / testing on non-Pi hardware

Falls back to OpenCV VideoCapture automatically when picamera2 is not available, so you can develop and test on your Mac or Windows machine with a regular webcam.

pip install "djhud-pi"   # no [pi] extra needed on non-Pi
djhudpi