Metadata-Version: 2.4
Name: hikcloudstream
Version: 0.1.0
Summary: Unofficial Python SDK for Hik-Connect cloud cameras: list devices, snapshots, and live VTM streaming
Project-URL: Homepage, https://github.com/cristianojmiranda/hikcloudstream
Project-URL: Documentation, https://github.com/cristianojmiranda/hikcloudstream#readme
Project-URL: Repository, https://github.com/cristianojmiranda/hikcloudstream
Project-URL: Issues, https://github.com/cristianojmiranda/hikcloudstream/issues
Author: Cristiano Miranda
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: camera,cctv,cloud,ezviz,hik-connect,hikvision,nvr,streaming,vtm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video :: Capture
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: pycryptodome>=3.21.0
Requires-Dist: pyezvizapi>=1.0.4.5
Provides-Extra: cli
Requires-Dist: pillow>=11.0.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: av>=17.1.0; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pillow>=11.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: viewer
Requires-Dist: av>=17.1.0; extra == 'viewer'
Requires-Dist: pillow>=11.0.0; extra == 'viewer'
Description-Content-Type: text/markdown

# hikcloudstream

[![CI](https://github.com/cristianojmiranda/hikcloudstream/actions/workflows/ci.yml/badge.svg)](https://github.com/cristianojmiranda/hikcloudstream/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![License](https://img.shields.io/badge/license-Apache--2.0-green)

**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

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

```python
from hikcloudstream import Credentials, HikConnectClient

with HikConnectClient() as client:
    client.login(Credentials("user@example.com", "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](https://ffmpeg.org/) (`ffmpeg` on PATH) for recording, HD frame capture, and MPEG-TS remux.

## CLI

```bash
export HIK_CONNECT_USER="user@example.com"
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/`](examples/) — each script documents required extras and env vars.

## Documentation

- [Quickstart](docs/quickstart.md)
- [Streaming API](docs/streaming.md)
- [Limitations](docs/limitations.md)
- [Architecture](docs/architecture.md)

## Origin

Live streaming was reverse-engineered from the **Hik-Connect for End User** mobile app and aligned with [pyezvizapi](https://github.com/RenierM26/pyEzvizApi). The implementation uses the **cloud VTM relay protocol**.

## Related projects

- [pyezvizapi](https://github.com/RenierM26/pyEzvizApi) — VTM protocol (Apache-2.0)
- [Home Assistant EZVIZ](https://www.home-assistant.io/integrations/ezviz/) — integration using pyezvizapi
- [go2rtc](https://github.com/AlexxIT/go2rtc) — LAN RTSP/WebRTC aggregator

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). AI agents: read [AGENT.md](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](LICENSE) and [NOTICE](NOTICE).
