example.yaml

# HomeSec Configuration Example
#
# Copy this file and customize for your setup:
#   cp config/example.yaml config/config.yaml
#
# All secrets should be stored in .env (see .env.example)
# Reference them here using _env suffix (e.g., token_env: MY_TOKEN)
#
# Run with:
#   homesec run --config config/config.yaml

version: 1

# =============================================================================
# Cameras - Define your video sources
# =============================================================================
cameras:
  # RTSP camera (IP cameras, NVRs)
  - name: front_door
    source:
      backend: rtsp
      config:
        # RTSP URL from environment variable (set in .env)
        rtsp_url_env: FRONT_DOOR_RTSP_URL
        # Optional: separate low-res stream for motion detection
        # detect_rtsp_url_env: FRONT_DOOR_RTSP_SUB_URL
        output_dir: "./recordings"
        stream:
          # Customize ffmpeg behavior (e.g., for flaky TCP streams)
          ffmpeg_flags: ["-rtsp_transport", "tcp", "-vsync", "0"]
          connect_timeout_s: 2.0  # RTSP connect timeout (seconds)
          io_timeout_s: 2.0       # RTSP I/O timeout (seconds)
          disable_hwaccel: false
        motion:
          pixel_threshold: 45        # Pixel difference threshold (0-255)
          min_changed_pct: 1.0       # Min % of frame that must change (idle)
          recording_sensitivity_factor: 2.0  # Recording keepalive sensitivity (>=1.0)
          blur_kernel: 5             # Blur kernel size (reduces noise)
        recording:
          stop_delay: 10             # Seconds of no motion before stopping
          max_recording_s: 60        # Max clip length before rotation
        runtime:
          frame_timeout_s: 2.0       # Timeout waiting for frames
          frame_queue_size: 20       # Frame queue size
          heartbeat_s: 30.0          # Heartbeat log interval
          debug_motion: false
        reconnect:
          backoff_s: 1.0             # Backoff between reconnects
          max_attempts: 0            # 0 = retry forever
          detect_fallback_attempts: 3  # Switch detect stream to main after N failures

  # FTP server (receive uploads from cameras that support FTP)
  - name: ftp_camera
    source:
      backend: ftp
      config:
        host: "0.0.0.0"
        port: 2121
        root_dir: "./ftp_incoming"
        anonymous: true
        # For authenticated FTP:
        # anonymous: false
        # username_env: FTP_USERNAME
        # password_env: FTP_PASSWORD

  # Local folder (watch for new files)
  - name: local_camera
    source:
      backend: local_folder
      config:
        watch_dir: "./recordings"
        poll_interval: 1.0           # Seconds between folder scans
        stability_threshold_s: 1.0   # Wait for file to stop growing

# =============================================================================
# Storage - Where to upload processed clips
# =============================================================================
storage:
  backend: dropbox  # Options: dropbox, local

  # Backend-specific config
  config:
    root: "/homecam"
    # Simple token auth (get from Dropbox App Console)
    token_env: DROPBOX_TOKEN
    # OR OAuth refresh flow (for long-running apps)
    # app_key_env: DROPBOX_APP_KEY
    # app_secret_env: DROPBOX_APP_SECRET
    # refresh_token_env: DROPBOX_REFRESH_TOKEN
    web_url_prefix: "https://www.dropbox.com/home"

# =============================================================================
# State Store - PostgreSQL for clip state tracking
# =============================================================================
state_store:
  dsn_env: DB_DSN  # e.g., postgresql+asyncpg://user:pass@localhost:5432/homesec

# =============================================================================
# Preview - Live preview config contract (v1 HLS; RTSP sources support on-demand preview)
# =============================================================================
preview:
  enabled: false
  backend: hls
  token_ttl_s: 60
  idle_timeout_s: 30.0
  recording_policy: stop_on_recording  # Use allow_during_recording for best-effort concurrent preview; may consume an extra RTSP session
  config:
    segment_duration_ms: 1000  # Lower latency means more segment churn
    live_window_segments: 4    # Total window ~= segment_duration_ms * segment count
    storage_dir: /tmp/homesec-preview  # Prefer tmpfs; keep separate from recordings and other durable storage
    audio_enabled: true
    audio_codec: auto
    video_codec: auto

# =============================================================================
# Notifiers - How to send alerts
# =============================================================================
# Optional: set to [] (or disable all entries) to run analysis-only with no external alerts.
notifiers:
  # MQTT (for Home Assistant, Node-RED, etc.)
  - backend: mqtt
    config:
      host: "localhost"
      port: 1883
      auth:
        username_env: MQTT_USERNAME
        password_env: MQTT_PASSWORD
      topic_template: "homecam/alerts/{camera_name}"
      qos: 1
      retain: false

  # SendGrid email
  # - backend: sendgrid_email
  #   config:
  #     api_key_env: SENDGRID_API_KEY
  #     from_email: "alerts@example.com"
  #     from_name: "HomeSec"
  #     to_emails: ["you@example.com"]

# =============================================================================
# Filter - Object detection to filter clips
# =============================================================================
filter:
  backend: yolo
  config:
    # Model downloads automatically to ./yolo_cache
    # model_path: "yolo11n.pt"  # Default model
    max_workers: 4  # Parallel detection workers (plugin-specific)
    classes:
      - person
      - car
      - truck
      - motorcycle
      - bicycle
      - dog
      - cat
    min_confidence: 0.5
    sample_fps: 2           # Frames per second to analyze
    min_box_h_ratio: 0.03   # Min box height as ratio of frame

# =============================================================================
# VLM - Vision Language Model for scene analysis
# =============================================================================
vlm:
  backend: openai
  trigger_classes: ["person"]  # Only run VLM if these detected
  run_mode: trigger_only  # trigger_only | always | never
  config:
    api_key_env: OPENAI_API_KEY
    model: "gpt-4o"
    # For local/alternative providers:
    # base_url: "http://localhost:1234/v1"
    # model: "local-model-name"
  preprocessing:
    max_frames: 10    # Max frames to send to VLM
    max_size: 1024    # Max dimension (pixels)
    quality: 85       # JPEG quality (1-100)

# =============================================================================
# Alert Policy - When to send notifications
# =============================================================================
alert_policy:
  backend: default
  enabled: true
  config:
    min_risk_level: "medium"  # Options: low, medium, high, critical
    notify_on_activity_types:
      - person_at_door
      - delivery
      - suspicious
    notify_on_motion: false   # Alert on any motion (no VLM required)
    overrides:
      front_door:
        min_risk_level: "low"
        notify_on_activity_types:
          - person_at_door
          - delivery
          - suspicious
          - animal

# =============================================================================
# Advanced Settings (optional)
# =============================================================================

# Retry settings for transient failures
# retry:
#   max_attempts: 3
#   backoff_s: 1.0

# Concurrency limits
# concurrency:
#   max_clips_in_flight: 4
#   upload_workers: 4
#   filter_workers: 4
#   vlm_workers: 2

# Periodic Postgres backups
# maintenance:
#   postgres_backup:
#     enabled: false
#     interval: 24h
#     keep_count: 5
#     local_dir: ./backups/postgres
#     timeout_s: 1800
#     compression_level: 6
#     upload:
#       enabled: true
#       storage_backend: primary