Manual / Getting Started
Hardware
OpenFollow is built to run reliably on affordable, off-the-shelf hardware. This chapter covers the host computer, video sources, controllers, displays, and network.
Host computer
Recommended: Raspberry Pi 5 (or Compute Module 5)
The reference deployment target for tracking with operator input is a Raspberry Pi 5 or a Compute Module 5 on a CM5 IO board, with 4 GB RAM minimum (8 GB recommended). The pre-built image and the .deb package are built and tested against this configuration, and the kiosk display (full-screen on HDMI) targets it. The CM5 with eMMC and an NVMe SSD on the IO board is the most reliable live-show configuration.
You also need:
- A boot device: a Compute Module with 16 GB onboard eMMC minimum (32 GB recommended), or a 64 GB microSD card.
- The official 27 W Pi 5 power supply.
- Active or passive cooling.
- Optional: an NVMe SSD on the IO board. The installer mounts it at
/mnt/nvme.
OpenFollow also installs on a 64-bit Intel or AMD machine – a mini-PC, NUC, or laptop – running Debian 13 (Trixie) (the same base as Raspberry Pi OS) from the amd64 .deb package. It can run on macOS for development and testing, but production use should be on Raspberry Pi OS Lite or Debian 13 (Trixie).
Any feature that uses person detection may require more powerful hardware than a Raspberry Pi. These features are experimental and not recommended for production use.
Cameras and capture
OpenFollow accepts video over network protocols and direct connections. Aim for the lowest end-to-end latency at 720p or 1080p, 25–30 fps.
| Source type | Typical use | Notes |
|---|---|---|
| RTSP (recommended) | Most IP cameras, HDMI/SDI-to-IP encoders | The most universal option. Latency depends on camera firmware. |
| SRT | Long-haul over noisy or remote networks | Configurable latency floor. |
| RTP | Tightly-controlled local pipelines | You typically generate the RTP yourself. |
| NDI® 1 2 | NDI®-native cameras and software sources | Requires the closed-source NDI® Tools / SDK on the Pi. |
| Pi Camera (CSI) | Pi Camera modules, CSI capture adapters | Lowest latency. CSI HDMI/SDI bridges work via libcamera. |
| USB Camera | UVC webcams, USB capture cards | Latency varies wildly by vendor. |
| Media Gallery | Bench testing without a camera | Play a stored still or clip; ships with a Stage scene and a Grey card. |
Per-protocol setup, recommended encoder settings, and known-good cameras live in Video Inputs.
Controllers
Gamepads
Standard USB-wired gamepads are auto-detected. The default mapping assumes an Xbox-style layout (A/B/X/Y, Left/Right Bumpers, Left/Right Triggers, two sticks, D-Pad). The wizard auto-detects the controller name and lets you remap any button if the labels don’t match.
The controller must run in XInput mode. Pads with a mode switch (XInput / DirectInput, or PC / Switch / Android) often default to something else – check your controller's manual for how to set XInput.
Prefer controllers with Hall-effect sticks – they don't develop drift over time the way potentiometer sticks do.
Use a wired gamepad for show work. Wireless / Bluetooth is not recommended.
The shipped config uses neutral Xbox-identity defaults rather than a device-specific calibration – run the button detection wizard once per controller so each pad maps correctly. Any modern Xbox-compatible USB gamepad works; see tested hardware.
3D mouse
3Dconnexion SpaceMouse and SpaceNavigator devices3 connect over USB and drive a marker on all six axes. Off by default; map the axes and buttons under Input → 3D Mouse. Connect one per operator on a multi-operator station. Full setup is in Gamepad, Keyboard & OSC → 3D mouse.
Keyboard
The keyboard is a full live input. It supports four movement layouts:
- WASD (default)
- ESDF
- IJKL
- Numpad 8426
Plus dedicated keys for Z up/down, reset, speed adjust, settings menu, and marker switching. Full mapping is in Gamepad, Keyboard & OSC.
OSC sources
Anything that can send OSC (a control surface app, another OpenFollow instance, a console, a custom script) can drive markers via the OSC input – see Controls.
Display
The Pi’s HDMI output renders the live overlay full-screen at boot. Headless deployments can still drive an HDMI output without an attached keyboard/mouse.
Operator station
It’s important to provide a functional environment for the operator:
- The operator should not be able to see the stage directly. Continuous following depends on tracking the marker on the screen, not on glancing back and forth between screen and stage. Looking at the stage breaks the loop and the marker drifts. Having the station in a space where the stage is not visible is an industry best practice with all remote-control systems.
- Ergonomic seating and screen height. Operating the system over a long show is fatiguing; treat it like any sustained desk task. Make sure to implement your local recommendations for ergonomic seating and monitor placement.
- Large and glare-free monitor. Ambient stage light reflecting off the screen washes out the live image and makes the marker hard to see. A hood, a matte screen, or simply a darker pocket helps.
- Have your operators connected. When your operator is in a different space as recommended, ensure reliable communication between the operator and the people operating the systems that consume the data generated by OpenFollow. Also, provide a way for the operator to receive cues and hearing the show.
Network
OpenFollow is designed for trusted LAN deployment.
- Multicast must work (PSN, OTP). Test end-to-end before show day; configure IGMP snooping on managed switches.
- Wired Ethernet. Wi-Fi is not recommended.
- Same subnet as consoles, media servers, and audio engines – or routed multicast.
NVMe storage (optional)
An NVMe SSD on the CM5 IO board mounts at /mnt/nvme and holds detection models and runtime data. The OS and the OpenFollow app live on the boot device (eMMC or microSD), not the SSD. Recommended for permanent installs.
Tested hardware
The following devices have been verified to work with OpenFollow. The list will grow as more hardware is tested – if you’ve had success with something not listed, let us know.
Tested does not mean recommended. A listing here means only that the device has been verified to work with OpenFollow – not that the project recommends it or its manufacturer.
Cameras
| Model | Tested connections |
|---|---|
| AIDA Imaging HD-NDI-VF | RTSP (recommended), NDI®, SRT |
| AIDA Imaging HD-NDI-TF | RTSP (recommended), NDI®, SRT. This camera has a tele-optic zoom lens – it needs to be further away from the Stage than what is practical in a lot of venues. The AIDA Imaging HD-NDI-VF and AIDA Imaging HD-NDI-TF are otherwise identical. |
| AIDA Imaging HD3G-NDI-200 | RTSP (recommended), NDI®, SRT |
| Marshall Electronics CV570-ND3 | RTSP (recommended), NDI® |
| Sony BRC-X400 | NDI® |
| Sony FX30 | USB, Raspberry Pi CSI (HDMI) |
| Elgato Cam Link 4K | USB (HDMI capture). USB video capture is processing-heavy; for a 4K source on a Raspberry Pi, set the Render resolution to 1080p rather than Native size. |
Gamepads
| Model | Notes |
|---|---|
| GameSir-G7 SE Controller for Xbox | Use in USB-wired mode. |
| 8BitDo Pro 2 Wired Controller for Xbox | Hall-effect sticks. Use in USB-wired mode. |
| Microsoft Xbox Wireless Controller | Tested over USB-C cable only – use in USB-wired mode, not Bluetooth. Noticeable stick drift in some tested units. If you have one it's fine for testing purposes, but don't buy one specifically for OpenFollow. |
3D mice
| Model | Tested connections |
|---|---|
| 3Dconnexion SpaceNavigator® | USB |
| 3Dconnexion SpaceMouse® Compact | USB |
| 3Dconnexion SpaceMouse® | USB |
MIDI controllers
| Model | Tested connections |
|---|---|
| Korg nanoKONTROL2 | USB |
1. NDI® is a registered trademark of Vizrt NDI AB.
2. OpenFollow does not contain any NDI® code by itself. NDI® requires closed source NDI® Tools / NDI® SDK on the host system that need to be installed separately.
3. SpaceMouse and SpaceNavigator are registered trademarks of 3Dconnexion GmbH.