Kinectv2IRCamera

Stream the Kinect for Windows v2 infrared (IR) camera over HTTP (MJPEG + HLS) and RTSP, from a headless Python terminal application. Built on libfreenect2.

The Kinect v2 has an active-IR sensor that sees in total darkness, which makes it a capable low-light / night-vision network camera. This app captures the raw IR stream, processes it (crop, brightness/sensitivity tone-mapping, motion change-mask, IR-reflector tracking), and serves it to browsers, VLC and any RTSP/HLS client.

Features

• IR video from the Kinect v2 (native 512×424) via the freenect2 binding.
• HTTP MJPEG stream served in-process (view in any browser or VLC).
• RTSP + HLS via bundled MediaMTX (ffmpeg → H.264).
• Four-sided crop — top / bottom / left / right, each in pixels or percent.
• Software sensitivity — gain, gamma, black/white levels, auto/fixed/off normalization (Kinect v2 has no settable hardware gain; see docs/PROCESSING.md).
• Change-mask — show only pixels that changed within the last X frames; blank the rest.
• Black & white output — --binary, a pure two-level image with no grayscale (free: it is folded into the tone-map lookup table).
• IR-reflector tracking — --connect-dots joins the changed pixels into a continuous line, so a reflector that registers as speckled dots is drawn as the path it actually travelled.
• CLI flags + YAML config; headless, OpenCL pipeline with CPU fallback.
• --source mock — a synthetic source so you can run and test without any hardware.

Quick start

# 1. One-time setup: build libfreenect2, install udev rules + MediaMTX + the app.
scripts/setup_libfreenect2.sh                 # see docs/INSTALL.md for details

# 2a. Run WITHOUT a Kinect (synthetic test pattern) to verify the streaming stack:
source .venv/bin/activate
kinect2ir --source mock --managed-mediamtx --stats

# 2b. Run against a real Kinect v2 (must be on a USB3 port):
kinect2ir --source kinect --managed-mediamtx --stats \
          --crop-top 10% --crop-bottom 10% --gain 1.4 --change-mask

Then open:

Protocol	URL
HTTP MJPEG	http://<host>:8080/
HTTP snapshot	http://<host>:8080/snapshot.jpg
RTSP	rtsp://<host>:8554/ir
HLS	http://<host>:8888/ir/index.m3u8
WebRTC	http://<host>:8889/ir

Documentation

Doc	Contents
docs/REQUIREMENTS.md	Scope, features, non-goals
docs/DECISIONS.md	Design decisions and why
docs/ARCHITECTURE.md	Modules and data flow
docs/INSTALL.md	Full setup + Python-binding fallback chain
docs/USAGE.md	Complete CLI + YAML reference
docs/PROCESSING.md	Crop / tone-map / change-mask / connect details
docs/STREAMING.md	MJPEG, ffmpeg, MediaMTX, ports
docs/TROUBLESHOOTING.md	Common problems and fixes

Development

source .venv/bin/activate
pip install -e ".[dev]"
pytest -q                       # unit tests (no hardware needed)
kinect2ir --source mock --no-publish   # MJPEG only, quick loop

Status

The full capture → process → MJPEG/RTSP/HLS pipeline is verified end-to-end using the mock source. Real-hardware capture (kinect2ir --source kinect) requires a Kinect v2 on USB3 and a successful freenect2 binding build — see docs/INSTALL.md.

License

MIT.