Hikvision Live Viewer

Python app for viewing a Hikvision camera live over RTSP when your computer is on the same network as the camera.

It includes basic real-time motion tracking and YuNet/SFace face recognition overlays.

Setup

Open a terminal in this folder:

cd /home/compotuzb/Documents/hikvision_live_viewer
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env and enter your camera IP, username, and password.

Face Recognition Setup

The app downloads missing OpenCV Zoo ONNX models automatically on first run when AUTO_DOWNLOAD_FACE_MODELS=true:

models/face_detection_yunet_2023mar.onnx
models/face_recognition_sface_2021dec.onnx

If your machine has no internet access, download those files manually and put them in models/, or set custom FACE_DETECTOR_MODEL_URL and FACE_RECOGNIZER_MODEL_URL values in .env.

Put one clear reference image per person in known_faces/. The file name becomes the display name:

known_faces/Aziz.jpg
known_faces/Madina.png

YuNet is used for face detection. SFace is used to extract and compare face features. Both ONNX models run through ONNX Runtime and prefer CUDA when FACE_INFERENCE_DEVICE=gpu. If only the YuNet model is present, the app still draws face boxes but labels faces as Unknown. Increase FACE_PROCESS_EVERY_N_FRAMES if live video becomes slow.

If CUDA is requested but ONNX Runtime cannot activate CUDAExecutionProvider, face recognition is disabled when FACE_DNN_REQUIRE_GPU=true.

For live camera recognition, FACE_MATCH_THRESHOLD=0.25 is intentionally more tolerant than the SFace default because RTSP frames are often compressed, blurred, or angled. Unknown faces still show their best score on screen so you can tune the threshold.

To check the current CUDA/ONNX Runtime state:

python check_cuda.py

On Ubuntu, nvidia-smi must work before Python can use the GPU. If nvidia-smi fails, update the NVIDIA driver first, then reboot:

sudo apt install nvidia-driver-595-open nvidia-utils-595 libnvidia-compute-595
sudo reboot

Run

python view_camera.py

Press q in the video window to quit.

Notes

• Main stream is usually channel 101.
• Sub stream is usually channel 102; use this if the video is slow.
• Your computer must be on the same network as the camera.
• RTSP must be enabled on the Hikvision camera.
• The default RTSP URL is:

rtsp://USERNAME:PASSWORD@CAMERA_IP:554/Streaming/Channels/101

If your camera uses a different stream path, set HIKVISION_RTSP_URL in .env.

To disable motion boxes, set this in .env:

ENABLE_MOTION_TRACKING=false

To disable face recognition, set this in .env:

ENABLE_FACE_RECOGNITION=false