LightNVR is a tiny, memory-optimized Network Video Recorder software written in C. While originally designed for resource-constrained devices like the Ingenic A1 SoC with only 256MB of RAM, it can run on any Linux system.

Overview

LightNVR provides a lightweight yet powerful solution for recording and managing IP camera streams. It's designed to run efficiently on low-power, memory-constrained devices while still providing essential NVR functionality with a modern, responsive web interface.

✨ New Features: Detection zones with visual polygon editor, customizable themes, enhanced light-object-detect integration, and ultra-low-latency WebRTC streaming!

Key Features

🎯 Smart Detection & Recording

• Detection Zones: Visual polygon-based zone editor for targeted object detection - define multiple zones per camera with custom class filters and confidence thresholds
• light-object-detect Integration: Seamless integration with light-object-detect API for ONNX/TFLite-based object detection with zone filtering
• ONVIF Motion Recording: Automated recording triggered by ONVIF motion detection events
• Object Detection: Optional SOD integration for motion and object detection (supports both RealNet and CNN models)

📺 Streaming & Playback

• WebRTC Streaming: Ultra-low latency live viewing with automatic NAT/firewall traversal via STUN/ICE
• HLS Streaming: Adaptive bitrate streaming for broad device compatibility
• Dual Streaming Modes: Toggle between WebRTC (low latency) and HLS (compatibility) on-the-fly
• Detection Overlays: Real-time bounding boxes and labels on live streams

🎨 Modern User Interface

• Customizable Themes: 7 beautiful color themes (Ocean Blue, Forest Green, Royal Purple, Sunset Rose, Golden Amber, Cool Slate, Default)
• Dark/Light Mode: Automatic system preference detection with manual override
• Color Intensity Control: Fine-tune theme brightness and contrast to your preference
• Responsive Design: Built with Tailwind CSS and Preact for smooth, modern UX

🔧 Core Capabilities

• Cross-Platform: Runs on any Linux system, from embedded devices to full servers
• Memory Efficient: Optimized to run on devices with low memory (SBCs and certain SoCs)
• Stream Support: Handle multiple video streams (with memory-optimized buffering)
• Protocol Support: RTSP and ONVIF (basic profile)
• Codec Support: H.264 (primary), H.265 (if resources permit)
• Resolution Support: Configurable resolution per stream
• Frame Rate Control: Configurable from 1-15 FPS per stream to reduce resource usage
• Standard Formats: Records in standard MP4/MKV containers with proper indexing
• Storage Management: Automatic retention policies and disk space management
• Reliability: Automatic recovery after power loss or system failure
• Resource Optimization: Stream prioritization to manage limited RAM

🧱 Architecture Overview

LightNVR is built as a small, C-based core service with a modern Preact/Tailwind web UI and go2rtc as the streaming backbone. Object detection is handled by an external detection API (typically light-object-detect).

High-level architecture: web UI, API, core, go2rtc, and detection service

At a high level:

• Web UI & API layer – Preact single-page UI served by the embedded HTTP server, plus JSON REST endpoints for streams, recordings, detection, and settings.
• Core service – Stream manager, recorder, retention logic, configuration store, and event system implemented in C for low memory use.
• Streaming layer (go2rtc) – Handles RTSP ingest and provides WebRTC/HLS endpoints. LightNVR configures go2rtc and talks to it directly for /api/webrtc and snapshot (/api/frame.jpeg) calls.
• Detection service – External HTTP API (e.g. light-object-detect) that receives frames from go2rtc and returns object detections which LightNVR stores and overlays.
• Storage & system resources – MP4/HLS writers, file system, DB, and lightweight threading model tuned for small devices.

For more detail, the repository also includes:

• docs/images/arch-state.svg – high-level state machine for streams/recordings
• docs/images/arch-thread.svg – thread and worker layout for the core service

🆕 Recent Highlights

libuv HTTP Backend (v0.20.0)

Migrated from Mongoose to libuv + llhttp for the HTTP server, improving performance and reliability.

TOTP Two-Factor Authentication (v0.20.0)

Optional TOTP-based MFA for securing the web interface with authenticator apps.

MQTT Event Streaming (v0.19.0)

Publish detection events to an MQTT broker for integration with Home Assistant and other automation platforms.

Demo Mode (v0.21.0)

Built-in demo mode with virtual test streams for development and evaluation without real cameras.

Auto-Generated Credentials (v0.21.7)

Admin password is now auto-generated on first run for improved out-of-box security.

💡 Use Cases

LightNVR is perfect for:

• 🏠 Home Security: Monitor your property with smart detection zones - get alerts only for activity in specific areas
• 🏢 Small Business: Cost-effective surveillance with professional features like zone-based detection and retention policies
• 🔬 IoT & Edge Computing: Run on resource-constrained devices (Raspberry Pi, SBCs) with minimal memory footprint
• 🎓 Education & Research: Learn about video processing, object detection, and real-time streaming with clean, well-documented code
• 🛠️ DIY Projects: Build custom surveillance solutions with flexible API integration and modern web interface
• 📦 Warehouse & Logistics: Monitor specific zones (loading docks, storage areas) with class-specific detection (person, forklift, etc.)

🆚 Why LightNVR?

System Requirements

• Processor: Any Linux-compatible processor (ARM, x86, MIPS, etc.)
• Memory: 256MB RAM minimum (more recommended for multiple streams)
• Storage: Any storage device accessible by the OS
• Network: Ethernet or WiFi connection
• OS: Linux with kernel 4.4 or newer

🌟 Feature Highlights

Detection Zones - Precision Object Detection

Define custom detection zones with a visual polygon editor. Perfect for monitoring specific areas like doorways, parking spots, or restricted zones while ignoring irrelevant motion.

Interactive zone editor with driveway detection zone drawn

Detection Zones section in stream configuration

Key capabilities:

• Draw unlimited polygons per camera stream
• Per-zone class filtering (e.g., only detect "person" in Zone A, "car" in Zone B)
• Adjustable confidence thresholds per zone
• Color-coded zones for easy identification
• Enable/disable zones without deleting configuration

Theme Customization - Your Style, Your Way

Choose from 7 professionally designed color themes and fine-tune the intensity to match your environment and preferences.

Theme selector in light mode	Theme selector in dark mode

Ocean Blue	Forest/Emerald Green	Royal Purple	Sunset Rose

Available themes:

• 🎨 Default (Neutral Gray)
• 🌊 Ocean Blue
• 🌲 Forest Green
• 👑 Royal Purple
• 🌹 Sunset Rose
• ⚡ Golden Amber
• 🗿 Cool Slate

Each theme supports both light and dark modes with adjustable color intensity (0-100%).

WebRTC Live Streaming - Ultra-Low Latency

Experience real-time camera feeds with sub-second latency using WebRTC technology. Automatic NAT traversal ensures it works even behind firewalls.

WebRTC live view with ultra-low latency	HLS-based live view for compatibility

Real-time detection overlays with bounding boxes

Features:

• Sub-second latency for real-time monitoring
• Automatic STUN/ICE configuration for NAT traversal
• Seamless fallback to HLS for compatibility
• Real-time detection overlay with bounding boxes
• Grid layout supporting multiple simultaneous streams

light-object-detect Integration

Powerful object detection using modern ONNX and TFLite models with zone-aware filtering.

Integration features:

• Per-stream API endpoint configuration
• Configurable detection backends (ONNX, TFLite, OpenCV)
• Zone-based filtering to reduce false positives
• Track ID and zone ID support for advanced analytics
• Direct go2rtc frame extraction (no FFmpeg overhead)

Screenshots

Stream Management	Recording Management

Recording Playback with video player modal

Settings Management	System Information

Quick Start

Installation

1. Build from source:

   # Clone the repository
   git clone https://github.com/opensensor/lightnvr.git
   cd lightnvr
   
   # Initialize submodules (required for go2rtc)
   git submodule update --init --recursive
   
   # Build web assets (requires Node.js/npm)
   cd web
   npm install
   npm run build
   cd ..
   
   # Build the software
   ./scripts/build.sh --release
   
   # Install (requires root)
   sudo ./scripts/install.sh

2. Configure:

   # Edit the configuration file
   sudo nano /etc/lightnvr/lightnvr.ini

3. Start the service:

   sudo systemctl start lightnvr
   sudo systemctl enable lightnvr

4. Access the web interface: Open a web browser and navigate to http://your-device-ip:8080

   Default username: admin (password is auto-generated on first run — check the service logs with journalctl -u lightnvr)

5. (Optional) Set up object detection:

   For advanced object detection with zone filtering, integrate with light-object-detect:

   # Install light-object-detect (requires Python 3.8+)
   pip install light-object-detect
   
   # Start the detection API server (default port 9001)
   light-object-detect --host 0.0.0.0 --port 9001

   Then configure detection in LightNVR:

   • Navigate to Streams → Select a stream → Configure
   • Enable Detection Based Recording
   • Set API Detection URL to http://localhost:9001/api/v1/detect
   • Choose detection backend: onnx (recommended), tflite, or opencv
   • Configure Detection Zones to define areas of interest

   See Zone Configuration Guide for detailed zone setup instructions.

Troubleshooting

Blank Web Page

If you see a blank page after installation:

For Docker users:

# Check if you mounted /var/lib/lightnvr directly (this overwrites web assets)
docker inspect lightnvr | grep -A 5 Mounts

# Fix: Update docker-compose.yml to mount /var/lib/lightnvr/data instead
# Then recreate the container:
docker compose down
docker compose up -d

For native installation:

# Install/reinstall web assets (requires source directory)
sudo ./scripts/install_web_assets.sh

# Restart service
sudo systemctl restart lightnvr

See Web Interface Troubleshooting Guide for detailed instructions.

WebRTC Streams Not Connecting

If live streams fail with ICE connection errors, set your machine's local IP as external_ip in lightnvr.ini:

[go2rtc]
external_ip = 192.168.1.100  ; Replace with your machine's local IP

To find your local IP:

# Linux
hostname -I | awk '{print $1}'

# macOS
ipconfig getifaddr en0    # or en1 for Wi-Fi

Then restart LightNVR (or docker compose restart for Docker). See the Docker Deployment Guide for more WebRTC troubleshooting.

General Troubleshooting

For other issues, see the General Troubleshooting Guide.

Docker Installation

Quick Start with Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/opensensor/lightNVR.git
cd lightNVR

# Initialize submodules (required for go2rtc build)
git submodule update --init --recursive

# Start the container (first run will build the image)
docker compose up -d

# View logs
docker compose logs -f

The container will automatically:

• Create default configuration files in ./config
• Initialize the database in ./data/database
• Set up web assets with working defaults
• Configure go2rtc with WebRTC/STUN support

Access the web UI at http://localhost:8080 (default username: admin, password is auto-generated on first run — check logs)

Using Docker Run

Images are published to both Docker Hub and GHCR on every tagged release:

# Docker Hub (recommended)
docker pull matteius/lightnvr:latest

# GitHub Container Registry
docker pull ghcr.io/opensensor/lightnvr:latest

docker run -d \
  --name lightnvr \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 8554:8554 \
  -p 8555:8555 \
  -p 8555:8555/udp \
  -p 1984:1984 \
  -v ./config:/etc/lightnvr \
  -v ./data:/var/lib/lightnvr/data \
  -e TZ=America/New_York \
  matteius/lightnvr:latest

Volume Mounts Explained

The container uses two volume mounts for persistence:

• /etc/lightnvr - Configuration files

  • lightnvr.ini - Main configuration
  • go2rtc/go2rtc.yaml - go2rtc WebRTC/RTSP configuration

• /var/lib/lightnvr/data - Persistent data

  • database/ - SQLite database
  • recordings/ - Video recordings (HLS and MP4)
  • models/ - Object detection models

⚠️ Important: Do NOT mount /var/lib/lightnvr directly as it will overwrite web assets!

Exposed Ports

• 8080 - Web UI (HTTP)
• 8554 - RTSP streaming
• 8555 - WebRTC (TCP/UDP)
• 1984 - go2rtc API

Environment Variables

• TZ - Timezone (default: UTC)
• GO2RTC_CONFIG_PERSIST - Persist go2rtc config across restarts (default: true)
• LIGHTNVR_AUTO_INIT - Auto-initialize config files (default: true)

First Run

On first run, the container will:

1. Create default configuration files in /etc/lightnvr
2. Copy web assets to /var/lib/lightnvr/web
3. Initialize the database in /var/lib/lightnvr/data/database
4. Set up go2rtc with WebRTC/STUN configuration

The go2rtc configuration includes STUN servers for WebRTC NAT traversal, so WebRTC streaming should work out-of-the-box in most network environments.

Customizing Configuration

After first run, you can customize the configuration:

# Edit main configuration
nano ./config/lightnvr.ini

# Edit go2rtc configuration (WebRTC, RTSP settings)
nano ./config/go2rtc/go2rtc.yaml

# Restart to apply changes
docker compose restart

The configuration files will persist across container restarts and updates.

Documentation

Getting Started

• Installation Guide
• Build Instructions
• Configuration Guide
• Docker Deployment
• Troubleshooting Guide

Features & Integration

• Zone Configuration - Visual polygon-based detection zones
• API Documentation
• go2rtc Integration
• MQTT Integration
• ONVIF Detection
• ONVIF Motion Recording
• Motion Buffer System
• SOD Integration

Architecture & Development

• Architecture Overview
• Frontend Architecture
• State Management
• Release Process

Project Structure

• src/ - C source code
  • core/ - Core system components
  • video/ - Video processing and stream handling
  • storage/ - Storage management
  • web/ - HTTP server and API handlers
  • database/ - Database operations and migrations
  • utils/ - Utility functions
• include/ - Header files
• web/ - Web frontend (Vite + Preact + Tailwind CSS)
  • js/ - Preact components and pages
  • css/ - Tailwind CSS stylesheets
  • *.html - HTML entry points
• db/migrations/ - SQLite schema migrations
• scripts/ - Build, install, and utility scripts
• config/ - Configuration templates
• docs/ - Documentation
• tests/ - Integration and Playwright tests

Memory Optimization

LightNVR is specifically designed for memory-constrained environments:

• Efficient Buffering: Minimizes memory usage while maintaining reliable recording
• Stream Prioritization: Allocates resources based on stream importance
• Staggered Initialization: Prevents memory spikes during startup
• Swap Support: Optional swap file configuration for additional virtual memory
• Resource Governors: Prevents system crashes due to memory exhaustion

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Note: By contributing to this project, you agree to sign our Contributor License Agreement (CLA). The CLA bot will guide you through the process on your first pull request.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Commercial Licensing

For organizations that need to integrate lightNVR into proprietary products or cannot comply with GPL requirements, commercial licenses are available from OpenSensor Engineering. See Commercial Licensing & Professional Support for details.

Star History

Star History

Acknowledgments

LightNVR is built on the shoulders of giants. Special thanks to:

Core Technologies

• FFmpeg - Video processing and codec support
• go2rtc - WebRTC and RTSP streaming engine
• SQLite - Efficient embedded database
• libuv - Cross-platform async I/O library
• llhttp - HTTP parser
• cJSON - Lightweight JSON parser

Frontend Stack

• Tailwind CSS - Modern utility-first CSS framework
• Preact - Fast 3kB alternative to React
• HLS.js - JavaScript HLS client

Detection & AI

• light-object-detect - ONNX/TFLite object detection API
• SOD - Embedded computer vision library

Community

• All contributors who have helped improve LightNVR
• The open-source community for inspiration and support