Clip Saver

DeGirum Tools API Reference Guide. Record video clips around trigger events.

This API Reference is based on DeGirum Tools version 0.18.0.

Clip Saving Analyzer Module Overview

This module provides an analyzer (ClipSavingAnalyzer) for recording video snippets triggered by events or notifications. It captures frames before and after trigger events, saving them as video clips with optional AI annotations and metadata.

Key Features

  • Pre/Post Buffering: Configurable frame count before and after trigger events

  • Optional Overlays: Embed AI bounding boxes and labels in the saved clips

  • Side-car JSON: Save raw inference results alongside video files

  • Thread-Safe: Each clip is written by its own worker thread

  • Frame Rate Control: Configurable target FPS for saved clips

  • Event Integration: Works with EventDetector and EventNotifier triggers

  • Storage Support: Optional integration with object storage for clip uploads

Typical Usage

  1. Create a ClipSavingAnalyzer instance with desired buffer and output settings

  2. Process inference results through the analyzer chain

  3. When triggers occur, clips are automatically saved with pre/post frames

  4. Access saved clips and their associated metadata files

  5. Optionally upload clips to object storage for remote access

Integration Notes

  • Works with any analyzer that adds trigger names to results

  • Requires video frames to be available in the result object

  • Supports both local file storage and object storage uploads

  • Thread-safe for concurrent clip saving operations

Key Classes

  • ClipSavingAnalyzer: Main analyzer class for saving video clips

  • ClipSaver: Internal class handling clip writing and buffering

Configuration Options

  • clip_duration: Number of frames to save after trigger

  • clip_prefix: Base path for saved clip files

  • pre_trigger_delay: Frames to include before trigger

  • embed_ai_annotations: Enable/disable AI overlays in clips

  • save_ai_result_json: Enable/disable metadata saving

  • target_fps: Frame rate for saved video clips

Classes

ClipSavingAnalyzer

ClipSavingAnalyzer

Bases: ResultAnalyzerBase

Result-analyzer that records short video clips whenever one of the configured trigger names appears in an InferenceResults. It delegates internally to ClipSaver, which maintains a circular buffer, so every clip contains both pre-trigger and post-trigger context.

Functions

__init__(clip_duration, ...)

__init__(clip_duration, triggers, file_prefix, *, pre_trigger_delay=0, embed_ai_annotations=True, save_ai_result_json=True, target_fps=30.0)

Constructor.

Parameters:

Name
Type
Description
Default

clip_duration

int

Total length of the output clip in frames (pre-buffer + post-buffer).

required

triggers

Set[str]

Names that fire the recorder when found in either EventDetector or EventNotifier.

required

file_prefix

str

Path and filename prefix for generated files (frame number & extension are appended automatically).

required

pre_trigger_delay

int

Frames to include before the trigger. Defaults to 0.

0

embed_ai_annotations

bool

If True, use InferenceResults.image_overlay so bounding boxes/labels are burned into the clip. Defaults to True.

True

save_ai_result_json

bool

If True, dump a JSON file with raw inference results alongside the video. Defaults to True.

True

target_fps

float

Frame rate of the output file. Defaults to 30.0.

30.0

analyze(result)

analyze(result)

Inspect a single InferenceResults and forward it to internal ClipSaver if any trigger names are matched.

This method is called automatically for each frame when attached via attach_analyzers.

Parameters:

Name
Type
Description
Default

result

Current model output to scan for events/notifications.

required

join_all_saver_threads

join_all_saver_threads()

Block until all background clip-writer threads finish.

Returns:

Name
Type
Description

int

int

Number of threads that were joined.

Last updated

Was this helpful?