hikcloudstream 0.1.0__tar.gz

hikcloudstream-0.1.0/.env.example

@@ -0,0 +1,3 @@
+HIK_CONNECT_USER=
+HIK_CONNECT_PASSWORD=
+HIK_CONNECT_VALIDATE_CODE=

hikcloudstream-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+
+      - name: Ruff
+        run: uv run ruff check src tests
+
+      - name: Unit tests
+        run: uv run pytest tests/unit -v
+
+      - name: Build wheel
+        run: uv build

hikcloudstream-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.ts
+examples/output/
+*.jpg
+!tests/fixtures/*.jpg

hikcloudstream-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

hikcloudstream-0.1.0/AGENT.md

@@ -0,0 +1,88 @@
+# Agent directives
+
+> **Entry point for LLM agents and contributors working in this repository.**
+
+## What this repo is
+
+**hikcloudstream** is an unofficial Python SDK for **Hik-Connect cloud cameras**:
+
+- REST login, device list, cloud snapshots
+- Live video via **cloud VTM relay** (not LAN RTSP, not P2P)
+
+It is a **public open-source library** (Apache-2.0), not a sandbox experiment.
+
+## Language policy (non-negotiable)
+
+**All code artifacts must be in English:**
+
+- Identifiers, docstrings, comments, CLI help, error messages, HTTP viewer HTML
+- README and docs inside the repo
+- Commit messages (Conventional Commits)
+
+You may chat with the user in their language; never mirror it in the codebase.
+
+## Sensitive data policy
+
+**Never commit:**
+
+- Real usernames, passwords, device serials, validate codes
+- APK decompile trees or proprietary SDK blobs
+- Condominium-specific names or private regional host examples beyond public `api.hik-connect.com`
+
+Use `.env` locally (gitignored). Examples use `user@example.com` placeholders only.
+
+## Architecture map
+
+| Module | Responsibility |
+|--------|----------------|
+| `src/hikcloudstream/client.py` | REST API, login, list, snapshot |
+| `src/hikcloudstream/capture.py` | Cloud snapshot AES decrypt |
+| `src/hikcloudstream/stream/session.py` | VTM session, `LiveStreamSession`, record/capture helpers |
+| `src/hikcloudstream/stream/probe.py` | Auto stream type (substream vs main) |
+| `src/hikcloudstream/stream/rtp.py` | RTP → Annex B |
+| `src/hikcloudstream/stream/crypto.py` | Encrypted NAL decrypt |
+| `src/hikcloudstream/stream/sinks/` | MPEG-TS, MJPEG, HTTP viewer |
+| `src/hikcloudstream/cli/` | Thin CLI over public API only |
+
+Stable exports live in `src/hikcloudstream/__init__.py` and `src/hikcloudstream/stream/__init__.py`.
+
+## How to change things safely
+
+1. Read surrounding code; match naming and patterns.
+2. Keep CLI and examples on the **public API** — no direct `pyezvizapi` in `cli/`.
+3. Breaking API changes → update `CHANGELOG.md` and README examples.
+4. Prefer typed exceptions from `exceptions.py` over bare `RuntimeError`.
+5. Unit-test protocol logic (RTP, crypto) with redacted fixtures — no live credentials in CI.
+
+## Common pitfalls
+
+| Issue | Cause | Note |
+|-------|-------|------|
+| Black video on main stream | Proprietary RTP on some DVR channels | Auto substream (`stream=2`) |
+| VTDU token failure | Wrong auth path for Hik-Connect | Primary: `POST /api/user/token/get` |
+| MJPEG viewer + encryption | Decrypt not wired in viewer | Use `validate_code` with record/snapshot only |
+| N viewers = N VTM sessions | One TCP session per consumer | Document fan-out / HLS for scale |
+
+## Testing expectations
+
+- `tests/unit/` must pass in CI without secrets
+- Integration tests: `@pytest.mark.integration`, env-gated only
+- Run `uv run ruff check src tests` before finishing
+
+## Routing
+
+| Need | Go to |
+|------|--------|
+| User-facing overview | [README.md](README.md) |
+| Streaming API detail | [docs/streaming.md](docs/streaming.md) |
+| Maintainer blueprint | [docs/MAINTAINER_BLUEPRINT.md](docs/MAINTAINER_BLUEPRINT.md) |
+| Legal / OSS notes | MAINTAINER_BLUEPRINT § License |
+
+## Conflict resolution
+
+1. User explicit choice
+2. This `AGENT.md` for repo-specific rules
+3. Target module conventions
+4. Generic best practice
+
+If the developer also uses the **pkb** workspace, engineering discipline from `pkb/CLAUDE.md` applies unless it conflicts with this file.

hikcloudstream-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-09
+
+### Added
+
+- Initial public release migrated from sandbox prototype
+- `HikConnectClient` — login, list cameras, cloud snapshot
+- `hikcloudstream.stream` — VTM live sessions, auto stream probe, MPEG-TS record, MJPEG viewer
+- CLI: `hikcloudstream-snapshot`, `hikcloudstream-stream`
+- Examples, docs, unit tests, GitHub Actions CI

hikcloudstream-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for helping improve **hikcloudstream**. This project is early-stage (0.x); APIs may change.
+
+## Setup
+
+```bash
+git clone https://github.com/cristianojmiranda/hikcloudstream.git
+cd hikcloudstream
+uv sync --all-extras
+```
+
+## Run tests
+
+```bash
+uv run pytest tests/unit -v
+uv run ruff check src tests
+uv run mypy src/hikcloudstream
+```
+
+Integration tests (live Hik-Connect account) are optional:
+
+```bash
+export HIK_CONNECT_USER=...
+export HIK_CONNECT_PASSWORD=...
+uv run pytest -m integration  # when added
+```
+
+Never commit credentials or device serials from your environment.
+
+## Pull request checklist
+
+- [ ] English for code, comments, CLI help, and user-facing errors
+- [ ] No secrets, real account names, or private URLs in the diff
+- [ ] Unit tests for behavior changes (rtp, crypto, probe logic)
+- [ ] Public API changes documented in `CHANGELOG.md`
+- [ ] `uv run ruff check` and `uv run pytest tests/unit` pass
+
+## Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
+
+## AI-assisted changes
+
+Read [AGENT.md](AGENT.md) before editing. Keep diffs focused; match existing module layout.

hikcloudstream-0.1.0/NOTICE

@@ -0,0 +1,12 @@
+hikcloudstream
+Copyright 2026 Cristiano Miranda
+
+Licensed under the Apache License, Version 2.0.
+
+This project depends on:
+
+- pyezvizapi (Apache-2.0) — https://github.com/RenierM26/pyEzvizApi
+- httpx (BSD-3-Clause) — https://github.com/encode/httpx
+- pycryptodome (BSD) — https://github.com/Legrandin/pycryptodome
+- pillow (MIT-CMU) — optional extra [cli]/[viewer]
+- av / PyAV (BSD-3-Clause) — optional extra [viewer]

hikcloudstream-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+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).

hikcloudstream-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 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).

hikcloudstream-0.1.0/docs/MAINTAINER_BLUEPRINT.md

@@ -0,0 +1,55 @@
+# Maintainer blueprint
+
+Internal planning notes for **hikcloudstream** maintainers. The public README is the user-facing source of truth.
+
+## Protocol clarification
+
+Live video uses **cloud VTM relay**, not LAN RTSP and not classic P2P hole-punching:
+
+```
+Account login (REST)
+    → device/channel discovery (pagelist + VTM metadata)
+    → VTDU stream tokens
+    → TCP session to regional VTM server (ysproto://…)
+    → RTP carrying H.264
+    → depacketize / decode / remux
+```
+
+The Hik-Connect mobile app also uses VTM for remote preview when P2P/LAN is unavailable. Do **not** describe this project as a “P2P stream fix.”
+
+## Trade-offs
+
+| Decision | Pros | Cons |
+|----------|------|------|
+| Build on pyezvizapi | Battle-tested VTM framing | Hik-Connect adapter layer forever |
+| VTM-only (no P2P) | Matches cloud condo use case | No LAN optimizations |
+| PyAV for MJPEG | Low latency | Heavy optional dep; CPU per viewer |
+| Auto stream probe | Works across DVR channels | ~5s connect delay |
+| Alpha 0.x semver | API flexibility | Breaking changes possible |
+
+## License, copyright, and open-source safety
+
+> Not legal advice.
+
+Publishing as unofficial OSS is **reasonable** (same category as pyezvizapi, Home Assistant EZVIZ). Main risks: **ToS**, **trademark**, **secrets in repo** — not “you cannot copyright your Python.”
+
+| Do | Don't |
+|----|-------|
+| Apache-2.0 + NOTICE | APK decompile, SDK blobs |
+| README disclaimer | Official logos / “Hikvision SDK” naming |
+| Placeholder examples | Real credentials or device serials |
+
+See README legal disclaimer. Confirm employer IP if applicable.
+
+## Deferred (post-0.1.0)
+
+- PyPI publish
+- Async API (`httpx.AsyncClient`)
+- P2P / LAN RTSP
+- Encrypted live MJPEG viewer
+- Home Assistant integration
+- Dependabot, SECURITY.md, integration CI nightly
+
+## Public API stability
+
+Exports in `hikcloudstream/__init__.py` and `hikcloudstream/stream/__init__.py` are the stable surface for 0.1.x. Breaking changes require CHANGELOG entry.

hikcloudstream-0.1.0/docs/architecture.md

@@ -0,0 +1,45 @@
+# Architecture
+
+High-level data flow (no internal endpoint catalog):
+
+```
+┌─────────────┐     REST      ┌──────────────────┐
+│  Your app   │ ────────────► │ HikConnectClient │
+│  or CLI     │               │  (httpx)         │
+└──────┬──────┘               └────────┬─────────┘
+       │                               │
+       │ stream                        │ sessionId
+       ▼                               ▼
+┌──────────────────┐  VTDU tokens  ┌─────────────────┐
+│ LiveStreamSession│ ◄──────────── │ stream/adapter  │
+└────────┬─────────┘               └─────────────────┘
+         │ ysproto://VTM:8554
+         ▼
+┌──────────────────┐   RTP H.264   ┌──────────────────┐
+│ pyezvizapi VTM   │ ────────────► │ stream/rtp       │
+│ client           │               │ stream/sinks/*   │
+└──────────────────┘               └──────────────────┘
+```
+
+## Package layout
+
+```
+src/hikcloudstream/
+├── client.py          # REST API
+├── capture.py         # Snapshot decrypt
+├── stream/
+│   ├── session.py     # VTM lifecycle
+│   ├── probe.py       # Auto stream type
+│   ├── rtp.py         # Depacketization
+│   ├── crypto.py      # Encrypted NAL
+│   └── sinks/         # MPEG-TS, MJPEG, HTTP
+└── cli/               # Optional commands
+```
+
+## Dependencies
+
+- **httpx** — REST
+- **pyezvizapi** — VTM TCP protocol
+- **pycryptodome** — AES for snapshots and encrypted streams
+- **av** (optional) — PyAV MJPEG decoder
+- **FFmpeg** (system) — remux and frame extract

hikcloudstream-0.1.0/docs/limitations.md

@@ -0,0 +1,24 @@
+# Limitations
+
+| Issue | Impact | Workaround |
+|-------|--------|------------|
+| Unofficial API | Endpoints may change | Pin `ClientConfig.client_version`; watch app updates |
+| VTM session limits | N viewers = N cloud connections | Single ingest + HLS/WebRTC fan-out |
+| Encrypted live MJPEG | Viewer raises error | `validate_code` on record/snapshot only |
+| Proprietary RTP on main | Some channels black on `stream=1` | Auto substream (`stream=2`) |
+| Channels without VTM | `Could not find VTM resource` | Channel offline or unlicensed |
+| Cloud snapshot resolution | Fixed ~352×288 | Live frame capture for HD |
+| CAPTCHA / 2FA | Login fails | Log in via official app first |
+| No P2P / LAN RTSP | No direct NVR URL | Use go2rtc / RTSP for local access |
+| Token / firewall | VTDU auth blocked | Ensure outbound HTTPS to Hik-Connect auth hosts |
+
+## Performance (single viewer)
+
+Approximate values — vary by CPU, camera, and stream type:
+
+| Profile | RAM | Egress |
+|---------|-----|--------|
+| Substream MJPEG | ~65 MB | ~0.7 Mbps |
+| Main HD MJPEG | ~100 MB | ~10–15 Mbps |
+
+Not suitable for 50+ viewers without architecture change — see [streaming.md](streaming.md).

hikcloudstream-0.1.0/docs/quickstart.md

@@ -0,0 +1,70 @@
+# Quickstart
+
+## Install
+
+```bash
+uv sync --extra viewer
+# or: pip install "hikcloudstream[viewer]"
+```
+
+Install [FFmpeg](https://ffmpeg.org/) for recording and HD frame capture.
+
+## Environment (optional)
+
+```bash
+cp .env.example .env
+# fill HIK_CONNECT_USER and HIK_CONNECT_PASSWORD
+```
+
+## List cameras
+
+```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)
+```
+
+## Cloud snapshot
+
+```python
+from pathlib import Path
+from hikcloudstream import Credentials, HikConnectClient
+
+with HikConnectClient() as client:
+    client.login(Credentials("user@example.com", "your_password"))
+    cameras = client.list_cameras()
+    jpeg = client.capture_snapshot(cameras[0])
+    Path("thumb.jpg").write_bytes(jpeg)
+```
+
+Resolution is capped at **352×288** by the Hik-Connect cloud API.
+
+## Live stream frame (HD)
+
+```python
+from pathlib import Path
+from hikcloudstream import Credentials, HikConnectClient
+from hikcloudstream.stream import capture_live_snapshot
+
+with HikConnectClient() as client:
+    client.login(Credentials("user@example.com", "your_password"))
+    cameras = client.list_cameras()
+    capture_live_snapshot(client, cameras[0], Path("frame.jpg"), warmup_seconds=6.0)
+```
+
+## MJPEG browser viewer
+
+```python
+from hikcloudstream import Credentials, HikConnectClient
+from hikcloudstream.stream import MjpegServer
+
+with HikConnectClient() as client:
+    client.login(Credentials("user@example.com", "your_password"))
+    cameras = client.list_cameras()
+    MjpegServer(client, cameras[0], host="127.0.0.1", port=8558).serve_forever()
+```
+
+Open `http://127.0.0.1:8558/`.