Viseron

Viseron is a self‑hosted, local‑only Network Video Recorder (NVR) that blends traditional surveillance features with modern computer vision. At its core, it ingests video streams from IP cameras or local sources and applies a pipeline of components—each encapsulating a distinct processing task such as motion detection, object classification, or face recognition. The architecture is deliberately modular: developers can enable, disable, or replace components without touching the core runtime, allowing fine‑tuned customizations for specific use cases.

Technical Stack

• Language & Runtime: Python 3.10+ powers the entire stack, leveraging asynchronous IO (asyncio) to handle multiple camera feeds concurrently.
• Web Interface: Built on FastAPI, providing a lightweight REST API and an interactive UI served via Jinja2 templates.
• Configuration: YAML files parsed by pyyaml; the web editor exposes a schema‑driven form for safe editing.
• Storage: SQLite (default) or PostgreSQL for event metadata; video files are stored on the host filesystem, optionally in a network share.
• Computer‑Vision Backbone: OpenCV for frame extraction, with optional hardware acceleration via CUDA, Google Coral EdgeTPU, or NVIDIA Jetson libraries.
• Containerization: Docker images are published to GitHub Container Registry, with pre‑built layers for each supported accelerator.

Core Capabilities

• Component System: Each component implements a standardized interface (setup, process_frame, shutdown). Developers can ship new components as Python packages and register them via a simple entry‑point.
• Event API: Exposes WebSocket and REST endpoints to query events, stream thumbnails, or trigger actions.
• Webhooks: Configurable HTTP callbacks for motion, object, or face events, enabling integration with home‑automation platforms.
• Exporters: Built‑in support for RTSP, HLS, and ONVIF; custom exporters can be added by implementing the Exporter protocol.
• Security: All communication is HTTPS‑enabled via self‑signed certificates; authentication can be extended with OAuth2 or custom middleware.

Deployment & Infrastructure

• Self‑Hosting: A single Docker container suffices for small deployments; multi‑node scaling can be achieved by running separate instances behind a reverse proxy and sharing the same SQLite/PostgreSQL database.
• Hardware Acceleration: The container automatically detects available accelerators; environment variables (CUDA_VISIBLE_DEVICES, CORAL_DEVICE) control which device a component uses.
• Resource Management: Components expose CPU and memory usage; the runtime can throttle processing based on system load, ensuring real‑time performance even on embedded boards like Jetson Nano.

Integration & Extensibility

• Plugin API: Developers can create custom components, exporters, or analytics modules. The plugin registry is discovered at runtime via pkg_resources.
• Scripting: A Python REPL exposed through the web UI allows ad‑hoc scripting against live feeds.
• Configuration Hooks: YAML templates expose hooks for conditional logic (e.g., enable face recognition only during night mode).
• Community Contribs: The project hosts a growing list of community components (e.g., DeepSORT tracking, YOLOv5 inference) that can be dropped into the components/ directory.

Developer Experience

• Documentation: The official site (viseron.netlify.app) provides a component explorer, API reference, and step‑by‑step guides.
• Testing: Unit tests use pytest with fixtures for mock camera streams; CI runs on GitHub Actions.
• Support: Active discussions and issue trackers on GitHub, plus a dedicated Discord channel for rapid feedback.
• Licensing: MIT‑licensed, allowing unrestricted commercial use and modification.

Use Cases

1. Home Automation – Integrate motion events with smart lights via webhooks.
2. Industrial Monitoring – Deploy on a Raspberry Pi cluster with Coral EdgeTPU for real‑time defect detection.
3. Security Audits – Use the event API to archive and replay footage for compliance purposes.
4. Research Prototyping – Plug in custom deep‑learning models to benchmark inference latency on edge hardware.

Advantages Over Alternatives

• Local Privacy: All data stays on the host; no cloud uploads.
• Hardware Flexibility: Native support for CUDA, Coral, and Jetson reduces the need for external inference services.
• Modular Design: Developers can cherry‑pick or drop components, avoiding monolithic bloat.
• Open Source & Extensible: MIT license and plugin architecture enable rapid feature addition without waiting for upstream releases.

Viseron offers a robust, developer‑friendly platform for building tailored surveillance solutions that can run anywhere from a desktop to an embedded gateway, all while keeping the data under your control.