Metadata-Version: 2.3
Name: cang
Version: 2026.7.24
Summary: Snapshot archiver for IP cameras — ingests, indexes, and browses surveillance snapshots.
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.139.2
Requires-Dist: uvicorn~=0.51.0
Requires-Python: >=3.12
Project-URL: Issues, https://codeberg.org/MinimalNVR/cang/issues
Project-URL: Source, https://codeberg.org/MinimalNVR/cang
Project-URL: Changelog, https://codeberg.org/MinimalNVR/cang/raw/branch/main/CHANGELOG.md
Project-URL: Documentation, https://cang.marvin8.zone/latest/
Description-Content-Type: text/markdown

<p align="center">
  <img src="icon/cang_wordmark_light.png" alt="cang" width="280" height="80">
</p>

# Cang (藏) — Snapshot Archiver for IP Cameras

[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENCE)
[![Status: Late beta](https://img.shields.io/badge/status-late%20beta-yellow)]()
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://cang.marvin8.zone/latest/)
[![Forgejo CI](https://codeberg.org/MinimalNVR/cang/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/MinimalNVR/cang/actions)
[![pepy downloads](https://img.shields.io/pepy/dt/cang)](https://pepy.tech/project/cang)
[![gitleaks](https://img.shields.io/badge/protected%20by-gitleaks-blue)](https://github.com/gitleaks/gitleaks)
[![pysentry](https://img.shields.io/badge/audited%20by-pysentry-blue)](https://codeberg.org/marvin8/pysentry)
[![ty](https://img.shields.io/badge/typed%20by-ty-blue)](https://github.com/astral-sh/ty)
[![complexipy](https://img.shields.io/badge/analysed%20by-complexipy-blue)](https://github.com/rohaquinlop/complexipy)

**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 snapshot archiver for IP cameras. Cameras handle motion detection
and object recognition themselves, deposit snapshot images into watched folders,
and Cang indexes, groups, and serves them through a clean FastAPI web UI.

Inspired by [LazyNVR](https://codeberg.org/LazyNVR/lazynvr-sources), written in Python.

## What it does

- Watches camera directories for snapshot JPEGs deposited by cameras
- Ingests all snapshots into SQLite with motion-event metadata
- Groups consecutive motion snapshots into events using a configurable time-gap threshold (60 s)
- Applies tiered retention: motion snapshots (default 30 days), background snapshots (14 days) — both configurable
- Serves a FastAPI + Jinja2 web UI with a scrubber for browsing snapshots by day and camera
- Runs anywhere Python is available; can also be deployed in a container

## What it does not do

- No RTSP / live-stream pulling
- No video clip processing or storage
- No multi-user roles or cloud sync

## Status

Late beta — core functionality (Dahua adapter, snapshot ingestion, event grouping, tiered retention, web UI) is working.
See the [documentation](https://cang.marvin8.zone/latest/) for installation
and configuration.

## Licence

Copyright (C) 2026 Marvin8

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.
