Kinecam

Use an Xbox One Kinect (v2) on Linux as virtual webcams and a boosted microphone. A tray icon starts and stops everything, and stopping powers the sensor down (IR and logo LEDs off).

Fork of BenGWeeks/openkinect-v2, which provides the original RGB-only kinect2v4l2 streamer, the audio test scripts and the hardware notes. Built on libfreenect2 and v4l2loopback.

Features

Device	Node	Size	Content
Kinect RGB	/dev/video10	1920x1080	Color camera
Kinect Depth	/dev/video11	512x424	Viridis colormap, adaptive range (3rd to 97th percentile), temporal smoothing, flicker removal
Kinect Cloud	/dev/video12	640x480	Colored point cloud, slow rocking view (±0.5 rad around a pivot 1 m out)
Kinect IR	/dev/video13	512x424	Infrared, adaptive brightness
Kinect Mic	PipeWire source	mono 16 kHz	4 mics mixed with gain, much louder than the raw device

• One process (camera/kinect2v4l2_multi) feeds all cameras, since only one program can open the Kinect at a time. Depth uses the OpenCL pipeline (about 800 Hz on a GTX 1060 vs about 10 Hz on CPU).
• tray/kinect-tray.py (PyQt6): green icon = streaming, grey = stopped. Click toggles, menu has Start/Stop and Quit.
• Skeleton tracking is not included (libfreenect2 has none).

Requirements

• Kinect v2 with its adapter, on a USB 3.0 port
• NVIDIA GPU with OpenCL (tested: GTX 1060, RTX 3060; CUDA not needed)
• v4l2loopback, kernel headers matching your running kernel, PipeWire, Python 3, PyQt6
• Tested on CachyOS (Arch), KDE Plasma, Wayland. Other distros should work but are untested.

Install

Quick (Arch / CachyOS)

git clone https://github.com/Athoz8/kinecam.git ~/kinecam
cd ~/kinecam && ./install.sh

Options (combine as needed):

Option	Effect
--autostart	Start the tray at login
--obs-camera	Optional: also create an extra "OBS Virtual Camera" device so OBS can start its virtual camera (see Optional: OBS Virtual Camera)

Plug in the Kinect (USB 3.0) first so the mic filter can be created. The script installs packages, builds libfreenect2 with the fixes below, sets up the virtual cameras, the USB power-off rule and the mic filter, builds the streamer and creates the kinecam launcher. It is safe to run again. If it stops because the running kernel has no modules left after an update, reboot and run it again.

Manual steps

1. Packages (use your kernel's headers, e.g. linux-cachyos-headers; check with uname -r)

sudo pacman -Syu   # sync first, or headers may 404
sudo pacman -S --needed base-devel cmake v4l2loopback-dkms python-pyqt6 opencl-nvidia

If you use a legacy NVIDIA driver (e.g. opencl-nvidia-580xx), leave out opencl-nvidia; it conflicts with the legacy package. install.sh does this automatically.

2. libfreenect2 (AUR libfreenect2-git needs two fixes on current toolchains: CMake 4 rejects its old minimum version, and a local variable clashes with a macro in newer OpenCL headers)

yay -S libfreenect2-git   # fails (CMake 4); it only fetches the PKGBUILD and sources
cd ~/.cache/yay/libfreenect2-git
CMAKE_POLICY_VERSION_MINIMUM=3.5 makepkg -f   # fails at the OpenCL error; expected
grep -rl CL_ICDL_VERSION src/libfreenect2/src | xargs sed -i 's/CL_ICDL_VERSION/ICDL_VERSION_LOCAL/g'
CMAKE_POLICY_VERSION_MINIMUM=3.5 makepkg -ef
sudo pacman -U libfreenect2-git-*.pkg.tar.zst

Remove any older copy in /usr/local/include/libfreenect2 and /usr/local/lib/libfreenect2.so*, or the compiler will pick up the stale headers. (Ubuntu/Debian: build from source as in the original scripts/install-kinect-v2.sh.)

3. Virtual cameras

echo 'options v4l2loopback devices=4 video_nr=10,11,12,13 card_label="Kinect RGB,Kinect Depth,Kinect Cloud,Kinect IR" exclusive_caps=1,1,1,1' | sudo tee /etc/modprobe.d/kinect-vcams.conf
echo v4l2loopback | sudo tee /etc/modules-load.d/v4l2loopback.conf
sudo modprobe -r v4l2loopback; sudo modprobe v4l2loopback   # close apps using the cameras first

4. USB power-off rule (lets the sensor suspend when idle so the LEDs go off)

echo 'ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02c4", TEST=="power/control", ATTR{power/control}="auto", ATTR{power/autosuspend_delay_ms}="2000"' | sudo tee /etc/udev/rules.d/66-kinect2-autosuspend.rules
sudo udevadm control --reload-rules

5. Build the streamer

cd camera && g++ -O2 -o kinect2v4l2_multi kinect2v4l2_multi.cpp -lfreenect2

6. Microphone (~/.config/pipewire/pipewire.conf.d/kinect-mic.conf; replace the serial in target.object with yours from pactl list short sources | grep NUI, then systemctl --user restart pipewire pipewire-pulse wireplumber)

context.modules = [
  { name = libpipewire-module-filter-chain
    args = {
      node.description = "Kinect Mic"
      media.name = "Kinect Mic"
      filter.graph = {
        nodes = [
          { type = builtin name = mix label = mixer control = { "Gain 1" = 8 "Gain 2" = 8 "Gain 3" = 8 "Gain 4" = 8 } }
        ]
        inputs = [ "mix:In 1" "mix:In 2" "mix:In 3" "mix:In 4" ]
        outputs = [ "mix:Out" ]
      }
      capture.props = {
        node.name = "capture.kinect_mic"
        audio.rate = 16000
        audio.channels = 4
        audio.position = [ FL FR FC LFE ]
        target.object = "alsa_input.usb-Microsoft_Xbox_NUI_Sensor_<SERIAL>-02.analog-surround-40"
        node.passive = true
      }
      playback.props = {
        node.name = "kinect_mic"
        media.class = Audio/Source
        audio.rate = 16000
        audio.channels = 1
        audio.position = [ MONO ]
      }
    }
  }
]

Optional: OBS Virtual Camera

Only needed if the OBS Start Virtual Camera button fails (it often shows just "Failed to start virtual camera"). OBS needs a loopback device of its own, and the four devices Kinecam creates are all taken by the Kinect streams, so OBS has nowhere to write. This adds a fifth, separate device (/dev/video20, "OBS Virtual Camera"). You do not need it to use the Kinect cameras as sources in OBS or other apps.

./install.sh --obs-camera

It is safe to run on an existing install. If the cameras are in use and the module cannot be reloaded, the device is added live instead and still comes back after a reboot.

Manual steps:

sudo pacman -S v4l2loopback-utils
sudo v4l2loopback-ctl add -n "OBS Virtual Camera" -x 1 /dev/video20   # live, until reboot
v4l2-ctl --list-devices                                               # should list it

To keep it after a reboot, change /etc/modprobe.d/kinect-vcams.conf to the five-device line, then reload the module (close apps using the cameras first):

options v4l2loopback devices=5 video_nr=10,11,12,13,20 card_label="Kinect RGB,Kinect Depth,Kinect Cloud,Kinect IR,OBS Virtual Camera" exclusive_caps=1,1,1,1,1

If it still fails:

• Check that v4l2-ctl --list-devices shows "OBS Virtual Camera".
• Stop the Kinect streams, remove the Kinect sources from the scene and test with only a webcam; OBS may be picking /dev/video10.
• Run sudo dmesg | grep -i v4l2loopback | tail right after a failed start; the kernel message usually names the reason.

Use

kinecam   # or open Kinecam from the application menu

Select "Kinect RGB / Depth / Cloud / IR" as video sources and "Kinect Mic" as audio in OBS, Zoom, browsers, etc. Run ./install.sh --autostart to start it at login. Use Quit (or Stop) to power the sensor down.

Troubleshooting

Problem	Fix
Crash or frozen video with VA-API errors (vaGetImage, vaCreateImage)	Run with LIBVA_DRIVER_NAME=nonexistent (the tray does this). For the viewer: env LIBVA_DRIVER_NAME=nonexistent Protonect cl
Segfault when stopping the original kinect2v4l2	The original delete pipeline; double-frees; it is removed here
Logo LED stays on after stopping	Step 4 rule missing, or an app still has the mic open (e.g. OBS minimized to tray). Quit it
LIBUSB_ERROR_IO / "No Kinect device found" after suspend	Re-authorize: echo 0 | sudo tee /sys/bus/usb/devices/<port>/authorized, wait 2 s, write 1
modprobe -r v4l2loopback says in use	Find holders with sudo fuser -v /dev/video1* and close them
Kinect IR/Mixed/... entries in OBS that do nothing	Leftovers from older configs; reload the module with the settings from step 3
Cloud/Depth show trails	Temporal smoothing trades a little latency for less flicker
OBS says "Failed to start virtual camera"	Add the optional OBS Virtual Camera device: ./install.sh --obs-camera (see above)

Layout

camera/   kinect2v4l2_multi.cpp (RGB+Depth+Cloud+IR), kinect2v4l2.cpp (original RGB-only)
tray/     kinect-tray.py
install.sh  installer (Arch / CachyOS)
audio/    original test scripts
docs/     original notes (beamforming roadmap, troubleshooting)

Status

Working: 4 cameras, boosted mic, tray control, LED power-off. Planned: other distros and GPUs in install.sh, adjustable colormap and cloud settings, beamforming (see docs/BEAMFORMING-ROADMAP.md).

License

MIT, as in the original project. Not affiliated with Microsoft; Kinect is a trademark of Microsoft Corporation.