AgentWebCam CLI

A command-line tool designed for AI agents (Gemini, Codex, etc.) to capture snapshots and record video from a webcam for automated analysis.

Features

• List Cameras: Discover available camera indices.
• Snap Image: Capture a high-quality frame.
• Record Video: Record fixed-duration video clips.

Installation

1. Ensure Python 3.9+ is installed.
2. Install dependencies:

   pip install opencv-python click numpy

3. (Optional) Install the package in editable mode:

   pip install -e .

Usage

List available cameras

agentwebcam list

Take a picture

agentwebcam snap --camera 0 --output snapshot.jpg

Record a video (5 seconds) with motion detection and overlays

agentwebcam record --camera 0 --duration 30 --motion --overlay --output activity.mp4

Create a timelapse

# Capture a frame every 5 seconds for 1 hour (3600s)
agentwebcam timelapse --duration 3600 --interval 5 --output daily_timelapse.mp4

Tune camera settings

# Automatically adjust brightness
agentwebcam tune --auto

# Manually adjust
agentwebcam tune brightness 128

Manage Presets

# Save current settings
agentwebcam preset save night-vision

# Apply saved settings
agentwebcam preset apply night-vision

# List all presets
agentwebcam preset list

Advanced Features

• Autotuning: Automatically adjusts hardware settings to achieve optimal image balance.
• Hardware Presets: Save and load custom camera configurations for different environments (e.g., night, low-light).
• Visual Overlays: Burns real-time clock and event annotations directly into the video stream.
• Motion Detection: Saves disk space by only recording when significant movement is detected.
• Microphone Support: Record synchronized audio from any detected input device.
• SRT Subtitles: Generates sidecar subtitle files for post-capture analysis.

macOS

• Permissions: You must grant Terminal (or your IDE) permission to access the Camera. If it doesn't prompt, check System Settings > Privacy & Security > Camera.
• Backends: Uses AVFoundation.

Windows

• Backends: Uses MSMF or DSHOW.
• Codecs: Highly compatible with mp4v.

Linux

• Backends: Uses V4L2.
• Dependencies: If using opencv-python-headless, ensure system libraries are present (e.g., libgl1).
• Permissions: Ensure your user is in the video group (e.g., sudo usermod -aG video $USER).

Requirements

• Python 3.9+
• OpenCV (opencv-python or opencv-python-headless)
• click
• numpy