cang 0.1.0__tar.gz

cang-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.3
+Name: cang
+Version: 0.1.0
+Summary: Lightweight NVR: watches folders, transcodes to H.264/MP4, serves a FastAPI web UI.
+Author: Marvin8
+Author-email: Marvin8 <marvin8@tuta.io>
+License: AGPL-3.0-or-later
+Requires-Dist: aiosqlite~=0.22.1
+Requires-Dist: fastapi[standard]~=0.136.3
+Requires-Dist: uvicorn~=0.48.0
+Requires-Dist: watchdog~=6.0.0
+Requires-Python: >=3.12
+Project-URL: Issues, https://codeberg.org/MinimalNVR/cang/issues
+Project-URL: Source, https://codeberg.org/MinimalNVR/cang
+Description-Content-Type: text/markdown
+
+# Cang (藏) — Minimal Python Network Video Recorder
+
+[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENCE)
+[![Status: Idea phase](https://img.shields.io/badge/status-idea%20phase-orange)]()
+[![Woodpecker CI](https://ci.codeberg.org/api/badges/MinimalNVR/cang/status.svg)](https://ci.codeberg.org/MinimalNVR/cang)
+
+**Cang** (藏, *cáng*, roughly "tsang" with a rising tone) — Chinese for "to store /
+to archive". Secondary meaning: "hidden", quietly apt for security footage.
+The name reflects the project's philosophy: cameras do all the clever work;
+Cang just keeps what they send.
+
+A lightweight NVR that does as little as possible: cameras handle motion detection
+and object recognition themselves, deposit video clips and snapshot images into a
+watched folder, and Cang transcodes, indexes, and serves them through a clean web UI
+grouped by day and hour.
+
+Inspired by [LazyNVR](https://codeberg.org/LazyNVR/lazynvr-sources), written in Python.
+
+## What it does
+
+- Watches `incoming/<camera>/` directories for clips deposited by cameras
+- Transcodes to H.264/MP4 with `-movflags +faststart` (browser-seekable)
+- Indexes clips in SQLite: camera, timestamp, duration, thumbnail
+- Serves a FastAPI + Jinja2 web UI: day → hour view, click-to-play
+- Keeps clips marked as important; auto-expires the rest after configurable days
+- Runs as a single Podman container; storage is a bind-mounted volume
+
+## What it does not do
+
+- No RTSP / live-stream pulling
+- No motion detection or object recognition (delegated to cameras)
+- No multi-user roles or cloud sync
+
+## Status
+
+Idea phase. See [concept.md](concept.md) for the full design specification.
+
+## Licence
+
+Copyright (C) 2026 contributors
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+See [LICENCE](LICENCE) for the full text.

cang-0.1.0/README.md

@@ -0,0 +1,47 @@
+# Cang (藏) — Minimal Python Network Video Recorder
+
+[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENCE)
+[![Status: Idea phase](https://img.shields.io/badge/status-idea%20phase-orange)]()
+[![Woodpecker CI](https://ci.codeberg.org/api/badges/MinimalNVR/cang/status.svg)](https://ci.codeberg.org/MinimalNVR/cang)
+
+**Cang** (藏, *cáng*, roughly "tsang" with a rising tone) — Chinese for "to store /
+to archive". Secondary meaning: "hidden", quietly apt for security footage.
+The name reflects the project's philosophy: cameras do all the clever work;
+Cang just keeps what they send.
+
+A lightweight NVR that does as little as possible: cameras handle motion detection
+and object recognition themselves, deposit video clips and snapshot images into a
+watched folder, and Cang transcodes, indexes, and serves them through a clean web UI
+grouped by day and hour.
+
+Inspired by [LazyNVR](https://codeberg.org/LazyNVR/lazynvr-sources), written in Python.
+
+## What it does
+
+- Watches `incoming/<camera>/` directories for clips deposited by cameras
+- Transcodes to H.264/MP4 with `-movflags +faststart` (browser-seekable)
+- Indexes clips in SQLite: camera, timestamp, duration, thumbnail
+- Serves a FastAPI + Jinja2 web UI: day → hour view, click-to-play
+- Keeps clips marked as important; auto-expires the rest after configurable days
+- Runs as a single Podman container; storage is a bind-mounted volume
+
+## What it does not do
+
+- No RTSP / live-stream pulling
+- No motion detection or object recognition (delegated to cameras)
+- No multi-user roles or cloud sync
+
+## Status
+
+Idea phase. See [concept.md](concept.md) for the full design specification.
+
+## Licence
+
+Copyright (C) 2026 contributors
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+See [LICENCE](LICENCE) for the full text.

cang-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["uv_build>=0.10.0,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "cang"
+version = "0.1.0"
+authors = [
+    { name = "Marvin8", email = "marvin8@tuta.io" },
+]
+description = "Lightweight NVR: watches folders, transcodes to H.264/MP4, serves a FastAPI web UI."
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+requires-python = ">=3.12"
+dependencies = [
+    "aiosqlite~=0.22.1",
+    "fastapi[standard]~=0.136.3",
+    "uvicorn~=0.48.0",
+    "watchdog~=6.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "complexipy~=5.5.0",
+    "git-cliff~=2.13.1",
+    "httpx~=0.28.1",
+    "nox-uv~=0.8.0",
+    "prek~=0.4.3",
+    "ty~=0.0.40",
+    "ruff~=0.15.14",
+    "tryke~=0.0.29",
+]
+
+[project.scripts]
+cang = "cang.cli:main"
+
+[project.urls]
+Issues = "https://codeberg.org/MinimalNVR/cang/issues"
+Source = "https://codeberg.org/MinimalNVR/cang"
+
+[tool.uv]
+constraint-dependencies = [
+    "starlette>=1.0.1",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.tryke]
+src = ["src"]

cang-0.1.0/src/cang/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+from importlib.metadata import version
+
+__version__ = version("cang")

cang-0.1.0/src/cang/adapters/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+from cang.adapters.base import BaseAdapter
+from cang.adapters.dahua import DahuaAdapter
+
+
+def make_adapter(adapter_type: str) -> BaseAdapter:
+    if adapter_type == "dahua":
+        return DahuaAdapter()
+    raise ValueError(f"unknown adapter: {adapter_type!r}")

cang-0.1.0/src/cang/adapters/base.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from datetime import date, time
+from pathlib import Path
+
+
+@dataclass
+class IncomingClip:
+    path: Path
+    date: date
+    channel: str
+    start: time
+    end: time
+    motion: bool
+    first_frame: bool
+    snapshots: list[Path] = field(default_factory=list)
+
+
+class BaseAdapter(ABC):
+    @abstractmethod
+    def scan(self, root: Path) -> Iterator[IncomingClip]: ...

cang-0.1.0/src/cang/adapters/dahua.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+import re
+from collections.abc import Iterator
+from datetime import date, time
+from pathlib import Path
+
+from cang.adapters.base import BaseAdapter, IncomingClip
+
+_CLIP_RE = re.compile(r"^(\d{2})\.(\d{2})\.(\d{2})-(\d{2})\.(\d{2})\.(\d{2})(.*)")
+_SS_RE = re.compile(r"^(\d{2})")
+
+
+def _parse_clip_stem(stem: str) -> tuple[time, time, bool, bool]:
+    m = _CLIP_RE.match(stem)
+    if not m:
+        raise ValueError(f"unrecognised clip stem: {stem!r}")
+    sh, sm, ss, eh, em, es, flags = m.groups()
+    return (
+        time(int(sh), int(sm), int(ss)),
+        time(int(eh), int(em), int(es)),
+        "[M]" in flags,
+        "[F]" in flags,
+    )
+
+
+def _parse_snapshot_time(jpg: Path) -> time:
+    mm_dir = jpg.parent
+    hh_dir = mm_dir.parent
+    ss_m = _SS_RE.match(jpg.stem)
+    if not ss_m:
+        raise ValueError(f"unrecognised snapshot filename: {jpg.name!r}")
+    return time(int(hh_dir.name), int(mm_dir.name), int(ss_m.group(1)))
+
+
+def _minute_dirs_in_range(jpg_root: Path, start: time, end: time) -> Iterator[Path]:
+    if not jpg_root.is_dir():
+        return
+    for hh_dir in sorted(jpg_root.iterdir()):
+        if not hh_dir.is_dir():
+            continue
+        hh = int(hh_dir.name)
+        if not (start.hour <= hh <= end.hour):
+            continue
+        for mm_dir in sorted(hh_dir.iterdir()):
+            if not mm_dir.is_dir():
+                continue
+            mm = int(mm_dir.name)
+            if (start.hour, start.minute) <= (hh, mm) <= (end.hour, end.minute):
+                yield mm_dir
+
+
+def _collect_snapshots(jpg_root: Path, start: time, end: time) -> list[Path]:
+    results: list[Path] = []
+    for mm_dir in _minute_dirs_in_range(jpg_root, start, end):
+        for jpg in sorted(mm_dir.glob("*.jpg")):
+            try:
+                if start <= _parse_snapshot_time(jpg) <= end:
+                    results.append(jpg)
+            except ValueError:
+                continue
+    return results
+
+
+def _date_dirs(root: Path) -> Iterator[tuple[date, Path]]:
+    for date_dir in sorted(root.iterdir()):
+        if not date_dir.is_dir():
+            continue
+        try:
+            yield date.fromisoformat(date_dir.name), date_dir
+        except ValueError:
+            continue
+
+
+def _clips_in_channel(clip_date: date, channel_dir: Path) -> Iterator[IncomingClip]:
+    dav_root = channel_dir / "dav"
+    jpg_root = channel_dir / "jpg"
+    if not dav_root.is_dir():
+        return
+    for hh_dir in sorted(dav_root.iterdir()):
+        if not hh_dir.is_dir():
+            continue
+        for dav in sorted(hh_dir.glob("*.dav")):
+            try:
+                start, end, motion, first_frame = _parse_clip_stem(dav.stem)
+            except ValueError:
+                continue
+            yield IncomingClip(
+                path=dav,
+                date=clip_date,
+                channel=channel_dir.name,
+                start=start,
+                end=end,
+                motion=motion,
+                first_frame=first_frame,
+                snapshots=_collect_snapshots(jpg_root, start, end),
+            )
+
+
+class DahuaAdapter(BaseAdapter):
+    def scan(self, root: Path) -> Iterator[IncomingClip]:
+        for clip_date, date_dir in _date_dirs(root):
+            for channel_dir in sorted(date_dir.iterdir()):
+                if not channel_dir.is_dir():
+                    continue
+                yield from _clips_in_channel(clip_date, channel_dir)

cang-0.1.0/src/cang/cli.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+import argparse
+import asyncio
+from pathlib import Path
+
+import uvicorn
+
+from cang.config import load_config
+from cang.db import open_db
+from cang.pipeline import Pipeline
+from cang.web.app import create_app
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Cang NVR — start the web UI")
+    parser.add_argument("config", type=Path, help="Path to cang.toml")
+    return parser.parse_args()
+
+
+async def _run(config_path: Path) -> None:
+    cfg = load_config(config_path)
+    async with open_db(cfg.server.output_dir / "cang.db") as db:
+        pipeline = Pipeline(cfg.server.output_dir)
+        app = create_app(cfg, db, pipeline)
+        server = uvicorn.Server(
+            uvicorn.Config(app, host=cfg.web.host, port=cfg.web.port, log_level="info")
+        )
+        await server.serve()
+
+
+def main() -> None:
+    asyncio.run(_run(_parse_args().config))

cang-0.1.0/src/cang/config.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_KNOWN_ADAPTERS = {"dahua"}
+
+
+@dataclass
+class ServerConfig:
+    output_dir: Path
+    scan_interval: int = 300
+
+
+@dataclass
+class CameraConfig:
+    name: str
+    adapter: str
+    root: Path
+    delete_after_transcode: bool = False
+
+
+@dataclass
+class WebConfig:
+    host: str = "0.0.0.0"
+    port: int = 8080
+    username: str | None = None
+    password: str | None = None
+
+
+@dataclass
+class AppConfig:
+    server: ServerConfig
+    cameras: list[CameraConfig]
+    web: WebConfig = field(default_factory=WebConfig)
+
+
+def _parse_server(raw: dict) -> ServerConfig:
+    try:
+        output_dir = raw["output_dir"]
+    except KeyError as exc:
+        raise ValueError(
+            "config: [server] is missing required key 'output_dir'"
+        ) from exc
+    scan_interval = int(raw.get("scan_interval", 300))
+    return ServerConfig(output_dir=Path(output_dir), scan_interval=scan_interval)
+
+
+def _parse_camera(raw: dict, index: int) -> CameraConfig:
+    for key in ("name", "adapter", "root"):
+        if key not in raw:
+            raise ValueError(
+                f"config: [[camera]] entry {index} is missing required key '{key}'"
+            )
+    adapter = raw["adapter"]
+    if adapter not in _KNOWN_ADAPTERS:
+        known = ", ".join(sorted(_KNOWN_ADAPTERS))
+        raise ValueError(
+            f"config: [[camera]] entry {index} has unknown adapter {adapter!r}"
+            f" — must be one of: {known}"
+        )
+    return CameraConfig(
+        name=raw["name"],
+        adapter=adapter,
+        root=Path(raw["root"]),
+        delete_after_transcode=bool(raw.get("delete_after_transcode", False)),
+    )
+
+
+def _parse_web(raw: dict) -> WebConfig:
+    username = raw.get("username")
+    password = raw.get("password")
+    if (username is None) != (password is None):
+        raise ValueError(
+            "config: [web] requires both 'username' and 'password', or neither"
+        )
+    return WebConfig(
+        host=raw.get("host", "0.0.0.0"),
+        port=raw.get("port", 8080),
+        username=username,
+        password=password,
+    )
+
+
+def load_config(path: Path) -> AppConfig:
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    try:
+        server_raw = data["server"]
+    except KeyError as exc:
+        raise ValueError("config: missing required section [server]") from exc
+    server = _parse_server(server_raw)
+    cameras = [_parse_camera(cam, i) for i, cam in enumerate(data.get("camera", []))]
+    web = _parse_web(data.get("web", {}))
+    return AppConfig(server=server, cameras=cameras, web=web)

cang-0.1.0/src/cang/db.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+
+import aiosqlite
+
+from cang.adapters.base import IncomingClip
+
+_DDL_V1 = """
+CREATE TABLE IF NOT EXISTS clips (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    camera       TEXT    NOT NULL,
+    recorded_at  TEXT    NOT NULL,
+    recorded_end TEXT    NOT NULL,
+    duration_s   REAL    NOT NULL,
+    filename     TEXT    NOT NULL,
+    thumbnail    TEXT,
+    flags        TEXT    NOT NULL DEFAULT '',
+    keep         INTEGER NOT NULL DEFAULT 0,
+    ingested_at  TEXT    NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_clips_unique
+    ON clips (camera, recorded_at, filename);
+DELETE FROM schema_version;
+INSERT INTO schema_version (version) VALUES (1);
+"""
+
+_DDL_V2 = """
+ALTER TABLE clips ADD COLUMN status TEXT NOT NULL DEFAULT 'done';
+DELETE FROM schema_version;
+INSERT INTO schema_version (version) VALUES (2);
+"""
+
+
+async def _apply_v1(db: aiosqlite.Connection) -> None:
+    await db.executescript(_DDL_V1)
+    await db.commit()
+
+
+async def _apply_v2(db: aiosqlite.Connection) -> None:
+    await db.executescript(_DDL_V2)
+    await db.commit()
+
+
+async def _migrate(db: aiosqlite.Connection) -> None:
+    await db.execute(
+        "CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)"
+    )
+    await db.commit()
+    async with db.execute("SELECT version FROM schema_version") as cur:
+        row = await cur.fetchone()
+    version = row[0] if row else 0
+    if version < 1:
+        await _apply_v1(db)
+        version = 1
+    if version < 2:
+        await _apply_v2(db)
+
+
+@asynccontextmanager
+async def open_db(path: Path | str) -> AsyncIterator[aiosqlite.Connection]:
+    async with aiosqlite.connect(path) as db:
+        db.row_factory = aiosqlite.Row
+        await _migrate(db)
+        yield db
+
+
+async def insert_clip(
+    db: aiosqlite.Connection,
+    clip: IncomingClip,
+    camera: str,
+    filename: str,
+) -> int:
+    recorded_at = datetime.combine(clip.date, clip.start).isoformat()
+    recorded_end = datetime.combine(clip.date, clip.end).isoformat()
+    duration_s = (
+        clip.end.hour * 3600
+        + clip.end.minute * 60
+        + clip.end.second
+        - clip.start.hour * 3600
+        - clip.start.minute * 60
+        - clip.start.second
+    )
+    flags = ("M" if clip.motion else "") + ("F" if clip.first_frame else "")
+    thumbnail = str(clip.snapshots[0]) if clip.snapshots else None
+    ingested_at = datetime.now(UTC).replace(tzinfo=None).isoformat()
+    cursor = await db.execute(
+        """
+        INSERT OR IGNORE INTO clips
+            (camera, recorded_at, recorded_end, duration_s, filename,
+             thumbnail, flags, ingested_at, status)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending')
+        """,
+        (
+            camera,
+            recorded_at,
+            recorded_end,
+            duration_s,
+            filename,
+            thumbnail,
+            flags,
+            ingested_at,
+        ),
+    )
+    await db.commit()
+    return cursor.lastrowid or 0
+
+
+async def set_keep(db: aiosqlite.Connection, clip_id: int, keep: bool) -> None:
+    await db.execute("UPDATE clips SET keep = ? WHERE id = ?", (int(keep), clip_id))
+    await db.commit()
+
+
+async def set_clip_done(
+    db: aiosqlite.Connection,
+    clip_id: int,
+    thumbnail: str | None = None,
+) -> None:
+    if thumbnail is not None:
+        await db.execute(
+            "UPDATE clips SET status = 'done', thumbnail = ? WHERE id = ?",
+            (thumbnail, clip_id),
+        )
+    else:
+        await db.execute("UPDATE clips SET status = 'done' WHERE id = ?", (clip_id,))
+    await db.commit()
+
+
+async def get_clip_by_camera_filename(
+    db: aiosqlite.Connection,
+    camera: str,
+    filename: str,
+) -> aiosqlite.Row | None:
+    async with db.execute(
+        "SELECT * FROM clips WHERE camera = ? AND filename = ?",
+        (camera, filename),
+    ) as cur:
+        return await cur.fetchone()
+
+
+async def count_pending_for_day(db: aiosqlite.Connection, day: str) -> int:
+    async with db.execute(
+        "SELECT COUNT(*) FROM clips WHERE DATE(recorded_at) = ? AND status = 'pending'",
+        (day,),
+    ) as cur:
+        row = await cur.fetchone()
+    return row[0] if row else 0
+
+
+async def delete_expired(db: aiosqlite.Connection, cutoff: datetime) -> int:
+    cursor = await db.execute(
+        "DELETE FROM clips WHERE keep = 0 AND recorded_at < ?",
+        (cutoff.isoformat(),),
+    )
+    await db.commit()
+    return cursor.rowcount
+
+
+async def list_days(db: aiosqlite.Connection) -> list[str]:
+    async with db.execute(
+        "SELECT DISTINCT DATE(recorded_at) AS day FROM clips ORDER BY day DESC"
+    ) as cur:
+        rows = await cur.fetchall()
+    return [row["day"] for row in rows]
+
+
+async def list_days_with_stats(db: aiosqlite.Connection) -> list[aiosqlite.Row]:
+    async with db.execute(
+        """
+        SELECT
+            DATE(recorded_at) AS day,
+            COUNT(*)          AS clip_count,
+            SUM(CASE WHEN flags LIKE '%M%' THEN 1 ELSE 0 END) AS motion_count,
+            ROUND(SUM(duration_s) / 3600.0, 2) AS total_hours
+        FROM clips
+        GROUP BY day
+        ORDER BY day DESC
+        """
+    ) as cur:
+        return list(await cur.fetchall())
+
+
+async def list_clips_for_day(
+    db: aiosqlite.Connection,
+    day: str,
+    camera: str | None = None,
+) -> list[aiosqlite.Row]:
+    if camera is None:
+        async with db.execute(
+            "SELECT * FROM clips WHERE DATE(recorded_at) = ? AND status = 'done'"
+            " ORDER BY recorded_at ASC",
+            (day,),
+        ) as cur:
+            return list(await cur.fetchall())
+    async with db.execute(
+        "SELECT * FROM clips WHERE DATE(recorded_at) = ? AND camera = ?"
+        " AND status = 'done' ORDER BY recorded_at ASC",
+        (day, camera),
+    ) as cur:
+        return list(await cur.fetchall())
+
+
+async def get_clip(db: aiosqlite.Connection, clip_id: int) -> aiosqlite.Row | None:
+    async with db.execute("SELECT * FROM clips WHERE id = ?", (clip_id,)) as cur:
+        return await cur.fetchone()