<p align="center"> <img src="docs/logo.png" alt="VibeNVR Logo" width="120"> </p>

📹 VibeNVR – Modern Video Surveillance System

VibeNVR is a modern, modular, and containerized video surveillance system designed to manage IP cameras, recordings, motion detection, and a unified event timeline. It features a custom high-performance video engine (VibeEngine) built for efficiency and reliability, wrapped in a premium React-based interface.

🎬 Video Demo

Project Status: This is a Vibe Coding Project. Extensive testing has been performed to ensure stability, but we are always open to new help and contributions from the community!

⚠️ IMPORTANT: When updating, always check the Release Notes and ensure your docker-compose.prod.yml and .env are synchronized with the latest version.

Language Policy: Please note that English is the official and only supported language of this project. All code, user interface elements, commit messages, issues, and documentation (including wikis) must be written strictly in English to maintain consistency and accessibility for the global community.

---

💬 Help Us Improve!

We are building VibeNVR to be the best local NVR experience, and we can't do it without you.

Found a bug? Have a great idea for a feature? Want to share your setup? Please Open an Issue! We are extremely proactive, always available to fix problems, and love adding new capabilities requested by the community. Your feedback is what drives this project forward.

✨ Key Features

| Feature | Description | |---------|-------------| | 🖥️ Modern Web Interface | Ultra-premium UI built with React, Vite, and Lucide icons. | | 🎨 Customizable Dashboard | Toggle widgets and graphs to suit your monitoring needs. | | 🛡️ Secure by Design | Full JWT authentication, 2FA with Trusted Devices, Rate Limiting, and HttpOnly Media Cookies. | | 📷 Advanced Video Engine | Custom Python engine using PyAV & FFmpeg for RTSP streaming, with OpenCV for motion detection and image processing. | | ⚡ Passthrough Recording | Direct Stream Copy support for near-zero CPU usage recording (experimental, with auto-fallback). | | 🎯 Smart Motion Detection | Native motion detection with adjustable sensitivity, gap, and pre/post-capture buffers. | | 📅 Event Timeline | Unified browser for movie recordings and high-res snapshots with instant filters. | | 🛡️ Privacy Masking | Permanent black-out zones burned into recordings. Motion Zones for exclusion masking. | | 🔑 API Access Tokens | Secure, read-only API tokens with TTL (Expiration) and hashed storage for 3rd party integrations. | | 💾 Storage Management | Automated background cleanup (FIFO), Multiple Storage Profiles, and Bulk Deletion tools. | | 📁 Camera Groups | Organize cameras into custom groups for logical multi-view management. | | 💾 System Backups | Automated & Manual configuration snapshots with server-side management and restoration. | | 🕙 Timezone Synchronization | Full ISO 8601 support ensures perfect timing between engine, backend, and UI. | | 📊 Real-time Monitoring | Native WebCodecs H.264 low-latency WebSocket streaming, with selectable modes and adaptive JPEG polling fallback. | | 🛡️ IP Ban Protection | Automated ffprobe pre-flight checks and per-camera RTSP Transport selection (TCP/UDP) to ensure maximum compatibility. | | 🐳 Docker-Native | Zero-dependency deployment with Tag-Driven CI/CD for stable, predictable releases. |

---

🔒 Security & Architecture

VibeNVR is built with security as a priority. For detailed information regarding our security model, authenticated media, internal port protection, vulnerability reporting, and Role-Based Access Control (RBAC), please see our dedicated Security Documentation.

---

📊 Public Telemetry

VibeNVR maintains a public, anonymous telemetry dashboard where you can see global usage statistics, active versions, and hardware trends: View Public Telemetry Dashboard

What is collected?

We only collect non-sensitive, anonymous technical data:

• Application Version: To see how many users are on the latest release.
• Hardware Profile: CPU count, total RAM (rounded to GB), and GPU acceleration status.
• Usage Metrics: Total number of cameras, camera groups, and events in the database.
• System Info: Operating System and hardware architecture (e.g., Linux x86_64).
• Anonymous ID: A randomly generated UUID that uniquely identifies the installation without linking it to any personal identity or IP address.
• Feature Flags: A simple indicator if notifications are configured (no addresses or tokens).

How often?

The report is sent once 30 seconds after startup and then once every 24 hours.

Opt-out

Your privacy is paramount. You can disable telemetry at any time:

1. Navigate to Settings in the web interface.
2. Open the Privacy & Analytics section.
3. Toggle off Enable Anonymous Telemetry and save.

---

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (V2 recommended)

📦 Installation via Docker (Recommended)

1. Get the files: Download the docker-compose.prod.yml file.

   Alternatively, clone the repository to get all files (recommended for easier updates):

   git clone https://github.com/spupuz/VibeNVR.git
   cd VibeNVR
   

2. Configuration (.env): VibeNVR is configured using a .env file.

   • If you cloned the repo, you can use the included .env file as a base.
   • If you just downloaded the compose file, create a file named .env in the same directory.

   Important: Update your .env with secure values:

   # .env content example
   # ENV Configuration
   SECRET_KEY=change_this_to_a_long_random_string  # CRITICAL: Security key (min 32 chars). Application won't start in production with a weak key unless ALLOW_WEAK_SECRET=true is set.
   WEBHOOK_SECRET=change_this_to_a_long_random_string # REQUIRED: Validates engine->backend communication. Set SAME as SECRET_KEY.
   # POSTGRES_PASSWORD=vibenvrpass
   
   # Storage & Paths
   # VIBENVR_DATA=./viben_data             # Where recordings and logs are stored
   # VIBENVR_DB_DATA=./viben_db_data       # Database persistence path
   
   # Ports
   # VIBENVR_FRONTEND_PORT=8080            # Frontend Access Port
   # VIBENVR_BACKEND_PORT=5005             # Backend API Port
   
   # Hardware Acceleration
   # HW_ACCEL=true                         # Enable Hardware Acceleration (true/false)
   # HW_ACCEL_TYPE=auto                    # auto, nvidia, intel, amd
   

   See the .env file in the repo for all available options.

3. Start the service:

   docker compose -f docker-compose.prod.yml up -d
   

🔄 Updating VibeNVR

When a new version is released, follow these steps to ensure a clean update:

1. Back up your .env file:

   cp .env .env.bak
   

2. Retrieve the new production compose file: Ensure you are in the project root.

   curl -O https://raw.githubusercontent.com/spupuz/VibeNVR/main/docker-compose.prod.yml
   

3. Pull the new images:

   docker compose -f docker-compose.prod.yml pull
   

4. Stop the current stack:

   docker compose -f docker-compose.prod.yml down
   

5. Start the new stack:

   docker compose -f docker-compose.prod.yml up -d
   

---

💾 Data Persistence (Bind Mounts vs Volumes)

The default configuration above uses Bind Mounts (mappings to local folders like ./data/recordings) which makes it easy to access your video files directly from the host system.

Option A: Using Local Folders (Bind Mounts - Recommended) This allows you to easily backup or view recordings using tools on your host machine.

• Recordings: ./data/recordings
• Database: ./data/db

Option B: Using Docker Volumes If you prefer to let Docker manage storage (better for performance on some non-Linux filesystems), change the volumes section in docker-compose.yml:

volumes:
  - vibenvr_data:/data

And define the volume at the end of the file:

volumes:
  vibenvr_data:

---

---

🏠 Dashboard Integration (Homepage)

VibeNVR integrates perfectly with gethomepage.dev using the customapi widget.

Example services.yaml configuration:

- VibeNVR:
    icon: mdi-cctv
    href: http://your-vibenvr-ip:8080/
    description: Video Surveillance
    server: your-docker-host # Optional: Requires docker socket access in Homepage
    container: vibenvr-backend
    widget:
      type: customapi
      url: http://your-vibenvr-ip:8080/api/v1/homepage/stats
      headers:
        X-API-Key: "your-api-token-here"
      method: GET
      mappings:
        - field: cameras_online
          label: Online
        - field: events_today
          label: Events (24h)
        - field: storage_used_gb
          label: Storage (GB)
        - field: uptime
          label: Uptime
        - field: cameras_recording
          label: Recording
        - field: storage_total_gb
          label: Total Disk (GB)

---

🌐 Production Deployment (Nginx Proxy Manager)

Since VibeNVR binds to 127.0.0.1 by default, you MUST use a Reverse Proxy to access it from other computers or the internet.

**Recommended Setup with N