Skip to content

Quick Start

Jump to bottom
mileshilliard edited this page Feb 20, 2026 · 2 revisions

Quick Start

Get OptiVue running in under 10 minutes.

Prerequisites

Before you begin, make sure you have the following:

Python 3.9+

python3 --version

OpenCV system packages -- required before installing Python dependencies:

# Debian / Ubuntu / Raspberry Pi OS
sudo apt update
sudo apt install python3-opencv libopencv-dev -y

If you are using an RPi, I recommend reading this: Learn to install quickly on RPi

A USB camera connected and recognised by your system. To verify:

ls /dev/video*
# Should show at least /dev/video0

If you have multiple USB cameras connected, each will appear as /dev/video0, /dev/video1, etc. Note the indices -- you will need them in your config.

Install

Clone the repository and install Python dependencies:

git clone https://github.com/syntaxerror019/optivue.git
cd optivue
pip install -r requirements.txt

Configure

Create a .env file in the root directory (same directory as main.py)
Put the following contents into the .env file, replacing the USERNAME and PASSWORD
These will be the credentials asked for upon opening some pages on the web interface.

USERNAME=your_username
PASSWORD=your_secure_password

Copy the example config and open it for editing:

cp config.example.yaml config.yaml
nano config.yaml

Here is the full config with all available options:

camera:
  compression: mjpeg        # Video compression format
fps: 30                     # Frames per second for the camera feed
width: 640                  # Capture resolution width
height: 480                 # Capture resolution height
motion_contour_area: 500    # Minimum contour area to trigger motion detection (pixels)
motion_detection: true      # Enable or disable motion detection

cameras:
  - 0                       # Camera index -- add more indices for additional cameras
                            # e.g. - 0
                            #      - 1

record:
  enabled: true             # Enable or disable recording
  recording_length: 60       # Length of each clip in minutes

storage_path: /home/user/optivue   # Where clips and snapshots are saved
video_retention: 30                # How long to keep recordings in days

server:
  host: 0.0.0.0             # 0.0.0.0 = accessible on your network
                            # Change to 127.0.0.1 for local-only access
  port: 5000

The key things to set for a first run are covered below. Full documentation of every option is in the Configuration wiki page.

Cameras

OptiVue uses camera indices -- the number OpenCV assigns to each connected device. 0 is almost always your first USB camera. If you have more than one, add additional indices to the list:

cameras:
  - 0
  - 1

To find which index corresponds to which camera on Linux:

ls /dev/video*

Storage

Set storage_path to an absolute path where you want clips saved. The directory will be created if it does not exist. Set video_retention to automatically delete recordings older than that many days:

storage_path: /home/pi/optivue
video_retention: 30

Recording

record:
  enabled: true
  recording_length: 60    # each clip will be 1 minute long

Motion Detection

Motion detection is enabled by default. If you want continuous recording without it, set motion_detection: false. Adjust motion_contour_area to tune sensitivity -- lower values trigger on smaller movements:

motion_detection: true
motion_contour_area: 500

Resolution and FPS

Lower these if OptiVue is struggling on older hardware:

fps: 30
width: 640
height: 480

On a Raspberry Pi 3B+, 640x480 at 15fps is a comfortable starting point.

Server

server:
  host: 0.0.0.0    # accessible from other devices on your network
  port: 5000

Run

python main.py

Then open your browser and go to:

http://localhost:5000

Accessing from another device on the same network? Replace localhost with the IP address of the machine running OptiVue:

http://192.168.1.x:5000

Running as a Background Service

To keep OptiVue running after you close the terminal, set it up as a systemd service.

Create the service file:

sudo nano /etc/systemd/system/optivue.service

Paste the following, updating the paths to match your setup:

[Unit]
Description=OptiVue Camera System
After=network.target

[Service]
WorkingDirectory=/home/pi/optivue
ExecStart=/usr/bin/python3 main.py
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable optivue
sudo systemctl start optivue

Check it is running:

sudo systemctl status optivue

Next Steps

Clone this wiki locally