Savant

https://savant-ai.io/docs/latest/
Admin
Savant is an open-source, high-level Python/C++/Rust framework for building real-time, streaming...
Tokens:203,603
Snippets:2,169
Trust Score:6.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build Asynchronous Source with Configuration

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant_rs.py.client.SourceBuilder.html

This example demonstrates how to create an asynchronous Source object, similar to the synchronous version but designed for non-blocking operations. It includes logging and socket setup.

```python
source = (
    SourceBuilder()
    .with_log_provider(JaegerLogProvider('http://localhost:16686'))
    .with_socket('req+connect:ipc:///tmp/zmq-sockets/input-video.ipc')
    .build_async()
)
result = await source(JpegSource('cam-1', 'data/AVG-TownCentre.jpeg'))
result.logs().pretty_print()

```

--------------------------------

### NvInferModelInput Configuration Examples

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.deepstream.nvinfer.model.NvInferModelInput.html

Examples demonstrating how to configure NvInferModelInput with specific shape and offsets.

```yaml
shape: [3, 224, 224]
```

```yaml
offsets: [0.0, 0.0, 0.0]
```

--------------------------------

### Source Usage Example

Source: https://savant-ai.io/docs/latest/reference/api/client.html

Example demonstrating how to use the Client SDK to build a source, send a JPEG image, and process the results.

```APIDOC
## Source Usage Example

### Description
This example shows how to initialize telemetry, build a source using `SourceBuilder`, send a JPEG image from a file to a module, and retrieve the status and logs of the operation.

### Method
```python
import time
from savant_rs.telemetry import (
    ContextPropagationFormat,
    Protocol,
    TelemetryConfiguration,
    TracerConfiguration,
)
from savant.client import JaegerLogProvider, JpegSource, SourceBuilder

# Initialize OTLP tracer to send metrics and logs to Jaeger.
# Note: the same OTLP tracer also should be configured in the module.
télémetry_config = TelemetryConfiguration(
    context_propagation_format=ContextPropagationFormat.W3C,
    tracer=TracerConfiguration(
        service_name='savant-client',
        protocol=Protocol.Grpc,
        endpoint='http://jaeger:4317',
        # tls=ClientTlsConfig(
        #     ca='/path/to/ca.crt',
        #     identity=Identity(
        #         certificate='/path/to/client.crt',
        #         key='/path/to/client.key',
        #     ),
        # ),
        # timeout=5000,  # milliseconds
    ),
)
télémetry.init(telemetry_config)
# or
# use x509 provider config file (take a look at samples/telemetry/otlp/x509_provider_config.json)
# telemetry.init_from_file('/path/to/x509_provider_config.json')


# Build the source
source = (
    SourceBuilder()
    .with_log_provider(JaegerLogProvider('http://localhost:16686'))
    .with_socket('pub+connect:ipc:///tmp/zmq-sockets/input-video.ipc')
    # Note: healthcheck port should be configured in the module.
    .with_module_health_check_url('http://172.17.0.1:8888/status')
    .build()
)

# Send a JPEG image from a file to the module
result = source(JpegSource('cam-1', 'data/AVG-TownCentre.jpeg'))
print(result.status)
time.sleep(1)  # Wait for the module to process the frame
result.logs().pretty_print()

# Shutdown the the tracer
télémetry.shutdown()
```
```

--------------------------------

### Install Docker

Source: https://savant-ai.io/docs/latest/_sources/getting_started/0_configure_prod_env.rst.txt

Download and execute the official Docker installation script to install Docker on Ubuntu 22.04.

```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```

--------------------------------

### Install Nvidia Container Toolkit

Source: https://savant-ai.io/docs/latest/getting_started/0_configure_prod_env.html

Configure apt sources for Nvidia Docker and install the Nvidia Container Toolkit. Restart Docker to apply changes.

```bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

```

--------------------------------

### Model Input Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.base.model.ModelInput.html

This example demonstrates how to configure model input parameters in a module's configuration file, specifying the input object, shape, and aspect ratio.

```yaml
model:
    input:
        object: 'frame'
        shape: [3, 240, 240]
        maintain_aspect_ratio: True

```

--------------------------------

### Async Source Example

Source: https://savant-ai.io/docs/latest/reference/api/client.html

Example of how to build and use an asynchronous source to send JPEG images to a module.

```APIDOC
## Async Source Example

### Description
This example demonstrates building an asynchronous source and sending a JPEG image to a module.

### Method
`SourceBuilder().with_log_provider(...).with_socket(...).build_async()`

### Endpoint
`pub+connect:ipc:///tmp/zmq-sockets/input-video.ipc`

### Parameters
#### Request Body
- **JpegSource** (object) - Required - Represents the JPEG image source with camera ID and file path.
  - **camera_id** (string) - Required - The identifier for the camera stream.
  - **path** (string) - Required - The file path to the JPEG image.

### Response
#### Success Response (200)
- **status** (string) - The status of the operation.
```

--------------------------------

### Download Example Model Archive using AWS CLI

Source: https://savant-ai.io/docs/latest/_sources/savant_101/27_working_with_models.rst.txt

Use this command to download an example model archive for the Nvidia car classification sample. Ensure you have AWS CLI installed and configured.

```bash
aws --endpoint-url=https://eu-central-1.linodeobjects.com s3 cp s3://savant-data/models/Primary_Detector/Primary_Detector.zip .
```

--------------------------------

### Module Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.config.schema.Module.html

Illustrates the structure of a module configuration file, including name, parameters, and pipeline definition with source and elements.

```yaml
name: module_name
parameters:
pipeline:
    source:
        element: uridecodebin
        properties:
            uri: file:///data/test.mp4
    elements:
    sink:
        - element: console_sink

```

--------------------------------

### Sink Usage Example

Source: https://savant-ai.io/docs/latest/reference/api/client.html

Example demonstrating how to use the Client SDK to build a sink with specified socket, idle timeout, and log provider.

```APIDOC
## Sink Usage Example

### Description
This example shows how to use the `SinkBuilder` to create a sink, configuring its connection socket, idle timeout, and a Jaeger log provider.

### Method
```python
from savant.client import JaegerLogProvider, SinkBuilder

# Build the sink
sink = (
    SinkBuilder()
    .with_socket('sub+connect:ipc:///tmp/zmq-sockets/output-video.ipc')
    .with_idle_timeout(60)
    .with_log_provider(JaegerLogProvider('http://localhost:16686'))
    # Note: healthcheck port should be configured in the module.
    .with_module_health_check_url('http://172.17.0.1:8888/status')
    .build()
)
```
```

--------------------------------

### Python Path Configuration Example

Source: https://savant-ai.io/docs/latest/_sources/savant_101/70_python.rst.txt

Example of configuring a Python Function Unit using a Python path for the module.

```yaml
- element: pyfunc
  module: samples.traffic_meter.line_crossing
  class_name: LineCrossing
```

--------------------------------

### NvInferAttributeModel Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.deepstream.nvinfer.model.NvInferAttributeModel.html

This example demonstrates how to configure an NvInferAttributeModel for a classifier, specifying model details, input/output layers, and attribute extraction parameters.

```yaml
- element: nvinfer@classifier
  name: Secondary_CarColor
  model:
    format: caffe
    model_file: resnet18.caffemodel
    mean_file: mean.ppm
    label_file: labels.txt
    precision: int8
    int8_calib_file: cal_trt.bin
    batch_size: 16
    input:
      object: Primary_Detector.Car
      object_min_width: 64
      object_min_height: 64
      color_format: bgr
    output:
      layer_names: [predictions/Softmax]
      attributes:
        - name: car_color
          threshold: 0.51

```

--------------------------------

### Python Async Source and Sink Example

Source: https://savant-ai.io/docs/latest/_sources/reference/api/client.rst.txt

Provides an asynchronous example for both source and sink operations. It demonstrates building async sources and sinks, sending frames, and receiving results concurrently. The OTLP tracer should also be configured in the module.

```python
import asyncio
from savant_rs.telemetry import (
    ContextPropagationFormat,
    Protocol,
    TelemetryConfiguration,
    TracerConfiguration,
)
from savant.client import JaegerLogProvider, JpegSource, SinkBuilder, SourceBuilder


async def run_source():
    # Build the source
    source = (
        SourceBuilder()
        .with_log_provider(JaegerLogProvider('http://localhost:16686'))
        .with_socket('pub+connect:ipc:///tmp/zmq-sockets/input-video.ipc')
        .build_async()
    )

    # Send a JPEG image from a file to the module
    result = await source(JpegSource('cam-1', 'data/AVG-TownCentre.jpeg'))
    print(result.status)


async def run_sink():
    # Build the sink
    sink = (
        SinkBuilder()
        .with_socket('sub+connect:ipc:///tmp/zmq-sockets/output-video.ipc')
        .with_idle_timeout(60)
        .with_log_provider(JaegerLogProvider('http://localhost:16686'))
        .build_async()
    )

    # Receive results from the module and print them
    async for result in sink:
        print(result.frame_meta)
        result.logs().pretty_print()


async def main():
    # Initialize the OTLP tracer to send metrics and logs to Jaeger.
    # Note: the Jaeger tracer also should be configured in the module.
    telemetry_config = TelemetryConfiguration(
        context_propagation_format=ContextPropagationFormat.W3C,
        tracer=TracerConfiguration(
            service_name='savant-client',
            protocol=Protocol.Grpc,
            endpoint='http://jaeger:4317',
            # tls=ClientTlsConfig(
            #     ca='/path/to/ca.crt',
            #     identity=Identity(

```

--------------------------------

### ObjectModelOutput Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.base.model.ObjectModelOutput.html

This example shows how to configure the model output section in a module configuration file. It specifies the layer names to be used and provides a structure for defining output objects.

```yaml
model:
    # model configuration
    output:
        layer_names: [output]
        objects:
            # output objects configuration


```

--------------------------------

### Pipeline Idle Monitor Configuration Example

Source: https://savant-ai.io/docs/latest/advanced_topics/3_pipeline_idle_monitor.html

Example YAML configuration for Pipeline Idle Monitor. It shows how to set up monitoring for buffer overload and ingress/egress idle conditions, including actions and timing parameters.

```yaml
watch:
   - buffer: buffer1:8000
     ingress:
      action: restart
      cooldown: 60s
      idle: 100s
      container:
         - labels: label2
         - labels: label3
     queue:
      action: stop
      length: 999
      cooldown: 60s
      polling_interval: 10s
      container:
         - labels: label1

```

--------------------------------

### NvInferObjectModelOutput Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.deepstream.nvinfer.model.NvInferObjectModelOutput.html

This example demonstrates how to configure the output section for an NvInferObjectModel in a YAML file. It specifies the number of detected classes and the output layer names.

```yaml
model:
    # model configuration
    output:
        num_detected_classes: 4
        layer_names: [output]
        objects:
            # output objects configuration

```

--------------------------------

### AttributeModelOutputAttribute Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.base.model.AttributeModelOutputAttribute.html

This example demonstrates how to configure attributes for a model's output in a module configuration file. It shows the structure for defining attribute names and their corresponding labels.

```yaml
attributes:
    - name: color
      labels: ['red', 'green']

```

--------------------------------

### NvInferComplexModel Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.deepstream.nvinfer.model.NvInferComplexModel.html

This example demonstrates how to configure a complex model, such as a face detector, using the NvInferComplexModel template. It specifies model format, configuration files, and output layer details.

```yaml
- element: nvinfer@complex_model
  name: face_detector
  model:
    format: onnx
    config_file: config.txt
    output:
      layer_names: ['bboxes', 'scores', 'landmarks']
      converter:
        module: module.face_detector_coverter
        class_name: FaceDetectorConverter
      objects:
        - class_id: 0
          label: face
          selector:
            module: savant.selector
            class_name: BBoxSelector
            kwargs:
              confidence_threshold: 0.5
              nms_iou_threshold: 0.5
      attributes:
        - name: landmarks

```

--------------------------------

### Build Module Engines for Nvidia Car Classification Example

Source: https://savant-ai.io/docs/latest/_sources/savant_101/27_working_with_models.rst.txt

This command builds the model engines for the Nvidia car classification example. Ensure you are in the Savant directory when running this script.

```bash
./scripts/run_module.py --build-engines samples/nvidia_car_classification/module.yml
```

--------------------------------

### Precision Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.deepstream.nvinfer.model.NvInferComplexModel.html

Shows how to set the data precision for inference. Supported precisions include 'fp16' and 'int8'.

```yaml
precision: fp16
# precision: int8

```

--------------------------------

### Model Format Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.deepstream.nvinfer.model.NvInferComplexModel.html

Illustrates how to specify the model file format. The 'format' parameter accepts predefined values, such as 'onnx'.

```yaml
format: onnx
# format: caffe
# etc.
# look in enum for full list of format options

```

--------------------------------

### OpenTelemetry Configuration without TLS

Source: https://savant-ai.io/docs/latest/_sources/advanced_topics/9_open_telemetry.rst.txt

Configure OpenTelemetry without TLS for simpler setups. This example connects to a local Jaeger instance.

```json
{
      "tracer": {
          "service_name": "${TRACING_SERVICE_NAME:-default-name}",
          "protocol": "grpc",
          "endpoint": "http://jaeger:4317",
          "timeout": {
              "secs": 10,
              "nanos": 0
          }
      },
      "context_propagation_format": "w3c"
    }
```

--------------------------------

### Initialize and Use a Source

Source: https://savant-ai.io/docs/latest/reference/api/client.html

Initializes an OTLP tracer for metrics and logs, builds a source using SourceBuilder, and sends a JPEG image to a module. Ensure the healthcheck port is configured in the module.

```python
import time
from savant_rs.telemetry import (
    ContextPropagationFormat,
    Protocol,
    TelemetryConfiguration,
    TracerConfiguration,
)
from savant.client import JaegerLogProvider, JpegSource, SourceBuilder

# Initialize OTLP tracer to send metrics and logs to Jaeger.
# Note: the same OTLP tracer also should be configured in the module.
telemetry_config = TelemetryConfiguration(
    context_propagation_format=ContextPropagationFormat.W3C,
    tracer=TracerConfiguration(
        service_name='savant-client',
        protocol=Protocol.Grpc,
        endpoint='http://jaeger:4317',
        # tls=ClientTlsConfig(
        #     ca='/path/to/ca.crt',
        #     identity=Identity(
        #         certificate='/path/to/client.crt',
        #         key='/path/to/client.key',
        #     ),
        # ),
        # timeout=5000,  # milliseconds
    ),
)
telemetry.init(telemetry_config)
# or
# use x509 provider config file (take a look at samples/telemetry/otlp/x509_provider_config.json)
# telemetry.init_from_file('/path/to/x509_provider_config.json')


# Build the source
source = (
    SourceBuilder()
    .with_log_provider(JaegerLogProvider('http://localhost:16686'))
    .with_socket('pub+connect:ipc:///tmp/zmq-sockets/input-video.ipc')
    # Note: healthcheck port should be configured in the module.
    .with_module_health_check_url('http://172.17.0.1:8888/status')
    .build()
)

# Send a JPEG image from a file to the module
result = source(JpegSource('cam-1', 'data/AVG-TownCentre.jpeg'))
print(result.status)
time.sleep(1)  # Wait for the module to process the frame
result.logs().pretty_print()

# Shutdown the the tracer
telemetry.shutdown()

```

--------------------------------

### Compile Documentation from Sources

Source: https://savant-ai.io/docs/latest/_sources/savantdev/0_configure_doc_env.rst.txt

Run this command to build the documentation after the environment is set up. The output will be available in the build/html directory.

```bash
make run-docs
```

--------------------------------

### Install Nvidia Drivers

Source: https://savant-ai.io/docs/latest/_sources/getting_started/0_configure_prod_env.rst.txt

Install the Nvidia proprietary drivers on Ubuntu 22.04. A reboot is required after installation.

```bash
sudo apt install --no-install-recommends nvidia-driver-570 # or a newer version
sudo reboot
```

--------------------------------

### Python Source Usage Example

Source: https://savant-ai.io/docs/latest/_sources/reference/api/client.rst.txt

Demonstrates how to initialize an OTLP tracer, build a source using SourceBuilder, send a JPEG image, and process the results. Ensure the OTLP tracer is also configured in the module.

```python
import time
from savant_rs.telemetry import (
    ContextPropagationFormat,
    Protocol,
    TelemetryConfiguration,
    TracerConfiguration,
)
from savant.client import JaegerLogProvider, JpegSource, SourceBuilder

# Initialize OTLP tracer to send metrics and logs to Jaeger.
# Note: the same OTLP tracer also should be configured in the module.
telemetry_config = TelemetryConfiguration(
    context_propagation_format=ContextPropagationFormat.W3C,
    tracer=TracerConfiguration(
        service_name='savant-client',
        protocol=Protocol.Grpc,
        endpoint='http://jaeger:4317',
        # tls=ClientTlsConfig(
        #     ca='/path/to/ca.crt',
        #     identity=Identity(
        #         certificate='/path/to/client.crt',
        #         key='/path/to/client.key',
        #     ),
        # ),
        # timeout=5000,  # milliseconds
    ),
)
telemetry.init(telemetry_config)
# or 
# use x509 provider config file (take a look at samples/telemetry/otlp/x509_provider_config.json)
# telemetry.init_from_file('/path/to/x509_provider_config.json')


# Build the source
source = (
    SourceBuilder()
    .with_log_provider(JaegerLogProvider('http://localhost:16686'))
    .with_socket('pub+connect:ipc:///tmp/zmq-sockets/input-video.ipc')
    # Note: healthcheck port should be configured in the module.
    .with_module_health_check_url('http://172.17.0.1:8888/status')
    .build()
)

# Send a JPEG image from a file to the module
result = source(JpegSource('cam-1', 'data/AVG-TownCentre.jpeg'))
print(result.status)
time.sleep(1)  # Wait for the module to process the frame
result.logs().pretty_print()

# Shutdown the the tracer
telemetry.shutdown()
```

--------------------------------

### Run FFmpeg Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Use the helper script to run the FFmpeg Source Adapter. This example demonstrates setting custom FFmpeg parameters and specifying a device.

```bash
./scripts/run_source.py ffmpeg --source-id=test --ffmpeg-params=input_format=mjpeg,video_size=1280x720 --device=/dev/video0 /dev/video0
```

--------------------------------

### Pipeline Start Event Handling in Python

Source: https://savant-ai.io/docs/latest/_sources/savant_101/70_python.rst.txt

This method is called once when the pipeline starts. It should return True to allow processing to begin; False or None will prevent the pipeline from starting. Import NvDsPyFuncPlugin.

```python
def on_start(self) -> bool:
    """Do on plugin start."""
    return True
```

--------------------------------

### Install Nvidia Container Toolkit

Source: https://savant-ai.io/docs/latest/_sources/getting_started/0_configure_prod_env.rst.txt

Install the Nvidia Container Toolkit, which allows Docker containers to access Nvidia GPUs. This involves adding the Nvidia Docker repository and installing the toolkit package.

```bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```

--------------------------------

### Async Sink Example

Source: https://savant-ai.io/docs/latest/reference/api/client.html

Example of how to build and use an asynchronous sink to receive results from a module.

```APIDOC
## Async Sink Example

### Description
This example demonstrates building an asynchronous sink to receive and process results from a module.

### Method
`SinkBuilder().with_socket(...).with_idle_timeout(...).with_log_provider(...).build_async()`

### Endpoint
`sub+connect:ipc:///tmp/zmq-sockets/output-video.ipc`

### Parameters
None explicitly documented for the sink builder itself in this snippet.

### Response
#### Success Response (200)
- **result** (object) - Represents the received result from the module.
  - **frame_meta** (object) - Metadata associated with the frame.
  - **logs()** (function) - Returns logs associated with the result, with a `pretty_print()` method.
```

--------------------------------

### Run Video Loop Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Execute the Video Loop Source Adapter using the provided helper script. This is a convenient way to launch the adapter for testing.

```bash
./scripts/run_source.py video-loop --source-id=test /path/to/data/test.mp4
```

--------------------------------

### Adding Object Metadata Example

Source: https://savant-ai.io/docs/latest/_sources/savant_101/75_working_with_metadata.rst.txt

Example demonstrating how to create an `ObjectMeta` instance with a `BBox` and add it to the frame's metadata.

```APIDOC
## Add Object Metadata Example

### Description
This example shows how to create a new object's metadata and add it to the frame.

### Code
```python
from savant_rs.primitives.geometry import BBox
from savant.deepstream.meta.frame import NvDsFrameMeta
from savant.meta.object import ObjectMeta

def process_frame(self, buffer: Gst.Buffer, frame_meta: NvDsFrameMeta):
    new_obj_meta = ObjectMeta(
        element_name='my_element_name',
        label='my_obj_class_label',
        bbox=BBox(
            xc=400,
            yc=300,
            width=200,
            height=100,
        ),
    )
    frame_meta.add_obj_meta(new_obj_meta)
```
```

--------------------------------

### Run Video File Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Execute the Video File Source Adapter using the provided helper script for simpler integration.

```bash
./scripts/run_source.py videos --source-id=test /path/to/data/test.mp4

```

--------------------------------

### Run Image File Sink Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Example command to run the image file sink adapter using the provided helper script.

```bash
./scripts/run_sink.py image-files /path/to/output/%source_id-%src_filename
```

--------------------------------

### Default Ingress Filter Example

Source: https://savant-ai.io/docs/latest/_sources/advanced_topics/3_frame_filtering.rst.txt

The default ingress filter drops frames that do not contain video data. This example is provided for reference.

```python
class DefaultIngressFilter:
    """Default ingress filter that drops frames without video data."""

    def __call__(self, video_frame: VideoFrame) -> bool:
        """Return True if the frame has video data, False otherwise."""
        return video_frame.has_video

```

--------------------------------

### Run Multi-stream Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Execute the Multi-stream Source Adapter using the provided helper script. This simplifies the command-line arguments.

```bash
./scripts/run_source.py multi-stream --source-id-pattern='camera-%d' --number-of-sources=4 --shutdown-auth=shutdown-key /path/to/data/test.mp4

```

--------------------------------

### Create and Start Stream

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Creates a new RTSP stream and starts its operation. If any parameter is not specified, the default value from the adapter parameters will be used.

```APIDOC
## PUT /streams/{source_id}

### Description
Creates a new stream and starts it.

### Method
PUT

### Endpoint
`/streams/{source_id}`

### Parameters
#### Path Parameters
- **source_id** (string) - Required - A source ID for the stream.

#### Request Body
- **stub_file** (string) - Required - Location of a stub image file in JPEG format.
- **framerate** (string) - Required - Frame rate for the output stream (e.g., "30/1").
- **idr_period** (integer) - Required - Period of I-frame insertion.
- **codec** (string) - Required - Encoding codec; one of: `h264`, `hevc`.
- **bitrate** (integer) - Required - Encoding bitrate in bits per second.
- **profile** (string) - Required - Encoding profile. For `h264`: `Baseline`, `Main`, `High`. For `hevc`: `Main`, `Main10`, `FREXT`.
- **max_delay_ms** (integer) - Required - Maximum delay in milliseconds to wait after the last frame received before the stub image is displayed.
- **latency_ms** (integer) - Required - Resulting RTSP stream buffer size in milliseconds.
- **transfer_mode** (string) - Required - How the incoming video stream is mapped to the resulting stream; one of: `scale-to-fit`, `crop-to-fit`.
- **rtsp_keep_alive** (boolean) - Required - Whether to send RTSP keep alive packets.
- **metadata_output** (string) - Required - Where to dump metadata; one of: `stdout`, `logger`.
- **sync_input** (boolean) - Required - Flag indicating whether to show frames on sink synchronously (at the source rate).

### Response
#### Success Response (200)
- **stub_file** (string) - Location of the stub image file.
- **framerate** (string) - Frame rate of the stream.
- **idr_period** (integer) - Period of I-frame insertion.
- **codec** (string) - Encoding codec.
- **bitrate** (integer) - Encoding bitrate.
- **profile** (string) - Encoding profile.
- **max_delay_ms** (integer) - Maximum delay for stub image display.
- **latency_ms** (integer) - RTSP stream buffer size.
- **transfer_mode** (string) - Transfer mode specification.
- **rtsp_keep_alive** (boolean) - RTSP keep alive status.
- **metadata_output** (string) - Metadata output destination.
- **sync_input** (boolean) - Synchronous input flag.
- **status** (object) - Status of the stream:
  - **is_alive** (boolean) - Flag indicating if the stream is alive.
  - **exit_code** (integer) - Exit code of the stream in case of failure.

### Request Example
```json
{
    "stub_file": "/stub_imgs/smpte100_640x360.jpeg",
    "framerate": "30/1",
    "idr_period": 15,
    "codec": "hevc",
    "bitrate": 4000000,
    "profile": "Main",
    "max_delay_ms": 1000,
    "latency_ms": 100,
    "transfer_mode": "scale-to-fit",
    "rtsp_keep_alive": true,
    "metadata_output": "stdout",
    "sync_input": false
}
```

### Response Example
```json
{
  "stub_file": "/stub_imgs/smpte100_640x360.jpeg",
  "framerate": "30/1",
  "idr_period": 15,
  "bitrate": 4000000,
  "profile": "Main",
  "codec": "hevc",
  "max_delay_ms": 1000,
  "latency_ms": 100,
  "transfer_mode": "scale-to-fit",
  "rtsp_keep_alive": true,
  "metadata_output": "stdout",
  "sync_input": false,
  "status": {
    "is_alive": true,
    "exit_code": null
  }
}
```
```

--------------------------------

### Run Buffer Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Execute the buffer adapter using the provided helper script, specifying the mount path for the buffer.

```bash
./scripts/run_bridge.py buffer --mount-buffer-path /tmp/savant/buffer
```

--------------------------------

### TCP Socket Communication Example

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Example of configuring a TCP socket endpoint for ZeroMQ communication. This is used for network-based communication between different machines.

```bash
# tcp socket communication
ZMQ_ENDPOINT="pub+bind:tcp://1.1.1.1:3333"
```

--------------------------------

### Create RTSP Stream with Minimal Configuration

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

This example shows how to create an RTSP stream using only the required parameters, relying on adapter defaults for other settings. The response includes the stream's status.

```bash
curl -X PUT 'http://localhost:13000/streams/test2' \
    -H 'Content-Type: application/json' \
    -d '{}'
```

```json
{
  "stub_file": "/stub_imgs/smpte100_1280x720.jpeg",
  "framerate": "20/1",
  "idr_period": 20,
  "bitrate": 4000000,
  "profile": "High",
  "codec": "h264",
  "max_delay_ms": 1000,
  "latency_ms": 100,
  "transfer_mode": "scale-to-fit",
  "rtsp_keep_alive": true,
  "metadata_output": null,
  "sync_input": false,
  "status": {
    "is_alive": true,
    "exit_code": null
  }
}
```

--------------------------------

### Async Source and Sink Example

Source: https://savant-ai.io/docs/latest/reference/api/client.html

Demonstrates building and running an asynchronous source to send JPEG images and an asynchronous sink to receive results, including telemetry integration with Jaeger.

```python
import asyncio
from savant_rs.telemetry import (
    ContextPropagationFormat,
    Protocol,
    TelemetryConfiguration,
    TracerConfiguration,
)
from savant.client import JaegerLogProvider, JpegSource, SinkBuilder, SourceBuilder


async def run_source():
    # Build the source
    source = (
        SourceBuilder()
        .with_log_provider(JaegerLogProvider('http://localhost:16686'))
        .with_socket('pub+connect:ipc:///tmp/zmq-sockets/input-video.ipc')
        .build_async()
    )

    # Send a JPEG image from a file to the module
    result = await source(JpegSource('cam-1', 'data/AVG-TownCentre.jpeg'))
    print(result.status)


async def run_sink():
    # Build the sink
    sink = (
        SinkBuilder()
        .with_socket('sub+connect:ipc:///tmp/zmq-sockets/output-video.ipc')
        .with_idle_timeout(60)
        .with_log_provider(JaegerLogProvider('http://localhost:16686'))
        .build_async()
    )

    # Receive results from the module and print them
    async for result in sink:
        print(result.frame_meta)
        result.logs().pretty_print()


async def main():
    # Initialize the OTLP tracer to send metrics and logs to Jaeger.
    # Note: the Jaeger tracer also should be configured in the module.
    telemetry_config = TelemetryConfiguration(
        context_propagation_format=ContextPropagationFormat.W3C,
        tracer=TracerConfiguration(
            service_name='savant-client',
            protocol=Protocol.Grpc,
            endpoint='http://jaeger:4317',
            # tls=ClientTlsConfig(
            #     ca='/path/to/ca.crt',
            #     identity=Identity(
            #         certificate='/path/to/client.crt',
            #         key='/path/to/client.key',
            #     ),
            # ),
            # timeout=5000,  # milliseconds
        ),
    )
    telemetry.init(telemetry_config)
    # or
    # use x509 provider config file (take a look at samples/telemetry/otlp/x509_provider_config.json)
    # telemetry.init_from_file('/path/to/x509_provider_config.json')

    await asyncio.gather(run_sink(), run_source())

    # Shutdown the Jaeger tracer
    telemetry.shutdown()


asyncio.run(main())
```

--------------------------------

### Run Metadata JSON Sink Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Example command to run the metadata JSON sink adapter using the provided helper script.

```bash
./scripts/run_sink.py meta-json /path/to/output/%source_id-%src_filename
```

--------------------------------

### Run Image Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Execute the image source adapter using the provided helper script. This simplifies the command-line execution.

```bash
./scripts/run_source.py images --source-id=test /path/to/images
```

--------------------------------

### Update Packages and Install Basic Tools

Source: https://savant-ai.io/docs/latest/_sources/getting_started/0_configure_prod_env.rst.txt

Update the package list and install essential tools like git, git-lfs, and curl on Ubuntu 22.04.

```bash
sudo apt-get update
sudo apt-get install -y git git-lfs curl -y
```

--------------------------------

### Run Image File Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

This command shows how to launch the Image File Source Adapter using the provided helper script. It specifies the source type, an ID, and the directory containing the images.

```bash
./scripts/run_source.py images --source-id=test /path/to/images

```

--------------------------------

### IPC Socket Communication Example

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Example of configuring an IPC (Inter-Process Communication) socket endpoint for ZeroMQ. This is typically used for communication between processes on the same machine.

```bash
ZMQ_ENDPOINT="dealer+connect:ipc:///tmp/zmq-sockets/input-video.ipc"
```

--------------------------------

### Run Display Sink Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Use this helper script to run the Display Sink adapter. This is a simplified alternative to the Docker command.

```bash
./scripts/run_sink.py display
```

--------------------------------

### PyFunc Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.base.pyfunc.PyFunc.html

This is an example of how to define a PyFunc in a module configuration. Ensure the specified module and class_name exist and inherit from the appropriate base class.

```yaml
- element: pyfunc
  module: module.pyfunc_implementation_module
  class_name: PyFuncImplementationClass

```

--------------------------------

### Telemetry Initialization

Source: https://savant-ai.io/docs/latest/_sources/reference/api/client.rst.txt

Demonstrates how to initialize telemetry with either direct configuration or from a file, and how to shut it down.

```APIDOC
## Telemetry Initialization

### Description
Initialize and shut down telemetry for the Savant client.

### Usage
```python
import asyncio
from savant.config import settings
from savant.deepstream.client import SinkBuilder, SourceBuilder
from savant.utils import logging
from savant.utils.telemetry import telemetry


async def run_sink():
    # Placeholder for sink logic
    pass

async def run_source():
    # Placeholder for source logic
    pass

async def main():
    # Example using direct configuration
    # telemetry_config = telemetry.TelemetryConfig(
    #     tracing_enabled=True,
    #     tracing_backend=telemetry.TracingBackend.JAEGER,
    #     tracing_endpoint="http://localhost:14268/api/traces",
    #     logs_enabled=True,
    #     logs_backend=telemetry.LogsBackend.FILE,
    #     logs_file="/tmp/savant.log",
    #     metrics_enabled=True,
    #     metrics_backend=telemetry.MetricsBackend.PROMETHEUS,
    #     metrics_endpoint="/metrics",
    #     # Example with TLS configuration
    #     # tls_config=telemetry.ClientTLSConfig(
    #     #     cert='/path/to/client.crt',
    #     #     key='/path/to/client.key',
    #     # ),
    #     # timeout=5000,  # milliseconds
    # )
    # telemetry.init(telemetry_config)

    # Example using a configuration file
    telemetry.init_from_file('/path/to/x509_provider_config.json')

    await asyncio.gather(run_sink(), run_source())

    # Shutdown the Jaeger tracer
    telemetry.shutdown()


asyncio.run(main())
```

### Parameters
* `telemetry_config` (TelemetryConfig): Configuration object for telemetry.
* `config_path` (str): Path to the telemetry configuration file.
```

--------------------------------

### Pipeline Start Event Handling

Source: https://savant-ai.io/docs/latest/savant_101/70_python.html

Override the on_start method to execute code once when the pipeline begins processing. Returning False or None will prevent the pipeline from starting.

```python
def on_start(self) -> bool:
    """Do on plugin start."""
    return True

```

--------------------------------

### Run Video File Source Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Use this command to run the video file source adapter with the helper script. It takes the source type, ID, and file path as arguments.

```bash
./scripts/run_source.py videos --source-id=test /path/to/data/test.mp4
```

--------------------------------

### AttributeModelOutput Configuration Example

Source: https://savant-ai.io/docs/latest/reference/api/generated/savant.base.model.AttributeModelOutput.html

This example demonstrates how to configure the output of a model using AttributeModelOutput in a module configuration file. It specifies the output layer and defines attributes with their names and thresholds.

```yaml
model:
    # model configuration
    output:
        layer_names: [output]
        attributes:
            - name: cat_or_dog
              threshold: 0.5

```

--------------------------------

### Run GigE Camera Adapter with Docker

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Launches the GigE camera source adapter using Docker. Ensure the ZMQ endpoint and camera name are correctly configured.

```bash
docker run --rm -it --name source-gige-test \
    --entrypoint /opt/savant/adapters/gst/sources/gige_cam.sh \
    -e ZMQ_ENDPOINT=dealer+connect:ipc:///tmp/zmq-sockets/input-video.ipc \
    -e SOURCE_ID=test \
    -e CAMERA_NAME=test-camera \
    -v /tmp/zmq-sockets:/tmp/zmq-sockets \
    ghcr.io/insight-platform/savant-adapters-gstreamer:latest
```

--------------------------------

### Basic Thread Execution in Python

Source: https://savant-ai.io/docs/latest/_sources/recipes/1_python_multithreading.rst.txt

Demonstrates how to create and start a simple thread in Python. Ensure the target function is defined before creating the thread.

```python
import threading

def worker(num):
    """Thread worker function"""
    print('Worker: %s' % num)
    return

threads = []
for i in range(5):
    t = threading.Thread(target=worker, args=(i,))
    threads.append(t)
    t.start()

for t in threads:
    t.join()

print("All threads finished.")
```

--------------------------------

### Example: Conditionally Remove Primary Object Metadata

Source: https://savant-ai.io/docs/latest/_sources/savant_101/75_working_with_metadata.rst.txt

This example demonstrates how to find and remove the primary object's metadata from a frame based on a condition, effectively disabling further processing for that object.

```python
def process_frame(self, buffer: Gst.Buffer, frame_meta: NvDsFrameMeta):
        primary_meta_object = None
        for obj_meta in frame_meta.objects:
            if obj_meta.is_primary:
                primary_meta_object = obj_meta
                break
        condition = True

        if condition and primary_meta_object:
            frame_meta.remove_obj_meta(primary_meta_object)
```

--------------------------------

### Run GigE Camera Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Executes the GigE camera source adapter using the provided helper script. This simplifies the command-line execution.

```bash
./scripts/run_source.py gige --source-id=test test-camera
```

--------------------------------

### Start Kinesis Video Stream Playback via REST API

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Send a PUT request to the /stream/play endpoint to start playing the Kinesis Video Stream. This action does not require a request body.

```bash
curl -X PUT 'http://localhost:18367/stream/play'

```

--------------------------------

### Run Buffer Bridge Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Execute the Buffer Bridge Adapter using the provided helper script. This simplifies the command-line execution and allows for mounting the buffer path.

```bash
./scripts/run_bridge.py buffer --mount-buffer-path /tmp/savant/buffer

```

--------------------------------

### Example: Reading Object Attributes

Source: https://savant-ai.io/docs/latest/_sources/savant_101/75_working_with_metadata.rst.txt

This example shows how to iterate through frame objects and retrieve specific attributes, such as 'car_color', created by a classifier named 'Secondary_CarColor'. The attribute value can be accessed via `attr_meta.value`.

```python
for obj_meta in frame_meta.objects:
        attr_meta = obj_meta.get_attr_meta('Secondary_CarColor', 'car_color')
        if attr_meta is not None:
            # use attr_meta.value to get attribute value
```

--------------------------------

### Run USB Cam Source with Helper Script

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Utilize the provided helper script to launch the FFmpeg source adapter for USB cameras. This simplifies the command-line execution with predefined arguments.

```bash
./scripts/run_source.py ffmpeg --source-id=test --ffmpeg-params=input_format=mjpeg,video_size=1920x1080 --device=/dev/video0 /dev/video0

```

--------------------------------

### Run Message Dump Player Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Launch the Message Dump Player Adapter using the provided helper script, specifying the playlist path and dump files directory.

```bash
./scripts/run_source.py mdp --playlist /path/to/playlist/file.txt --dump-files-dir /path/to/dump/files
```

--------------------------------

### Run Display Sink Adapter with Docker

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

This Docker command launches the Display Sink adapter. It requires X server access and specific environment variables for display and Xauthority.

```bash
docker run --rm -it --name sink-display \
    --entrypoint /opt/savant/adapters/ds/sinks/display.sh \
    -e SYNC_INPUT=False \
    -e ZMQ_ENDPOINT=sub+connect:ipc:///tmp/zmq-sockets/output-video.ipc \
    -e DISPLAY \
    -e XAUTHORITY=/tmp/.docker.xauth \
    -e CLOSING_DELAY=0 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v /tmp/.docker.xauth:/tmp/.docker.xauth \
    -v /tmp/zmq-sockets:/tmp/zmq-sockets \
    --gpus=all \
    ghcr.io/insight-platform/savant-adapters-deepstream:latest
```

--------------------------------

### Start Playing Stream

Source: https://savant-ai.io/docs/latest/_sources/savant_101/10_adapters.rst.txt

Initiates playback of the stream.

```APIDOC
## PUT /stream/play

### Description
Starts playing the stream.

### Method
PUT

### Endpoint
/stream/play

### Response
#### Success Response (200)
- **name** (string) - The name of the stream.
- **source_id** (string) - The ID of the source.
- **timestamp** (string) - The timestamp of the stream data.
- **is_playing** (bool) - A flag specifying if the stream should start playing immediately.

#### Response Example
```json
{
  "name": "test-stream",
  "source_id": "test",
  "timestamp": "2024-03-12T06:57:00",
  "is_playing": true
}
```
```

--------------------------------

### Run Video File Sink Adapter with Helper Script

Source: https://savant-ai.io/docs/latest/savant_101/10_adapters.html

Invoke the video file sink adapter using the helper script. Provide the adapter name and the desired output path.

```bash
./scripts/run_sink.py video-files /path/to/output/%source_id-%src_filename

```
Tokens:
Raw