# Clip Saver

{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}

## Clip Saving Analyzer Module Overview <a href="#clip-saving-analyzer-module-overview" id="clip-saving-analyzer-module-overview"></a>

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 <a href="#classes" id="classes"></a>

## ClipSavingAnalyzer <a href="#clipsavinganalyzer" id="clipsavinganalyzer"></a>

`ClipSavingAnalyzer`

Bases: `ResultAnalyzerBase`

Result-analyzer that records short video clips whenever one of the configured trigger names appears in an [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults). It delegates internally to [`ClipSaver`](https://docs.degirum.com/degirum-tools/support/video_support), which maintains a circular buffer, so every clip contains both pre-trigger and post-trigger context.

### ClipSavingAnalyzer Methods <a href="#clipsavinganalyzer-methods" id="clipsavinganalyzer-methods"></a>

#### \_\_init\_\_(clip\_duration, ...) <a href="#init" id="init"></a>

`__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`](https://docs.degirum.com/degirum-tools/event_detector#key_events_detected) or [`EventNotifier`](https://docs.degirum.com/degirum-tools/notifier#key_notifications). | *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) <a href="#analyze" id="analyze"></a>

`analyze(result)`

Inspect a single [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) and forward it to internal [`ClipSaver`](https://docs.degirum.com/degirum-tools/support/video_support) if any trigger names are matched.

This method is called automatically for each frame when attached via [`attach_analyzers`](https://docs.degirum.com/degirum-tools/inference_support).

Parameters:

| Name     | Type                                                                                                                             | Description                                            | Default    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------- |
| `result` | [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | Current model output to scan for events/notifications. | *required* |

#### join\_all\_saver\_threads <a href="#join_all_saver_threads" id="join_all_saver_threads"></a>

`join_all_saver_threads()`

Block until all background clip-writer threads finish.

Returns:

| Name  | Type  | Description                         |
| ----- | ----- | ----------------------------------- |
| `int` | `int` | Number of threads that were joined. |