LightNVR - Lightweight Network Video Recorder

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.

Free to use does not mean free to build. About $10,000 of the maintainer's own money has gone into lightNVR's development and operation over roughly two years. If lightNVR saves you money, supports your customers, or creates value for your business, please help sustain the work through the lightNVR $10K Sustainability Drive or sponsor directly on GitHub.

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; DOODS2 servers are supported through a selectable request format
• ONVIF Motion Events: 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: HLS playback 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: 8 beautiful color themes (Ocean Blue, Forest Green, Royal Purple, Sunset Rose, Golden Amber, Cool Slate, Retro 80s, 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
• Operational Health: Bounded OS/container/filesystem/hardware sampling, durable incidents, Prometheus metrics, and MQTT loss-of-contact presence
• 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).

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.

Database-Backed User Management (v0.21.7)

Users live in the database and are managed from the Users page, not the config file. The first run creates an admin account with the password admin — change it immediately.

💡 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.

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 8 professionally designed color themes and fine-tune the intensity to match your environment and preferences.

Available themes:

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

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.

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

Quick Start

Installation

🏠 Running Home Assistant? Install LightNVR straight from the add-on store — no Docker or command line needed. Add the repository opensensor/lightnvr-hassio-addons under Settings → Add-ons → Add-on Store → ⋮ → Repositories, then install LightNVR. See that repo's README for one-click setup.

1. Build from source:

   Prerequisites (in addition to build-essential, cmake, pkg-config):

   • FFmpeg ≥ 7.1 (libavcodec ≥ 61, libavformat ≥ 61, libavutil ≥ 59, libswscale ≥ 8, libswresample ≥ 5). Debian 12 (bookworm) and Ubuntu 22.04 ship FFmpeg 5.x/6.x, which is too old — build FFmpeg from source or use a newer distro release (Debian 13 / Ubuntu 24.04+ ship a compatible version).
   • Node.js ≥ 24.11 and < 25 for the web build. Use the pinned version in .nvmrc; distribution packages may be older, so install Node 24 via NodeSource or nvm when needed.
   • libsqlite3-dev (not pulled in automatically by any of the above).

   # 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 >= 24.11 and < 25 -- see above).
   # Use this script rather than running: cd web && npm install && npm run build
   # It also runs scripts/extract_version.js first, which generates web/js/version.js
   # from CMakeLists.txt. Skipping that step fails the Vite build with:
   # "Could not resolve '../../version.js'" in Header.jsx.
   ./scripts/build_web_vite.sh
   
   # 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

   See First login — the default credentials are admin / admin and you should change them before anything else.

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
   • Running DOODS2 instead? Set API Request Format to DOODS2 in Settings → Detection and point the URL at its /detect endpoint (see API Detection Settings)
   • Configure Detection Zones to define areas of interest

   See Zone Configuration Guide for detailed zone setup instructions.

First login

⚠️ LightNVR ships with the credentials admin / admin, and the web server listens on 0.0.0.0 by default. Until you change the password, anyone who can reach port 8080 can reach your cameras and recordings. Change it before you expose the port to anything.

Log in at http://your-device-ip:8080 with admin / admin. LightNVR immediately opens a blocking password-change screen; the initial session cannot use the rest of the UI or protected password-authenticated APIs. After replacing the password, sign in again with the new credential. MFA, when enabled, is evaluated on that next sign-in.

You can also pre-set the password before the first start, which avoids the default ever being valid: set password in the [web] section of lightnvr.ini and start LightNVR. The first run creates the admin account with that password instead. The setting is only read when the account is created — after that, users live in the database and are managed from the Users page.

Upgrades do not mark existing accounts for a forced password change. The gate is set only when LightNVR creates a new administrator with the fallback admin password. API-key authentication and demo mode are not restricted by this first-login UI flow.

Forgot the password? There is no reset flag. Stop LightNVR, delete the account row, and restart — it will be recreated from the same rules as a first run:

sudo systemctl stop lightnvr
sqlite3 /var/lib/lightnvr/data/database/lightnvr.db "DELETE FROM users WHERE username = 'admin';"
sudo systemctl start lightnvr

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)

No clone or build required — docker-compose.yml pulls the published image:

# Download the compose file into an empty directory
curl -LO https://raw.githubusercontent.com/opensensor/lightNVR/main/docker-compose.yml

# Pull the image and start the container
docker compose up -d

# View logs
docker compose logs -f

To build the image from source instead, clone the repository, run git submodule update --init --recursive, and switch the image: line in docker-compose.yml to the commented-out build: block.

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. The default credentials are admin / admin — see First login.

Using Docker Run

Images are published to GHCR on every tagged release, for linux/amd64, linux/arm64, and linux/arm/v7:

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 \
  ghcr.io/opensensor/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_ONVIF_NETWORK - Camera network to scan for ONVIF discovery, in CIDR form

See Docker Deployment for the full list.

First Run

On first run, the container will:

1. Create default configuration files in /etc/lightnvr
2. Verify the web assets baked into the image at /var/lib/lightnvr/www
3. Initialize the database in /var/lib/lightnvr/data/database
4. Seed detection models into /var/lib/lightnvr/data/models
5. 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

📖 Full documentation index — grouped by task, with a getting-started path from install to first recording.

Getting Started

• Installation Guide
• Build Instructions
• Configuration Guide
• Docker Deployment
• Home Assistant Add-on
• Windows (Podman + WSL2)
• Reverse Proxy & HTTPS
• Troubleshooting Guide

Features & Integration

• Zone Configuration - Visual polygon-based detection zones
• API Documentation
• go2rtc Integration
• go2rtc Config Override
• MQTT Integration
• Camera Compatibility
• ONVIF Detection
• Multiple Detection Engines
• Motion Buffer System
• SOD Integration

Architecture & Development

• Architecture Overview
• Frontend Architecture
• Release Process
• Product requirement documents
• Internal design notes — historical writeups, not current guidance

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

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