# Clip Saver
{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}
## 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](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults). It delegates internally to [`ClipSaver`](/degirum-tools/support/video_support.md), which maintains a circular buffer, so every clip contains both pre-trigger and post-trigger context.
### ClipSavingAnalyzer Methods
#### \_\_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`](/degirum-tools/analyzers/event_detector.md#key_events_detected) or [`EventNotifier`](/degirum-tools/analyzers/notifier.md#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)
`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`](/degirum-tools/support/video_support.md) if any trigger names are matched.
This method is called automatically for each frame when attached via [`attach_analyzers`](/degirum-tools/inference_support.md).
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
`join_all_saver_threads()`
Block until all background clip-writer threads finish.
Returns:
| Name | Type | Description |
| ----- | ----- | ----------------------------------- |
| `int` | `int` | Number of threads that were joined. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.degirum.com/degirum-tools/analyzers/clip_saver.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.