Questions and answers

It is a preview. The project is in early development: the full chain, from the camera to the live point of view inside a running Visual Pinball X, works on a real Linux pincab with a Kinect v2, a Kinect v1 and a webcam. Windows and macOS builds are published, and reports from people running them are exactly what the project needs. Expect rough edges, and tell us about them on Discord.

Yes: headtracking is an open-source, cross-platform alternative to BAM for Visual Pinball X. It works from a plain webcam or a Kinect v1 or v2, needs no Microsoft Kinect SDK, and finds the camera's position by itself from the lockbar and side rails. See how it works.

No. To reach a Kinect, the driver setup shipped with headtracking replaces Microsoft's official Kinect driver with a generic WinUSB one. That breaks everything built on the Microsoft Kinect SDK, BAM head tracking included, until you restore the original driver (Device Manager, the “Xbox NUI” devices: uninstall the driver and scan for hardware changes, or reinstall the Kinect SDK/runtime). There is no automatic way back. Webcam users are not affected.

No. A plain webcam works: the automatic calibration turns it into a 3D head tracker. A Kinect measures the distance of your head directly and tracks in infrared, so it keeps working in a dark game room where a webcam struggles. See choosing a camera.

Visual Pinball X 10.8.1 or later: headtracking is a plugin for the plugin system of VPX 10.8.1. It is a Visual Pinball X plugin only.

There is no calibration routine: no checkerboard, no “look here and press a key”. The plugin finds the camera position from the lockbar and side rails in the image. You do need to enter two measurements in VPX (F12 → Cabinet Settings): your lockbar width and your screen inclination. See setting up the view.

Check the two measurements first. A wrong lockbar width scales every distance by the same error, so the effect feels too strong or too weak everywhere. A missing or wrong screen inclination mixes up/down with closer/farther, so the view drifts diagonally when you move. After that, adjust the gain and the smoothing on the settings page of the plugin.

Hold the lockbar button for 2 seconds during a game: the plugin takes your current head position as the new neutral position and shows “Head tracking recentered”. At the start of each game, the first stable position is captured, so stand where you normally play when the table loads.

When the plugin runs, it shows a notification with the detected camera at game start, and the VPX log gets HeadTracking lines. If a camera is missing, the plugin says so on screen. No notification at all usually means a driver or permission problem: on Linux the Kinect needs udev rules, on Windows it needs the WinUSB driver, and on macOS VPX must be allowed to use the camera. See the per-system steps.

The Kinect v2 needs its power adapter (the Kinect Adapter) and a dedicated USB 3.0 port on the back of the motherboard. It streams colour, infrared and depth at the same time, which is close to what a USB 3.0 link can carry: no hub, no front-panel port, no cheap extension cable.

Something else is holding the Kinect, for example the headtracking demo or a capture tool. Close it and restart the table.

Start the demo with the environment variable HT_DEPTH_PIPELINE=cpu. If the freeze goes away, the GPU depth processing is the cause on your machine. It is a diagnosis, not a setting to keep: send both logs on Discord.

Not at the moment. Releases are built for Linux (x86_64 and ARM 64-bit), Windows (64-bit x86) and macOS on Apple silicon. The Intel Mac and Windows ARM builds are switched off in the release pipeline because of problems in the machine-learning libraries.

Yes, but the short distance between the player and the camera decides which camera to pick. See the minicab notes.

Yes. headtracking is free software under the GNU GPL v3 or later. The source code is on GitHub.

Bug reports, help and beta testing happen on Discord. You can also open an issue on GitHub. The detailed install guide is docs/INSTALL.md.