hikcloudstream 0.1.0

Unofficial Python SDK for Hik-Connect cloud cameras: list devices, snapshots, and live VTM streaming

hikcloudstream

Unofficial Python SDK for Hik-Connect cloud cameras — list devices, cloud snapshots, and live streaming over the VTM relay.

If you have Hik-Connect cameras in the cloud (condo, shared NVR, no RTSP URL) and found almost nothing on GitHub — that's why this exists. This is a community library, not an official Hikvision or EZVIZ product. APIs can change without notice.

What it does

• Log in with your Hik-Connect account (same credentials as the mobile app)
• List cameras and channels on the account
• Cloud snapshot (~352×288 thumbnail via API)
• Live stream via cloud VTM relay (H.264 → Annex B, MPEG-TS, MJPEG viewer)
• Auto-select substream vs main stream per camera

What it does not do

• LAN RTSP / ONVIF / ISAPI (use FFmpeg, go2rtc, or HCNetSDK for local NVR access)
• P2P hole-punching (the app uses P2P at home; remote cloud preview uses VTM relay — same path as this library)
• Official support or guaranteed API stability

Quick start

git clone https://github.com/cristianojmiranda/hikcloudstream.git
cd hikcloudstream
uv sync --extra viewer

from hikcloudstream import Credentials, HikConnectClient

with HikConnectClient() as client:
    client.login(Credentials("[e-mail]", "your_password"))
    for cam in client.list_cameras():
        print(cam.index, cam.name, cam.device_serial, cam.channel_no)

Install

Extra	Purpose	Command
core	API + streaming protocol	pip install hikcloudstream or uv sync
cli	Command-line tools + Pillow	uv sync --extra cli
viewer	MJPEG HTTP viewer (PyAV)	uv sync --extra viewer
dev	Tests, ruff, mypy	uv sync --extra dev

System dependency: FFmpeg (ffmpeg on PATH) for recording, HD frame capture, and MPEG-TS remux.

CLI

export HIK_CONNECT_USER="[e-mail]"
export HIK_CONNECT_PASSWORD="your_password"

uv run hikcloudstream-snapshot "$HIK_CONNECT_USER" "$HIK_CONNECT_PASSWORD" --list
uv run hikcloudstream-snapshot "$HIK_CONNECT_USER" "$HIK_CONNECT_PASSWORD" 1 -o thumb.jpg
uv run hikcloudstream-stream "$HIK_CONNECT_USER" "$HIK_CONNECT_PASSWORD" 1 --proxy
uv run hikcloudstream-stream "$HIK_CONNECT_USER" "$HIK_CONNECT_PASSWORD" 1 -o frame.jpg --duration 6s

Open http://127.0.0.1:8558/ in a browser when using --proxy.

Stream types

stream=	Typical use
2 (substream)	Lower bandwidth, standard H.264 — works on most DVR channels
1 (main)	Higher resolution; some cameras only expose this stream
auto (default)	Probes substream for 5s, falls back to main

Force main stream in Python: StreamType.MAIN. In CLI: --main-stream.

Examples

See examples/ — each script documents required extras and env vars.

Documentation

• Quickstart
• Streaming API
• Limitations
• Architecture

Origin

Live streaming was reverse-engineered from the Hik-Connect for End User mobile app and aligned with pyezvizapi. The implementation uses the cloud VTM relay protocol.

Related projects

• pyezvizapi — VTM protocol (Apache-2.0)
• Home Assistant EZVIZ — integration using pyezvizapi
• go2rtc — LAN RTSP/WebRTC aggregator

Contributing

See CONTRIBUTING.md. AI agents: read AGENT.md first.

Legal disclaimer

This is an unofficial community project. It is not affiliated with, endorsed by, or supported by Hangzhou Hikvision Digital Technology Co., Ltd. or EZVIZ. Use at your own risk. You are responsible for complying with Hik-Connect / EZVIZ Terms of Service and applicable law. Trademarks belong to their respective owners.

License

Apache-2.0 — see LICENSE and NOTICE.