upvs

UniFi Protect Video Summary - Create ~10-minute timelapses from a day’s recordings.

Quick Start

# Build
go build ./cmd/upvs

# Set credentials (or use flags)
export UPVS_HOST=https://192.168.1.1
export UPVS_USERNAME=your-username
export UPVS_PASSWORD=your-password

# Run full pipeline for a single day
./upvs run --camera "Front Door" --date 2024-01-15 --out ./output

# Or run phases separately
./upvs scan   --camera "Front Door" --date 2024-01-15 --out ./output
./upvs fetch  --camera "Front Door" --date 2024-01-15 --out ./output --workers 4
./upvs render --camera "Front Door" --date 2024-01-15 --out ./output

Authentication

The tool authenticates using a local UniFi OS account (username/password). Create a dedicated account in UniFi OS for API access.

Pass credentials via:

• --username and --password flags
• --password-file flag (path to file containing password)
• UPVS_USERNAME and UPVS_PASSWORD environment variables

Note: Prefer --password-file or environment variables over --password flag to avoid exposing credentials in process lists.

Output

output/
├── timelapse/Front_Door_2024-01-15_timelapse.mp4  # Final video
├── clips/Front_Door/2024-01-15/*.mp4              # Downloaded clips
├── manifests/clip_index.json                       # Event tracking
└── metadata/day.json                               # Speed calculation

Options

Global Flags:
  --host             UniFi Protect URL (env: UPVS_HOST)
  --username         Username (env: UPVS_USERNAME)
  --password         Password (env: UPVS_PASSWORD)
  --password-file    Path to file containing password
  --camera           Camera ID or name
  --out              Output directory
  --tls-insecure     Skip TLS verification (for self-signed certs)
  --direct-api       Use /api path (direct NVR connection, not UniFi OS)
  --verbose          Enable debug logging

Requirements

• Go 1.23+
• FFmpeg (in PATH)
• UniFi Protect with local account access