hikcloudstream 0.1.0__py3-none-any.whl

hikcloudstream/__init__.py

@@ -0,0 +1,39 @@
+"""Unofficial Python SDK for Hik-Connect cloud cameras."""
+
+from hikcloudstream._config import CLOUD_CAPTURE_MAX
+from hikcloudstream.client import HikConnectClient
+from hikcloudstream.exceptions import (
+    ApiError,
+    AuthenticationError,
+    CameraNotFoundError,
+    CaptchaRequiredError,
+    CaptureError,
+    EncryptedStreamError,
+    FFmpegNotFoundError,
+    HikCloudStreamError,
+    StreamNegotiationError,
+    TokenError,
+)
+from hikcloudstream.models import Camera, ClientConfig, Credentials, StreamType
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CLOUD_CAPTURE_MAX",
+    "ApiError",
+    "AuthenticationError",
+    "Camera",
+    "CameraNotFoundError",
+    "CaptchaRequiredError",
+    "CaptureError",
+    "ClientConfig",
+    "Credentials",
+    "EncryptedStreamError",
+    "FFmpegNotFoundError",
+    "HikCloudStreamError",
+    "HikConnectClient",
+    "StreamNegotiationError",
+    "StreamType",
+    "TokenError",
+    "__version__",
+]

hikcloudstream/_config.py

@@ -0,0 +1,15 @@
+"""Internal constants shared across modules."""
+
+from __future__ import annotations
+
+JPEG_MAGIC = b"\xff\xd8"
+HIK_ENCODED_PREFIX = b"hikencodepicture"
+CLOUD_CAPTURE_MAX = (352, 288)
+DEVICE_FILTER = (
+    "TIME_PLAN,CONNECTION,SWITCH,STATUS,STATUS_EXT,WIFI,NODISTURB,P2P,KMS,HIDDNS"
+)
+RESOURCE_VTM_FILTER = "VTM"
+ANNEX_B_START_CODE = b"\x00\x00\x00\x01"
+MJPEG_BOUNDARY = b"hikframe"
+DEFAULT_STREAM_TYPE = 2
+STREAM_PROBE_TIMEOUT = 5.0

hikcloudstream/auth.py

@@ -0,0 +1,30 @@
+"""Authentication helpers and API response validation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hikcloudstream.exceptions import ApiError, AuthenticationError, CaptchaRequiredError
+
+
+def check_api_meta(payload: dict[str, Any]) -> None:
+    """Raise typed errors when the Hik-Connect meta block indicates failure."""
+    meta = payload.get("meta") or {}
+    code = meta.get("code", 0)
+    if code == 200:
+        return
+    message = str(meta.get("message") or meta.get("langMsg") or "unknown error")
+    raise ApiError(int(code), message)
+
+
+def raise_login_error(payload: dict[str, Any]) -> None:
+    """Map login response codes to typed authentication errors."""
+    meta = payload.get("meta") or {}
+    code = meta.get("code")
+    if code in (1013, 1014):
+        raise AuthenticationError("invalid username or password")
+    if code == 1015:
+        raise CaptchaRequiredError(
+            "CAPTCHA required — log in once via the Hik-Connect app, then retry"
+        )
+    check_api_meta(payload)

hikcloudstream/capture.py

@@ -0,0 +1,37 @@
+"""Cloud snapshot decryption helpers."""
+
+from __future__ import annotations
+
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import unpad
+
+from hikcloudstream._config import HIK_ENCODED_PREFIX, JPEG_MAGIC
+from hikcloudstream.exceptions import CaptureError
+
+
+def aes_key_material(value: str | None) -> bytes:
+    raw = (value or "").encode("utf-8")
+    if len(raw) >= 16:
+        return raw[:16]
+    return raw + b"\x00" * (16 - len(raw))
+
+
+def decrypt_capture(raw: bytes, validate_code: str | None) -> bytes:
+    """Decrypt Hik-Connect encrypted cloud snapshots."""
+    if raw.startswith(JPEG_MAGIC):
+        return raw
+    if not raw.startswith(HIK_ENCODED_PREFIX):
+        raise CaptureError(
+            "unknown image format; provide validate_code for encrypted devices"
+        )
+    if len(raw) <= 48:
+        raise CaptureError("encrypted payload too small")
+
+    key = aes_key_material(validate_code)
+    iv = aes_key_material("01234567")
+    cipher = AES.new(key, AES.MODE_CBC, iv)
+    decrypted = cipher.decrypt(raw[48:])
+    try:
+        return unpad(decrypted, AES.block_size)
+    except ValueError:
+        return decrypted

hikcloudstream/cli/__init__.py

@@ -0,0 +1 @@
+"""Optional CLI entry points (install with [cli] extra)."""

hikcloudstream/cli/_common.py

@@ -0,0 +1,140 @@
+"""Shared CLI helpers."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from hikcloudstream._config import JPEG_MAGIC
+from hikcloudstream.exceptions import CameraNotFoundError
+from hikcloudstream.models import Camera, ClientConfig, Credentials
+
+DEFAULT_API = ClientConfig().api_base_url
+
+
+def credentials_from_args(args: argparse.Namespace) -> Credentials:
+    username = args.username or os.environ.get("HIK_CONNECT_USER", "")
+    password = args.password or os.environ.get("HIK_CONNECT_PASSWORD", "")
+    if not username or not password:
+        raise RuntimeError(
+            "username and password required (arguments or HIK_CONNECT_USER / HIK_CONNECT_PASSWORD)"
+        )
+    return Credentials(username=username, password=password)
+
+
+def add_auth_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "username",
+        nargs="?",
+        default=None,
+        help="Hik-Connect account (or HIK_CONNECT_USER env)",
+    )
+    parser.add_argument(
+        "password",
+        nargs="?",
+        default=None,
+        help="Hik-Connect password (or HIK_CONNECT_PASSWORD env)",
+    )
+    parser.add_argument(
+        "camera",
+        nargs="?",
+        type=int,
+        help="Camera number from --list (1-based index)",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List available cameras and exit",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print camera list as JSON (with --list)",
+    )
+    parser.add_argument(
+        "--api",
+        default=DEFAULT_API,
+        help=f"API base URL (default: {DEFAULT_API})",
+    )
+
+
+def resolve_camera(cameras: list[Camera], camera_no: int) -> Camera:
+    if camera_no < 1 or camera_no > len(cameras):
+        raise CameraNotFoundError(
+            f"invalid camera {camera_no}. Use --list (1..{len(cameras)})."
+        )
+    return cameras[camera_no - 1]
+
+
+def print_camera_list(cameras: list[Camera]) -> None:
+    if not cameras:
+        print("No cameras found for this account.")
+        return
+    print(f"{'#':>3}  {'Camera':<28} {'Device':<20} {'Serial':<12} Ch")
+    print("-" * 80)
+    for camera in cameras:
+        print(
+            f"{camera.index:>3}  {camera.name[:28]:<28} "
+            f"{camera.device_name[:20]:<20} {camera.device_serial:<12} "
+            f"{camera.channel_no}"
+        )
+
+
+def dump_camera_list_json(cameras: list[Camera]) -> None:
+    print(
+        json.dumps(
+            [
+                {
+                    "index": c.index,
+                    "name": c.name,
+                    "device": c.device_name,
+                    "deviceSerial": c.device_serial,
+                    "channelNo": c.channel_no,
+                }
+                for c in cameras
+            ],
+            indent=2,
+            ensure_ascii=False,
+        )
+    )
+
+
+def image_dimensions(image_bytes: bytes) -> tuple[int, int]:
+    from PIL import Image
+
+    image = Image.open(io.BytesIO(image_bytes))
+    return image.size
+
+
+def save_image(image_bytes: bytes, path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(image_bytes)
+    return path
+
+
+def show_image(image_bytes: bytes) -> None:
+    from PIL import Image
+
+    image = Image.open(io.BytesIO(image_bytes))
+    if image.mode not in ("RGB", "L"):
+        image = image.convert("RGB")
+    image.show()
+
+
+def open_path(path: Path) -> None:
+    if sys.platform.startswith("linux"):
+        subprocess.run(["xdg-open", str(path)], check=False)
+    elif sys.platform == "darwin":
+        subprocess.run(["open", str(path)], check=False)
+    else:
+        raise RuntimeError("no default viewer configured for this platform")
+
+
+def ensure_jpeg(image_bytes: bytes) -> None:
+    if not image_bytes.startswith(JPEG_MAGIC):
+        raise RuntimeError("output is not a valid JPEG")

hikcloudstream/cli/snapshot.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Cloud snapshot CLI — low-resolution thumbnail via Hik-Connect API."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import httpx
+
+from hikcloudstream import CLOUD_CAPTURE_MAX, HikConnectClient
+from hikcloudstream.cli._common import (
+    add_auth_args,
+    credentials_from_args,
+    dump_camera_list_json,
+    ensure_jpeg,
+    image_dimensions,
+    open_path,
+    print_camera_list,
+    resolve_camera,
+    save_image,
+    show_image,
+)
+from hikcloudstream.exceptions import HikCloudStreamError
+from hikcloudstream.models import ClientConfig
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Capture a cloud snapshot from Hik-Connect cameras.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  hikcloudstream-snapshot user pass --list\n"
+            "  hikcloudstream-snapshot user pass 3\n"
+            "  hikcloudstream-snapshot user pass 3 -o camera3.jpg\n"
+            "  hikcloudstream-stream user pass 3 -o frame-hd.jpg   # higher-res live frame\n"
+        ),
+    )
+    add_auth_args(parser)
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Save snapshot to this file (default: camera-<n>.jpg)",
+    )
+    parser.add_argument(
+        "--show",
+        action="store_true",
+        help="Open the snapshot with the default image viewer",
+    )
+    parser.add_argument(
+        "--validate-code",
+        help="Device encryption code (only needed for encrypted snapshots)",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    config = ClientConfig(api_base_url=args.api)
+
+    try:
+        creds = credentials_from_args(args)
+    except RuntimeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    with HikConnectClient(config) as client:
+        try:
+            client.login(creds)
+            cameras = client.list_cameras()
+
+            if args.list:
+                if args.json:
+                    dump_camera_list_json(cameras)
+                else:
+                    print_camera_list(cameras)
+                return 0
+
+            if args.camera is None:
+                print("Specify a camera number or use --list.", file=sys.stderr)
+                return 2
+
+            camera = resolve_camera(cameras, args.camera)
+            image_bytes = client.capture_snapshot(
+                camera,
+                validate_code=args.validate_code,
+            )
+            ensure_jpeg(image_bytes)
+
+            output_path = args.output or Path(f"camera-{args.camera}.jpg")
+            saved = save_image(image_bytes, output_path)
+
+            width, height = image_dimensions(image_bytes)
+            print(
+                f"Saved: {saved} ({camera.name} / ch {camera.channel_no}, "
+                f"{width}x{height})"
+            )
+            if (width, height) == CLOUD_CAPTURE_MAX:
+                print(
+                    "Note: cloud snapshot is capped at "
+                    f"{CLOUD_CAPTURE_MAX[0]}x{CLOUD_CAPTURE_MAX[1]} by Hik-Connect API. "
+                    "Use hikcloudstream-stream for a live-stream frame.",
+                    file=sys.stderr,
+                )
+
+            if args.show:
+                try:
+                    show_image(image_bytes)
+                except Exception:
+                    open_path(saved)
+
+            return 0
+        except httpx.HTTPError as exc:
+            print(f"HTTP error: {exc}", file=sys.stderr)
+            return 1
+        except HikCloudStreamError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hikcloudstream/cli/stream.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Live stream CLI — open Hik-Connect camera streams and capture HD frames."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import threading
+import time
+from pathlib import Path
+
+import httpx
+
+from hikcloudstream import HikConnectClient
+from hikcloudstream.cli._common import (
+    add_auth_args,
+    credentials_from_args,
+    dump_camera_list_json,
+    ensure_jpeg,
+    image_dimensions,
+    open_path,
+    print_camera_list,
+    resolve_camera,
+    show_image,
+)
+from hikcloudstream.exceptions import HikCloudStreamError
+from hikcloudstream.models import ClientConfig, StreamType
+from hikcloudstream.stream import capture_live_snapshot, record_stream, require_ffmpeg
+from hikcloudstream.stream.sinks.http import play_url, serve_stream_proxy
+
+
+def _parse_duration(value: str) -> float:
+    match = re.fullmatch(r"(\d+(?:\.\d+)?)(s|sec|secs|second|seconds|m|min|mins)?", value)
+    if not match:
+        raise argparse.ArgumentTypeError(
+            f"invalid duration {value!r}; use examples like 10s or 1m"
+        )
+    amount = float(match.group(1))
+    unit = match.group(2) or "s"
+    if unit.startswith("m"):
+        return amount * 60.0
+    return amount
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Open live Hik-Connect camera streams and capture HD snapshots.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  hikcloudstream-stream user pass --list\n"
+            "  hikcloudstream-stream user pass 1 --proxy\n"
+            "  hikcloudstream-stream user pass 1 --proxy --show\n"
+            "  hikcloudstream-stream user pass 1 -o frame-hd.jpg\n"
+            "  hikcloudstream-stream user pass 1 --record clip.ts --duration 15s\n"
+        ),
+    )
+    add_auth_args(parser)
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Save a live-stream snapshot to this JPEG file",
+    )
+    parser.add_argument(
+        "--record",
+        type=Path,
+        metavar="FILE",
+        help="Record live stream to an MPEG-TS file",
+    )
+    parser.add_argument(
+        "--duration",
+        type=_parse_duration,
+        default=10.0,
+        help="Recording/snapshot warmup duration (default: 10s)",
+    )
+    parser.add_argument(
+        "--proxy",
+        action="store_true",
+        help="Serve the live stream over HTTP (blocks until Ctrl+C)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Proxy bind host (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8558,
+        help="Proxy bind port (default: 8558)",
+    )
+    parser.add_argument(
+        "--show",
+        action="store_true",
+        help="With --proxy, open the stream in ffplay",
+    )
+    parser.add_argument(
+        "--ffmpeg",
+        default="ffmpeg",
+        help="FFmpeg executable (default: ffmpeg)",
+    )
+    parser.add_argument(
+        "--validate-code",
+        help="Device encryption code (only if the app asks for one)",
+    )
+    parser.add_argument(
+        "--main-stream",
+        action="store_true",
+        help="Use main stream (stream=1; higher resolution, not all cameras support it)",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+
+    if not args.list and args.camera is None:
+        print("Specify a camera number or use --list.", file=sys.stderr)
+        return 2
+
+    action_count = sum(1 for flag in (args.output, args.record, args.proxy) if flag)
+    if not args.list and action_count != 1:
+        print(
+            "Choose exactly one action: -o/--output, --record, or --proxy.",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        creds = credentials_from_args(args)
+    except RuntimeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    config = ClientConfig(api_base_url=args.api)
+    stream_type = StreamType.MAIN if args.main_stream else StreamType.AUTO
+
+    with HikConnectClient(config) as client:
+        try:
+            client.login(creds)
+            cameras = client.list_cameras()
+
+            if args.list:
+                if args.json:
+                    dump_camera_list_json(cameras)
+                else:
+                    print_camera_list(cameras)
+                return 0
+
+            camera = resolve_camera(cameras, args.camera)
+            ffmpeg = require_ffmpeg(args.ffmpeg)
+
+            if args.output:
+                saved = capture_live_snapshot(
+                    client,
+                    camera,
+                    args.output,
+                    warmup_seconds=args.duration,
+                    ffmpeg_path=ffmpeg,
+                    validate_code=args.validate_code,
+                    stream_type=stream_type,
+                )
+                image_bytes = saved.read_bytes()
+                ensure_jpeg(image_bytes)
+                width, height = image_dimensions(image_bytes)
+                print(
+                    f"Saved: {saved} ({camera.name} / ch {camera.channel_no}, "
+                    f"{width}x{height}, live stream)"
+                )
+                if args.show:
+                    try:
+                        show_image(image_bytes)
+                    except Exception:
+                        open_path(saved)
+                return 0
+
+            if args.record:
+                saved = record_stream(
+                    client,
+                    camera,
+                    args.record,
+                    duration_seconds=args.duration,
+                    ffmpeg_path=ffmpeg,
+                    validate_code=args.validate_code,
+                    stream_type=stream_type,
+                )
+                print(
+                    f"Recorded: {saved} ({camera.name} / ch {camera.channel_no}, "
+                    f"{args.duration:.0f}s)"
+                )
+                return 0
+
+            stream_url = (
+                f"http://{args.host}:{args.port}/"
+                f"{camera.device_serial}-{camera.channel_no}.ts"
+            )
+            if args.show:
+
+                def _delayed_play() -> None:
+                    time.sleep(0.8)
+                    play_url(stream_url, player="ffplay")
+
+                threading.Thread(target=_delayed_play, daemon=True).start()
+
+            serve_stream_proxy(
+                client,
+                camera,
+                host=args.host,
+                port=args.port,
+                ffmpeg_path=ffmpeg,
+                validate_code=args.validate_code,
+                stream_type=stream_type,
+            )
+            return 0
+        except httpx.HTTPError as exc:
+            print(f"HTTP error: {exc}", file=sys.stderr)
+            return 1
+        except HikCloudStreamError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())