Backup Footage to Local Storage

Overview

This guide shows how to back up video and audio footage from Rhombus cameras to local storage devices such as Network Attached Storage (NAS), external hard drives, or local servers. The solution uses a Python script that uses the Rhombus API to download footage in parallel across multiple cameras.

The implementation supports:

• Multi-camera downloads with threading for improved performance
• Video and audio synchronization with automatic merging
• Flexible scheduling using cron jobs or task schedulers
• Customizable time ranges for historical footage backup
• Location-based filtering to backup specific sites

How it works

1. Camera Discovery

   The script queries the Rhombus API to enumerate all cameras in your organization, filtering by connection status, location, or specific camera UUIDs.

2. Session Authentication

   A federated session token is generated for each camera, providing temporary (1-hour) credentials for media access without exposing your API key in download URLs. Cameras on your LAN accept only federated tokens, by design, so LAN mode always uses one.

3. Media Download

   For each camera, the script:

   1. Requests MPD (MPEG-DASH) playlist URIs for video and audio streams
   2. Downloads the initialization segment (seg_init.mp4)
   3. Downloads sequential 2-second media segments
   4. Writes segments to local storage
4. Audio-Video Merging

   If audio is available, the script uses FFmpeg to merge video and audio streams into a single file, then cleans up temporary files.

Prerequisites

Before implementing local backup, ensure you have:

• Python 3.7 or higher installed on your backup system
• Rhombus API key from the Rhombus Console
• Network connectivity to Rhombus cameras (LAN or WAN)
• Sufficient storage space on your backup device (estimate 1-2 GB per camera per day)
• FFmpeg installed for audio-video merging

Installation

Install required software

# Update package list
sudo apt update

# Install Python 3 and pip
sudo apt install python3 python3-pip

# Install FFmpeg
sudo apt install ffmpeg

# Install Git (to clone the repository)
sudo apt install git

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3
brew install python

# Install FFmpeg
brew install ffmpeg

# Install Git
brew install git

# Install Python from python.org
# Download from: https://www.python.org/downloads/

# Install FFmpeg
# Download from: https://ffmpeg.org/download.html#build-windows
# Add FFmpeg to your PATH environment variable

# Install Git
# Download from: https://git-scm.com/download/win

# Enable SSH in Control Panel > Terminal & SNMP

# Install Python via Package Center
# Search for and install "Python 3"

# Install ffmpeg via SynoCommunity
# Add SynoCommunity package source: https://synocommunity.com/
# Install ffmpeg from Community packages

# Install Git via Package Center

Download the backup script

Clone the Rhombus API examples repository:

# Clone the repository
git clone https://github.com/RhombusSystems/api-examples-python.git

# Navigate to the NAS backup directory
cd api-examples-python/NAS-Backup-v2

# Install Python dependencies
pip3 install -r requirements.txt

Verify installation

Test that all components are installed correctly:

# Check Python version
python3 --version

# Check FFmpeg installation
ffmpeg -version

# Check pip packages
pip3 list | grep -E "(requests|ffmpeg|urllib3|xmltodict)"

Configuration

Command-line parameters

The backup script supports the following parameters:

Usage examples

Basic backup (last hour)

Backup the last hour of footage from all cameras:

python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY

Specific time range

Backup footage from a specific 2-hour window:

python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY \
  --start_time 1693526400 \
  --duration 7200

Single camera backup

Backup footage from one specific camera:

python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY \
  --camera_uuid camera-uuid-here \
  --duration 3600

Location-based backup

Backup all cameras at a specific location:

python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY \
  --location_uuid location-uuid-here \
  --duration 3600

WAN access (remote backup)

Backup from outside your local network:

python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY \
  --usewan \
  --duration 3600

Debug mode

Enable detailed logging for troubleshooting:

python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY \
  --debug \
  --duration 3600

Output files

Downloaded footage files follow this naming convention:

{CameraName}_{CameraUUID}_{Timestamp}_{Type}.{Extension}

Examples:

FrontDoor_abc123def456_1693526400_video.mp4
Lobby_def789ghi012_1693526400_videoWithAudio.mp4
Warehouse_ghi345jkl678_1693526400_video.mp4

File Types:

• Video-only files: .mp4 format (when no audio is available)
• Merged files: .mp4 format (video + audio combined via FFmpeg)
• Temporary files: .webm format (automatically deleted after merging)

Scheduling automated backups

Using cron (Linux/macOS/NAS)

Create automated backups using cron jobs:

1. Edit Crontab

   Open your crontab configuration:

   bash

   crontab -e

2. Add Backup Schedule

   Add one of the following examples based on your needs:

   Hourly BackupDaily Backup (Midnight)Every 4 HoursBusiness Hours Only

   bash

   # Backup every hour at minute 0
   0 * * * * cd /path/to/api-examples-python/NAS-Backup-v2 && /usr/bin/python3 copy_footage_script_threading.py --api_key YOUR_API_KEY --duration 3600 >> /var/log/rhombus_backup.log 2>&1

3. Save and Verify

   Save the crontab and verify it's scheduled:

   bash

   # List current cron jobs
   crontab -l
   
   # Check cron service status
   sudo systemctl status cron

Using Task Scheduler (Windows)

1. Open Task Scheduler

   Press Win + R, type taskschd.msc, and press Enter.

2. Create New Task
   1. Click "Create Task" in the right panel
   2. Name it "Rhombus Footage Backup"
   3. Select "Run whether user is logged on or not"
3. Set Trigger
   1. Go to the Triggers tab
   2. Click New
   3. Choose frequency (Daily, Weekly, etc.)
   4. Set start time and recurrence
4. Configure Action
   1. Go to the Actions tab
   2. Click New
   3. Action: Start a program
   4. Program: C:\Python39\python.exe (adjust path)
   5. Arguments: copy_footage_script_threading.py --api_key YOUR_API_KEY --duration 3600
   6. Start in: C:\path\to\NAS-Backup-v2
5. Save and Test
   1. Click OK to save
   2. Right-click the task and select "Run" to test

API endpoints used

The backup script interacts with the following Rhombus API endpoints:

Camera enumeration

POST https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList

Retrieves list of cameras with connection status and location information.

Audio gateway list

POST https://api2.rhombussystems.com/api/audiogateway/getMinimalAudioGatewayStateList

Fetches audio devices associated with cameras.

Session token generation

POST https://api2.rhombussystems.com/api/org/generateFederatedSessionToken

Creates a federated token for media access. The script asks for one hour; the response's expiresAtMs says when the token expires, and no federated token lasts more than 24 hours.

Video media URIs

POST https://api2.rhombussystems.com/api/camera/getMediaUris

Obtains MPD (MPEG-DASH) playlist templates for video streams.

Audio media URIs

POST https://api2.rhombussystems.com/api/audiogateway/getMediaUris

Obtains MPD templates for audio streams.

Performance optimization

Threading configuration

The script uses Python's ThreadPoolExecutor with a maximum of 4 concurrent workers. This balances download speed with API rate limits and system resources.

To adjust thread count, modify the script:

# In copy_footage_script_threading.py
with ThreadPoolExecutor(max_workers=4) as executor:  # Change 4 to desired value

Recommendations:

• 2-4 workers: Standard NAS or low-end systems
• 4-8 workers: High-performance NAS or servers
• 8-16 workers: Enterprise servers with high bandwidth

Storage considerations

Calculate Required Space:

Storage (GB) = Cameras × Days × 1.5 GB/day

Example:

• 10 cameras × 30 days × 1.5 GB = 450 GB required

Best Practices:

• Maintain at least 20% free space on backup device
• Implement retention policies to delete old footage
• Monitor disk usage regularly
• Use compression if long-term archival is needed

Network optimization

LAN vs WAN:

• LAN Mode (default): Faster downloads, uses local network addresses
• WAN Mode (--usewan): Required for remote backup, slower but accessible from anywhere

Bandwidth Requirements:

• Approximately 2-4 Mbps per concurrent camera download
• 4 workers = 8-16 Mbps recommended bandwidth

Retention and cleanup

Implement a retention policy to manage storage usage:

# Create cleanup script
cat > cleanup_old_footage.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/path/to/backup/directory"
RETENTION_DAYS=30

find "$BACKUP_DIR" -name "*.mp4" -type f -mtime +$RETENTION_DAYS -delete
find "$BACKUP_DIR" -name "*.webm" -type f -mtime +$RETENTION_DAYS -delete

echo "Deleted footage older than $RETENTION_DAYS days"
EOF

chmod +x cleanup_old_footage.sh

# Add to crontab (runs every Sunday at 3 AM)
0 3 * * 0 /path/to/cleanup_old_footage.sh >> /var/log/rhombus_cleanup.log 2>&1

import os
import time
from pathlib import Path

def cleanup_old_files(backup_dir, retention_days):
    """Remove footage files older than retention period"""
    cutoff_time = time.time() - (retention_days * 86400)
    removed_count = 0
    freed_space = 0

    for file in Path(backup_dir).glob("**/*.mp4"):
        if file.stat().st_mtime < cutoff_time:
            size = file.stat().st_size
            file.unlink()
            removed_count += 1
            freed_space += size

    print(f"Removed {removed_count} files")
    print(f"Freed {freed_space / (1024**3):.2f} GB")

# Usage
cleanup_old_files("/path/to/backup", retention_days=30)

Troubleshooting

# Test API authentication
curl -X POST https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY"

# Test with fewer threads and debug mode
python3 copy_footage_script_threading.py \
  --api_key YOUR_API_KEY \
  --debug \
  --duration 600  # Start with 10 minutes

# Check FFmpeg installation
which ffmpeg
ffmpeg -version

# Manual merge test
ffmpeg -i video.webm -i audio.webm -c copy output.mp4

# List all cameras via API
curl -X POST https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  | python3 -m json.tool

# Check disk usage
df -h /path/to/backup

# Find largest files
du -sh /path/to/backup/* | sort -hr | head -10

# Test cron job manually
cd /path/to/NAS-Backup-v2
/usr/bin/python3 copy_footage_script_threading.py --api_key YOUR_API_KEY

# Check cron logs
tail -f /var/log/syslog | grep CRON

Best practices

Security considerations

API key protection

1. Store securely: Use environment variables or credential managers
2. Restrict access: Limit file permissions on scripts containing keys
3. Rotate regularly: Change API keys periodically
4. Audit usage: Monitor API key activity in Rhombus Console

# Store API key in environment variable
export RHOMBUS_API_KEY="your-api-key-here"

# Use in script
python3 copy_footage_script_threading.py --api_key "$RHOMBUS_API_KEY"

# Restrict script permissions
chmod 600 backup_script.sh

Network security

• Use LAN mode when possible to avoid WAN exposure
• Implement firewall rules to restrict access
• Consider VPN for remote backup scenarios
• Enable mTLS authentication for enhanced security

Storage security

• Encrypt backup storage devices
• Restrict file system permissions
• Implement access controls on NAS/server
• Regularly audit who has access to backup files

Compliance considerations

When implementing local backup, consider:

Data Retention:

• Follow your organization's data retention policies
• Comply with industry regulations (HIPAA, GDPR, etc.)
• Document retention periods and deletion procedures

Access Control:

• Maintain audit logs of who accesses backup footage
• Implement role-based access controls
• Document authorized personnel

Data Protection:

• Encrypt data at rest and in transit
• Implement secure deletion procedures
• Regular security assessments

Advanced configuration

Custom output directory

Modify the script to save files to a specific directory:

# In copy_footage_script_threading.py
OUTPUT_DIR = "/mnt/nas/rhombus_backups"

# Create directory structure by date
import datetime
date_dir = datetime.datetime.now().strftime("%Y-%m-%d")
output_path = os.path.join(OUTPUT_DIR, date_dir)
os.makedirs(output_path, exist_ok=True)

Email notifications

Add email alerts for backup completion or failures:

import os
import smtplib
from email.mime.text import MIMEText

def send_notification(status, message):
    msg = MIMEText(message)
    msg['Subject'] = f'Rhombus Backup {status}'
    msg['From'] = 'backup@yourcompany.com'
    msg['To'] = 'admin@yourcompany.com'

    with smtplib.SMTP('smtp.gmail.com', 587) as server:
        server.starttls()
        server.login(os.environ['SMTP_EMAIL'], os.environ['SMTP_PASSWORD'])
        server.send_message(msg)

# Use after backup completes
try:
    # ... backup code ...
    send_notification("Success", "All cameras backed up successfully")
except Exception as e:
    send_notification("Failed", f"Backup failed: {str(e)}")

Webhook integration

Trigger webhooks after backup completion:

import datetime
import requests

def trigger_webhook(status, cameras_backed_up):
    webhook_url = "https://your-webhook-endpoint.com/backup"
    payload = {
        "status": status,
        "timestamp": datetime.datetime.now().isoformat(),
        "cameras": cameras_backed_up
    }
    requests.post(webhook_url, json=payload)

Next steps

Additional resources

• Rhombus API Documentation: Complete API reference for all endpoints
• Python Requests Documentation: docs.python-requests.org
• FFmpeg Documentation: ffmpeg.org/documentation
• Cron Documentation: man7.org/linux/man-pages/man5/crontab.5.html