Software Configuration | CowCatcher AI

Detection (What to watch)

Configure the sources the detector should monitor.

source: RTSP/HTTP stream URL or local video path. Use a list [ ] for multiple sources.
interval: Seconds to wait between processed frames (default 0). Useful to reduce load on slow machines.
frame_retention: How many recent frames to keep in memory per source (default 30) for context.

The fast first-pass AI that scans every frame. Without YOLO, all frames simply pass through.

model: URL or local path to a YOLO model file (.pt or .onnx).
confidence: Confidence required (0-1). Can also be a per-class threshold, e.g., { "person": 0.85 }.
time_max: Maximum duration in seconds to group frames into one event (default 60).
timeout: Seconds of no detections before the event is considered over (default 5).
cooldown: Seconds to wait before starting a new event. Prevents repeat alerts. Can be per class.
include_trailing_time: Seconds of extra footage to include after the last detection (default 1).
frames_min: How many frames in a row must match before counting (default 6, or 3 depending on GPU).
imgsz: Image size fed into the model. Higher is more accurate but slower (default 640).
strategy: Which frames to evaluate: "LATEST" (most recent only) or "ALL".

A Vision Language Model checks the footage after a YOLO detection. Greatly reduces false alarms.

prompt: The question to ask, e.g., 'Is there a person in this video?'.
model: The AI model (e.g., 'gemini/gemini-2.0-flash'). Supports LiteLLM providers.
key: API key for the chosen model provider.
url: Custom API endpoint, useful for local models.
strategy: "VIDEO" sends a clip to the AI. "IMAGE" sends a single frame (cheaper but less accurate).

Configure where confirmed detections should be sent.

directory: Folder path under 'detections/' to save files into. Otherwise uses the class name.
strategy: "BEST" saves only the highest-confidence frame. "ALL" saves every frame.
confidence: Minimum confidence required to save.
export_rejected: Whether to also save detections rejected by the VLM (default true).

token: Your Telegram bot token.
chat: The Telegram chat or user ID.
confidence: Minimum confidence required to send.
alert_every: Only send an alert every Nth detection (1 = every time, 5 = every 5th).
include_plot: Include the full frame with a detection box drawn on it (default false).
include_crop: Include a cropped image of just the detected object (default false).
include_video: Include an MP4 clip of the detection sequence (default true).
video_width: Width of the video clip in pixels (default 1280).
video_crf: Video quality (0-51). Lower = better quality, default 28.
export_rejected: Whether to also send detections rejected by the VLM (default false).

url: The URL to POST to when a detection occurs.
token: Authorization token sent in the request headers.
confidence: Minimum confidence required to trigger.
data_type: How image/video data is encoded in the payload: "binary" or "base64".
data_max: Maximum payload size in bytes. Images are compressed if they exceed this.
include_plot: Include the full frame with detection overlay (default false).
include_crop: Include a cropped image of the detected area (default true).
include_video: Include an MP4 clip of the detection sequence (default false).
video_width: Width of the video clip in pixels (default 1280).
video_crf: Video quality (0-51). Lower = better quality, default 28.
export_rejected: Whether to also POST detections rejected by the VLM (default false).

Sends a simple periodic HTTP request to verify the process is still alive.

url: The URL to ping.
method: HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD (default GET).
interval: Seconds between pings (default 60).
timeout: Request timeout in seconds (default 5).
headers: Optional HTTP headers map.
body: Optional request body sent as raw text.

Controls how ONNX Runtime configures before loading a YOLO model.

provider: Optional provider name to force (e.g., "CUDAExecutionProvider").
winml: For Windows ML build only. Tries to register ML execution providers (default true).
opset: ONNX opset used when exporting. Lower values can improve compatibility (default 20).

View the full documentation, example configurations and the Docker setup on our official GitHub page.