Camsnap

Camsnap Skill

Production-grade IP camera capture system for RTSP/ONVIF cameras with comprehensive error handling and multi-brand support.

When to Use

✅ USE this skill when:

• Capturing snapshots from IP security cameras
• Recording security camera footage
• Testing RTSP stream connectivity
• Needing automated camera monitoring
• Recording clips from security cameras
• Multi-camera snapshot capture
• Long-term camera monitoring
• Security or timelapse applications

❌ DON'T use this skill when:

• Needing webcam capture → Use system webcam tools
• Capturing video frames from files → Use video-frames
• Needing live streaming → Use streaming tools
• Video editing → Use video editing software

Prerequisites

# Install FFmpeg
brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Ubuntu/Debian

# Verify RTSP support
ffmpeg -formats | grep rtsp

# Camera must be:
# - Network accessible
# - RTSP enabled
# - Credentials known (if required)

Camera URL Formats

Supported Camera Types

Sample URLs

# Generic with authentication
rtsp://admin:password@192.168.1.100:554/stream

# Hikvision (channel 1, high quality)
rtsp://admin:password@192.168.1.100:554/Streaming/Channels/101

# Hikvision (channel 1, low quality)
rtsp://admin:password@192.168.1.100:554/Streaming/Channels/102

# Dahua (channel 1)
rtsp://admin:password@192.168.1.100:554/cam/realmonitor?channel=1&subtype=0

# Axis
rtsp://root:password@192.168.1.100:554/axis-media/media.amp

# Reolink (main stream)
rtsp://admin:password@192.168.1.100:554/h264Preview_01_main

# Reolink (sub stream - lower quality)
rtsp://admin:password@192.168.1.100:554/h264Preview_01_sub

# UniFi Protect
rtsp://192.168.1.100:554/livestream/ch00_0

# Wyze Cam
rtsp://your_username:password@192.168.1.100:554/live

Commands

1. Capture Snapshot

Capture a single frame from camera.

# Basic snapshot (requires credentials)
{baseDir}/camsnap.js snapshot --url rtsp://admin:pass@192.168.1.100/stream --output camera.jpg

# Using separate credentials
{baseDir}/camsnap.js snapshot --ip 192.168.1.100 --port 554 \
  --username admin --password secret --output camera.jpg

# Hikvision camera
{baseDir}/camsnap.js snapshot --type hikvision --ip 192.168.1.100 \
  --username admin --password secret --output camera.jpg

# With quality settings
{baseDir}/camsnap.js snapshot --url rtsp://cam.example.com/stream \
  --format png --quality 1 --output high-quality.png

# Resized snapshot
{baseDir}/camsnap.js snapshot --url rtsp://192.168.1.100/stream \
  --resize 1280x720 --output thumb.jpg

# No timestamp overlay
{baseDir}/camsnap.js snapshot --url rtsp://192.168.1.100/stream \
  --no-timestamp --output clean.jpg

Output Options:

2. Record Video Clip

Record a short video clip from camera.

# Basic recording
{baseDir}/camsnap.js record --url rtsp://192.168.1.100/stream \
  --duration 10 --output clip.mp4

# High quality, 30 seconds
{baseDir}/camsnap.js record --url rtsp://192.168.1.100/stream \
  --duration 30 --quality high --no-audio --output recording.mp4

# With specific frame rate
{baseDir}/camsnap.js record --url rtsp://192.168.1.100/stream \
  --duration 60 --fps 15 --quality medium --output clip.mp4

# Maximum quality (large file)
{baseDir}/camsnap.js record --url rtsp://192.168.1.100/stream \
  --duration 300 --quality maximum --fps 30 --output high-quality.mp4

Quality Presets:

Recording Limits:

• Minimum: 1 second
• Maximum: 3600 seconds (1 hour)
• Recommended: 10-300 seconds

3. Test Camera Connection

Verify camera connectivity and get stream information.

# Test basic connection
{baseDir}/camsnap.js test --url rtsp://192.168.1.100/stream

# Test with credentials
{baseDir}/camsnap.js test --ip 192.168.1.100 --username admin --password secret

# Test Hikvision
{baseDir}/camsnap.js test --type hikvision --ip 192.168.1.100 \
  --username admin --password secret

# Extended timeout for slow cameras
{baseDir}/camsnap.js test --url rtsp://192.168.1.100/stream \
  --timeout 30000

Sample Output:

{
  "connected": true,
  "url": "rtsp://***:***@192.168.1.100...",
  "format": "rtsp",
  "video": {
    "codec": "h264",
    "resolution": "1920x1080",
    "fps": 25,
    "bitrate": "4096000"
  },
  "audio": {
    "codec": "aac",
    "sampleRate": "48000",
    "channels": 2
  }
}

4. Motion Detection

Monitor camera for motion events.

# Monitor for 60 seconds
{baseDir}/camsnap.js detect --url rtsp://192.168.1.100/stream \
  --duration 60

# With custom threshold
{baseDir}/camsnap.js detect --url rtsp://192.168.1.100/stream \
  --duration 300 --threshold 0.05 --clip-duration 10

# On motion, record clip
{baseDir}/camsnap.js detect --url rtsp://192.168.1.100/stream \
  --duration 600 --clip-duration 15 --output-dir ./motion-clips

Detection Options:

5. Credential Management

Store camera credentials securely.

# Save credentials
{baseDir}/camsnap.js credentials --save --name front-door \
  --username admin --password secret --type hikvision

# List saved credentials
{baseDir}/camsnap.js credentials --list

# Use saved credentials
{baseDir}/camsnap.js snapshot --ip 192.168.1.100 \
  --use-credentials front-door --output camera.jpg

Credentials Storage:

• Location: ~/.camsnap_credentials
• Permissions: 600 (owner read/write only)
• Format: JSON with base64-encoded passwords
• No encryption (OS file permissions only)

Camera Setup Guides

Hikvision

# 1. Enable RTSP in camera settings:
#    Configuration > Network > Advanced > RTSP
#    (Port 554 by default)

# 2. Main stream (high quality)
{baseDir}/camsnap.js snapshot --type hikvision --ip 192.168.1.100 \
  --username admin --password password --output camera.jpg

# 3. Sub stream (lower quality, less bandwidth)
{baseDir}/camsnap.js snapshot --url "rtsp://admin:password@192.168.1.100:554/Streaming/Channels/102" \
  --output camera-low.jpg

Channel Numbers:

• Channel 1: 101 (main), 102 (sub)
• Channel 2: 201 (main), 202 (sub)
• Channel N: N01 (main), N02 (sub)

Dahua

# 1. Enable RTSP in camera:
#    Settings > Network > Connection > RTSP

# 2. Capture snapshot
{baseDir}/camsnap.js snapshot --type dahua --ip 192.168.1.100 \
  --username admin --password password --channel 1 --output camera.jpg

# 3. Higher quality (subtype=0)
{baseDir}/camsnap.js snapshot --url "rtsp://admin:password@192.168.1.100:554/cam/realmonitor?channel=1&subtype=0" \
  --output camera.jpg

# 4. Lower quality (subtype=1)
{baseDir}/camsnap.js snapshot --url "rtsp://admin:password@192.168.1.100:554/cam/realmonitor?channel=1&subtype=1" \
  --output camera-low.jpg

Axis

# 1. Enable RTSP in camera:
#    Plain Config > Network > Network > VAPIX

# 2. Test connection
{baseDir}/camsnap.js snapshot --type axis --ip 192.168.1.100 \
  --username root --password pass --output camera.jpg

Reolink

# 1. Enable RTSP in Reolink app:
#    Settings > Device > Stream Protocol > RTSP

# 2. Main stream (1080p)
{baseDir}/camsnap.js snapshot --type reolink --ip 192.168.1.100 \
  --username admin --password password --stream 01 --output camera.jpg

# 3. Sub stream (480p)
{baseDir}/camsnap.js snapshot --url "rtsp://admin:password@192.168.1.100:554/h264Preview_01_sub" \
  --output camera-low.jpg

UniFi Protect

# 1. In UniFi Protect, enable RTSP for camera
#    Settings > System > RTSP Service

# 2. Get stream URL from UniFi dashboard

# 3. Capture snapshot
{baseDir}/camsnap.js snapshot --type unifi --ip 192.168.1.100 \
  --output camera.jpg

Wyze Cam

# 1. Enable RTSP firmware on Wyze
#    (Requires custom firmware)

# 2. Capture snapshot
{baseDir}/camsnap.js snapshot --type wyze --ip 192.168.1.100 \
  --username username --password password --output camera.jpg

Connection Troubleshooting

Common Errors

"Connection timed out"

# Causes:
# 1. Camera not responding
# 2. Network issue
# 3. RTSP not enabled

# Solutions:
ping 192.168.1.100                    # Test connectivity
telnet 192.168.1.100 554              # Test RTSP port
{baseDir}/camsnap.js test --url rtsp://192.168.1.100 --timeout 30000

"Authentication failed"

# Causes:
# 1. Wrong username/password
# 2. Camera requires digest auth
# 3. Credentials have special characters

# Solutions:
# - Verify credentials in camera web UI
# - URL-encode special characters
{baseDir}/camsnap.js snapshot --url "rtsp://admin:p%40ssword@192.168.1.100/stream" \
  --output camera.jpg

"Stream not found"

# Causes:
# 1. Wrong stream path
# 2. Camera type mismatch

# Solutions:
# Check camera documentation for correct RTSP URL
{baseDir}/camsnap.js snapshot --type hikvision --ip 192.168.1.100 \
  --username admin --password secret --output camera.jpg

"FFmpeg error"

# Causes:
# 1. FFmpeg not installed
# 2. RTSP support missing
# 3. Codec not supported

# Solutions:
ffmpeg -protocols | grep rtsp        # Check RTSP support
brew reinstall ffmpeg --with-librtsp # Reinstall with RTSP (macOS)

Error Handling

Error Codes

Exit Status

{baseDir}/camsnap.js test --url rtsp://192.168.1.100/stream
echo $?  # 0 = success

{baseDir}/camsnap.js snapshot --url invalid
echo $?  # 1 = error (see above codes)

Examples

Security Snapshot Script

#!/bin/bash
# Capture hourly snapshots from security cameras

CAMERAS=(
  "rtsp://admin:pass@192.168.1.100/Streaming/Channels/101"
  "rtsp://admin:pass@192.168.1.101/cam/realmonitor?channel=1"
)

OUTPUT_DIR="/var/security/snapshots/$(date +%Y/%m/%d)"
mkdir -p "$OUTPUT_DIR"

for url in "${CAMERAS[@]}"; do
  name=$(echo "$url" | grep -o '[0-9]\+\.\|[0-9]\+$' | head -1)
  timestamp=$(date +%H%M%S)
  
  {baseDir}/camsnap.js snapshot --url "$url" \
    --output "$OUTPUT_DIR/camera_${name}_${timestamp}.jpg" 2>/dev/null
  
  if [ $? -eq 0 ]; then
    echo "[$timestamp] Captured: Camera $name"
  else
    echo "[$timestamp] Failed: Camera $name"
  fi
done

# Keep only last 30 days of snapshots
find /var/security/snapshots -name "*.jpg" -mtime +30 -delete

Timelapse Recording

#!/bin/bash
# Capture snapshot every minute for timelapse

URL="rtsp://admin:password@192.168.1.100/stream"
OUTPUT="/var/timelapse/$(date +%Y%m%d)"
mkdir -p "$OUTPUT"

duration=3600  # Record for 1 hour
interval=60    # Every 60 seconds

# Note: This is simplified - use cron for production
cd "$OUTPUT"
for ((i=0; i<duration; i+=interval)); do
  {baseDir}/camsnap.js snapshot --url "$URL" \
    --output "frame_$(printf %05d $i).jpg" 2>/dev/null
  sleep $interval
done

# Create timelapse video from frames
ffmpeg -framerate 30 -i frame_%05d.jpg -c:v libx264 -crf 18 timelapse.mp4

Motion Detection with Alert

#!/bin/bash
# Monitor camera and send alert on motion

URL="rtsp://admin:password@192.168.1.100/stream"

{baseDir}/camsnap.js detect --url "$URL" --duration 3600 --threshold 0.05

if [ $? -eq 0 ]; then
  # Motion detected - send notification
  echo "Motion detected at $(date)" | mail -s "Security Alert" admin@example.com
  
  # Capture evidence
  {baseDir}/camsnap.js snapshot --url "$URL" --output "/alerts/motion_$(date +%s).jpg"
fi

Multi-Camera Capture

#!/bin/bash
# Capture from multiple cameras simultaneously

CAMERA1="rtsp://admin:pass@192.168.1.100/stream"
CAMERA2="rtsp://admin:pass@192.168.1.101/stream"
CAMERA3="rtsp://admin:pass@192.168.1.102/stream"

{baseDir}/camsnap.js snapshot --url "$CAMERA1" --output /tmp/cam1.jpg &
c1=$!
{baseDir}/camsnap.js snapshot --url "$CAMERA2" --output /tmp/cam2.jpg &
c2=$!
{baseDir}/camsnap.js snapshot --url "$CAMERA3" --output /tmp/cam3.jpg &
c3=$!

# Wait for all
wait $c1 $c2 $c3

# Create contact sheet
montage /tmp/cam1.jpg /tmp/cam2.jpg /tmp/cam3.jpg \
  -tile 3x1 -geometry +4+4 +label "Cam 1" "Cam 2" "Cam 3" \
  -output multisource.jpg

Periodic Recording Scheduler

#!/bin/bash
# Record 10-minute clips every hour

URL="rtsp://admin:password@192.168.1.100/stream"
OUTPUT_DIR="/var/recordings/$(date +%Y%m)"
mkdir -p "$OUTPUT_DIR"

# Add to crontab:
# 0 * * * * /path/to/record-hourly.sh

{baseDir}/camsnap.js record --url "$URL" \
  --duration 600 \
  --quality high \
  --output "$OUTPUT_DIR/recording_$(date +%Y%m%d_%H%M).mp4"

Performance Tips

1. Use TCP Transport (Default)

# TCP is more reliable
{baseDir}/camsnap.js snapshot --url rtsp://192.168.1.100/stream

# For UDP (may drop packets)
{baseDir}/camsnap.js snapshot --url rtsp://192.168.1.100/stream --transport udp

2. Optimize Quality

# Quick preview
{baseDir}/camsnap.js snapshot --url "..." --resize 640x480 --quality 5

# Quality capture
{baseDir}/camsnap.js snapshot --url "..." --format png --resize 1

3. Use Lower Stream

# For Hikvision: use channel 102 (sub-stream) instead of 101
{baseDir}/camsnap.js snapshot --url "rtsp://admin:pass@192.168.1.100/Streaming/Channels/102"

4. Parallel Operations

# Start multiple captures in parallel
{baseDir}/camsnap.js snapshot --url rtsp://cam1/stream --out /tmp/c1.jpg &
cam1_id=$!
{baseDir}/camsnap.js snapshot --url rtsp://cam2/stream --out /tmp/c2.jpg &
cam2_id=$!

# Wait for completion
wait $cam1_id $cam2_id

Technical Details

Connection Flow

1. Parse camera configuration
   ├── URL or constructed from params
   ├── Credentials embedded
   └── Type-specific formatting

2. Test connection
   ├── ffprobe RTSP stream
   ├── Verify authentication
   └── Get stream info

3. Capture
   ├── FFmpeg connects
   ├── Extract frame/record
   └── Save with timestamp

4. Return result
   └── File path, size, metadata

RTSP Parameters

Default FFmpeg settings:

-rtsp_transport tcp          # Use TCP (reliable)
-stimeout 5000000           # 5 second read timeout
-frames:v 1                  # Capture single frame
-q:v 2                       # JPEG quality

Recording Settings

Quality presets use H.264 with AAC audio:

-low:     -crf 28 -preset ultrafast -b:v 500k -r 10
-medium:  -crf 23 -preset fast      -b:v 1000k -r 15
-high:    -crf 20 -preset medium    -b:v 2000k -r 25
-maximum: -crf 18 -preset slow      -b:v 4000k -r 30

Security Notes

• Credential Storage: Stored in ~/.camsnap_credentials with 600 permissions
• URL Handling: Passwords are hidden in output
• No Encryption: Use system file permissions on credential file
• Network Security: Camera should be on local network or VPN
• HTTPS: Not used (RTSP protocol limitation)
• Rotate Credentials: Periodically update camera passwords

Notes

• Snapshots include timestamp overlay by default
• Recording shows progress in terminal
• Maximum clip duration: 1 hour
• Supports both TCP and UDP RTSP transport
• FFmpeg required for all operations
• Credential names can be any string
• Camera types automate URL building
• All output files are verified for non-zero size
• Special characters in passwords must be URL-encoded
• Timelapse creation requires separate ffmpeg command
• Motion detection is basic (sampling only)
• For production monitoring, use dedicated NVR software