### Install Docker

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/getting_started/0_configure_prod_env.rst

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

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

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

### Run Router Demo Pipeline

Source: https://github.com/insight-platform/savant/blob/develop/samples/router/README.md

Execute the Docker Compose file to start the pipeline. Ensure Docker is installed and running.

```bash
docker compose -f samples/router/docker-compose.yml up
```

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

### Source Usage Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/client.rst

This example demonstrates how to initialize telemetry, build a source using SourceBuilder, send a JPEG image to a module, and process the results.

```APIDOC
## Source Usage Example

### Description
This example demonstrates how to initialize telemetry, build a source using `SourceBuilder`, send a JPEG image to a module, and process the results.

### Code
```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()
```
```

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

### Async Example (Source and Sink)

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/client.rst

This example shows how to use the Client SDK asynchronously for both source and sink operations, including telemetry initialization and building async source/sink objects.

```APIDOC
## Async Example (Source and Sink)

### Description
This example shows how to use the Client SDK asynchronously for both source and sink operations, including telemetry initialization and building async source/sink objects.

### Code
```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(
```
```

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

### Download Example Model Archive

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/27_working_with_models.rst

Use this command to download a sample model archive for the Nvidia car classification example. Ensure you have the 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 .
```

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

### Async Source and Sink Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/client.rst

Provides an asynchronous example for both source and sink operations. It shows how to build and use async versions of the source and sink, send a JPEG image, and receive/print results. Includes tracer initialization.

```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(

```

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

### Run Key-Value API Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/key_value_api/README.md

Use this command to start the Key-Value API demo on x86 platforms using Docker Compose.

```bash
# if x86
docker compose -f samples/key_value_api/docker-compose.x86.yml up
```

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

### Run Watchdog Sample on x86

Source: https://github.com/insight-platform/savant/blob/develop/services/watchdog/README.md

Command to start the watchdog service with a sample configuration on an x86 architecture using Docker Compose.

```bash
docker compose -f samples/pipeline_watchdog/docker-compose.x86.yml up --build -d
```

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

### Sink Usage Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/client.rst

This example demonstrates how to build a sink using SinkBuilder, connect to a module's output socket, and receive and process results.

```APIDOC
## Sink Usage Example

### Description
This example demonstrates how to build a sink using `SinkBuilder`, connect to a module's output socket, and receive and process results.

### Code
```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()
)

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

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

### Run FFmpeg Source with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Utilize the helper script to run the FFmpeg Source adapter. This example demonstrates passing 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
```

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

### Configure and Start a Stream

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Use this command to configure a new stream with specified parameters, including credentials and playback state. The response body mirrors the request.

```bash
curl -X PUT 'http://localhost:18367/stream' \
    -H "Content-Type: application/json" \
    -d '{
        "name": "test-stream",
        "source_id": "test",
        "timestamp": "2024-03-12T06:57:00",
        "credentials": {
            "region": "us-west-2",
            "access_key": "AKIAIOSFODNN7EXAMPLE",
            "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
        },
        "is_playing": true
    }'
```

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

### Container Matching Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/3_pipeline_idle_monitor.rst

This example shows how to specify labels for matching containers. The action applies to services with all specified labels in a single entry, or any of the entries if multiple label entries are provided.

```yaml
container:
   - labels: [label=1, label2]
   - labels: label3
```

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

### Run Image Files Sink with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

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

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

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

### Run Metadata JSON Sink with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

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 KVS Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/aws_kinesis/README.md

Starts the Kinesis Video Stream demo on x86 architecture using Docker Compose. Ensure AWS credentials are set in the .env file. Wait for the kvs-sink to start sending frames before sending the 'play' command.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/aws_kinesis/docker-compose.x86.yml up --build
```

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

### Run Demo on x86

Source: https://github.com/insight-platform/savant/blob/develop/samples/peoplenet_detector/README.md

Start the PeopleNet detector demo using Docker Compose for x86 architecture. Access the stream via RTSP or LL-HLS.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/peoplenet_detector/docker-compose.x86.yml up

# open 'rtsp://127.0.0.1:554/stream/city-traffic' in your player
# or visit 'http://127.0.0.1:888/stream/city-traffic/' (LL-HLS)

# Ctrl+C to stop running the compose bundle
```

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

### File Naming Convention Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/9_input_json_metadata.rst

Illustrates the required file naming convention for JSON metadata and its corresponding media file.

```text
./input_data/0000000000000785.json
./input_data/0000000000000785.jpg
```

```text
./input_data/street_people.json
./input_data/street_people.mp4
```

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

### Getting Attribute Metadata Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/75_working_with_metadata.rst

Example showing how to retrieve attribute metadata for an object, such as car color.

```APIDOC
## Get Attribute Metadata Example

### Description
This example iterates through objects in frame metadata and retrieves a specific attribute.

### Code Example
```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
        pass
```
```

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

### Initialize and Use a Source

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/client.rst

Demonstrates initializing an OTLP tracer for metrics and logs, building a source with specific configurations, sending a JPEG image, and shutting down the tracer. 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()
```

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

### Access Demo Stream

Source: https://github.com/insight-platform/savant/blob/develop/samples/area_object_counting/README.md

After starting the demo, access the video stream via RTSP or LL-HLS. Use Ctrl+C to stop the Docker Compose services.

```bash
# open 'rtsp://127.0.0.1:554/stream/town-centre' in your player
# or visit 'http://127.0.0.1:888/stream/town-centre/' (LL-HLS)

# Ctrl+C to stop running the compose bundle
```

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

### H.264 Encoder Configuration Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/12_video_processing.rst

Configure H.264 encoding parameters, including bitrate and profile. Run `gst-inspect-1.0 nvv4l2h264enc` to list all available properties.

```yaml
parameters:
  output_frame:
    codec: h264
    encoder_params:
      bitrate: 4000000
      profile: 4
```

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

### Run Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/face_reid/README.md

Launch the demo module using Docker Compose for x86 architecture. Access the video stream via RTSP or LL-HLS.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/face_reid/docker-compose.x86.yml --profile demo up

# open 'rtsp://127.0.0.1:554/stream/video' in your player
# or visit 'http://127.0.0.1:888/stream/video/' (LL-HLS)

# Ctrl+C to stop running the compose bundle
```

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

### Build Module Engines with run_module.py

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/27_working_with_models.rst

This script command builds TensorRT engines for a specific module configuration, useful for examples or custom module setups.

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

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

### Run Original Resolution Processing Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/original_resolution_processing/README.md

Launches the demo using Docker Compose for x86 platforms. Access streams via RTSP or LL-HLS. Stop with Ctrl+C.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/original_resolution_processing/docker-compose.x86.yml up
```

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

### Install Nvidia Drivers

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/getting_started/0_configure_prod_env.rst

Install the specified version of Nvidia drivers on Ubuntu. A reboot is required after installation.

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

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

### Install Nvidia Container Toolkit

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/getting_started/0_configure_prod_env.rst

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
```

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

### Adding Object Metadata Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/75_working_with_metadata.rst

Example demonstrating how to create and add a new object's metadata to a frame.

```APIDOC
## Add Object Metadata Example

### Description
This example shows how to create a new `ObjectMeta` instance with a `BBox` and add it to the `NvDsFrameMeta`.

### Code Example
```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 Keypoint Detection Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/keypoint_detection/README.md

Launches the keypoint detection demo on an x86 system using Docker Compose. Access the stream via RTSP or LL-HLS.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/keypoint_detection/docker-compose.x86.yml up
```

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

### Default Ingress Filter Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/3_frame_filtering.rst

The default ingress filter drops frames that do not contain video data. This is an example implementation.

```python
class DefaultIngressFilter:
    def __init__(self, **kwargs):
        pass

    def __call__(self, video_frame: VideoFrame) -> bool:
        return video_frame.has_video

```

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

### JSON Object Metadata Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/9_input_json_metadata.rst

Provides an example of how to structure metadata for a single detected object, including its bounding box and confidence.

```json
{
        "model_name": "coco",
        "label": "person",
        "object_id": 1,
        "bbox":
        {
            "xc": 390.14,
            "yc": 218.07,
            "width": 218.7,
            "height": 346.68,
            "angle": 0.0
        },
        "confidence": 1,
        "attributes": [],
        "parent_model_name": null,
        "parent_label": null,
        "parent_object_id": null
    }
```

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

### Access Demo Streams and Metrics

Source: https://github.com/insight-platform/savant/blob/develop/samples/buffer_adapter/README.md

Instructions for accessing the demo video stream via RTSP or LL-HLS, and viewing the adapter metrics in Grafana and Prometheus.

```bash
# open 'rtsp://127.0.0.1:554/stream/city-traffic' in your player
# or visit 'http://127.0.0.1:888/stream/city-traffic/' (LL-HLS)

# for pre-configured Grafana dashboard visit
# http://127.0.0.1:3000/d/89571523-ad22-4df2-bb09-df20b18bd5ee/buffer-metrics?orgId=1&refresh=5s

# for the buffer adapter metrics visit
# http://127.0.0.1:8080/metrics


# Ctrl+C to stop running the compose bundle
```

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

### Stream Control API - Create and Start a Stream

Source: https://github.com/insight-platform/savant/blob/develop/samples/multiple_gige/README.md

Create and start a new stream with specified configuration parameters for the Always-On-RTSP sink.

```APIDOC
## Create and start a stream

```bash
curl -X PUT \
    -H 'Content-Type: application/json' \
    -d '{"stub_file":"/stub_imgs/smpte100_1280x720.jpeg","framerate":"20/1","bitrate":4000000,"profile":"High","codec":"h264","max_delay_ms":1000,"latency_ms":null,"transfer_mode":"scale-to-fit","rtsp_keep_alive":true,"metadata_output":null,"sync_input":false}' \
    'http://localhost:13000/streams/gige-raw'
```
```

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

### Run Demo (Jetson)

Source: https://github.com/insight-platform/savant/blob/develop/samples/face_reid/README.md

Launch the demo module using Docker Compose for Jetson platform. Access the video stream via RTSP or LL-HLS.

```bash
# you are expected to be in Savant/ directory

# if Jetson
docker compose -f samples/face_reid/docker-compose.l4t.yml --profile demo up

# open 'rtsp://127.0.0.1:554/stream/video' in your player
# or visit 'http://127.0.0.1:888/stream/video/' (LL-HLS)

# Ctrl+C to stop running the compose bundle
```

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

### Update Packages and Install Basic Tools

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/getting_started/0_configure_prod_env.rst

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

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

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

### Run Original Resolution Processing Demo (Jetson)

Source: https://github.com/insight-platform/savant/blob/develop/samples/original_resolution_processing/README.md

Launches the demo using Docker Compose for Jetson platforms. Access streams via RTSP or LL-HLS. Stop with Ctrl+C.

```bash
# you are expected to be in Savant/ directory

# if Jetson
docker compose -f samples/original_resolution_processing/docker-compose.l4t.yml up
```

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

### Pipeline Start Event Handling

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/70_python.rst

This method is called once when the pipeline begins processing data. Returning False or None will prevent the pipeline from starting.

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

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

### Install pycocotools for Data Preparation

Source: https://github.com/insight-platform/savant/blob/develop/samples/source_adapter_with_json_metadata/README.md

Installs the pycocotools library, which is required for running the convert_coco_to_savant.py script to prepare input metadata from COCO dataset annotations.

```bash
pip install pycocotools
```

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

### Run Display Sink Adapter with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Use this command to run the display sink adapter via the helper script. This is a simplified way to start the adapter.

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

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

### Start module container with Docker Compose

Source: https://github.com/insight-platform/savant/blob/develop/samples/template/README.md

Launch the Savant module container using Docker Compose. This command starts the main processing unit of the module.

```bash
docker compose -f docker-compose.x86.yml up module -d
```

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

### Download Demo Video

Source: https://github.com/insight-platform/savant/blob/develop/samples/peoplenet_detector/README.md

Download a sample video file to the 'data' directory for performance testing. Ensure the video is placed in the correct location for the performance script.

```bash
# you are expected to be in Savant/ directory

mkdir -p data && curl -o data/Free_City_Street_Footage.mp4 \
   https://eu-central-1.linodeobjects.com/savant-data/demo/Free_City_Street_Footage.mp4
```

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

### Example: Remove Primary Object Metadata

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/75_working_with_metadata.rst

This example demonstrates how to 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 Multi-stream Source Adapter with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Executes the multi-stream source adapter using the helper script, specifying the source pattern, number of sources, shutdown authentication, and the video file location.

```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
```

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

### Example: Add New Object Metadata to Frame

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/75_working_with_metadata.rst

This example shows how to create a new `ObjectMeta` instance with a bounding box and add it to the frame's metadata using `add_obj_meta`.

```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 Buffer Adapter Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/buffer_adapter/README.md

Execute the Docker Compose command to run the buffer adapter demo on an x86 platform. Ensure you are in the Savant directory.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/buffer_adapter/docker-compose.x86.yml up
```

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

### Run Kafka Source Adapter with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Launch the Kafka source adapter using the provided helper script. Specify Kafka broker and topic details.

```bash
./scripts/run_source.py kafka-redis --brokers=kafka:9092 --topic=kafka-redis-adapter-demo --group-id=kafka-redis-adapter-demo
```

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

### Docker Compose Healthcheck Condition

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/introduction/2_running.rst

Specifies a healthcheck condition in docker-compose to ensure a service is healthy before starting dependent services. Use this to start source adapters only when the module is ready.

```yaml
depends_on:
  module:
    condition: service_healthy
```

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

### HTTP GET Request to Get Attribute by Exact Match

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/15_embedded_kvs.rst

Retrieves the attribute value for a key specified by exact namespace and name. The response is a serialized AttributeSet protobuf message.

```http
GET /kvs/get/(str: namespace)/(str: name) HTTP/1.1
Host: example.com
```

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

### Run Multi-stream Source Adapter with Docker

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Launches the multi-stream source adapter with Docker, configuring synchronous output, ZMQ endpoint, stream pattern, number of streams, shutdown authentication, location, and download path. Mounts volumes for ZMQ sockets, video file, and downloads.

```bash
docker run --rm -it --name source-multi-stream-test \
    --entrypoint /opt/savant/adapters/gst/sources/multi_stream.sh \
    -e SYNC_OUTPUT=True \
    -e ZMQ_ENDPOINT=dealer+connect:ipc:///tmp/zmq-sockets/input-video.ipc \
    -e SOURCE_ID_PATTERN='camera-%d' \
    -e NUMBER_OF_STREAMS=4 \
    -e SHUTDOWN_AUTH=shutdown-key \
    -e LOCATION=/path/to/data/test.mp4 \
    -e DOWNLOAD_PATH=/tmp/video-loop-source-downloads \
    -v /path/to/data/test.mp4:/path/to/data/test.mp4:ro \
    -v /tmp/zmq-sockets:/tmp/zmq-sockets \
    -v /tmp/video-loop-source-downloads:/tmp/video-loop-source-downloads \
    ghcr.io/insight-platform/savant-adapters-gstreamer:latest
```

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

### Run Source Shaper Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/source_shaper_sample/README.md

Execute the Docker Compose bundle for the source shaper sample on an x86 architecture. Access the streams via RTSP or LL-HLS after starting.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/source_shaper_sample/docker-compose.x86.yml up
```

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

### Python Input Preprocessing Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/30_dm.rst

An example Python class implementing custom object metadata preprocessing. This code defines the logic for preparing object data before it is passed to the inference model.

```Python
import savant.base.input_preproc


class TopCrop(savant.base.input_preproc.BasePreprocessObjectMeta):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

    def __call__(self, obj_meta, frame_meta):
        return obj_meta
```

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

### Telemetry Initialization

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/client.rst

Demonstrates how to initialize telemetry using either direct configuration or a configuration file.

```APIDOC
## Telemetry Initialization

### Description
Initializes the telemetry system with either a direct configuration object or by loading configuration from a file.

### Usage
```python
import asyncio
from savant.api import telemetry

async def main():
    # Option 1: Direct configuration
    # telemetry_config = {
    #     "tracing_exporter": {
    #         "type": "jaeger",
    #         "endpoint": "http://localhost:14268/api/traces",
    #         "service_name": "my-service",
    #         "agent_host_name": "localhost",
    #         "agent_port": 6831,
    #         "collector_endpoint": "http://localhost:4318/v1/traces",
    #         "protocol": "grpc",
    #         "tls_config": {
    #             "cert_file": "/path/to/client.crt",
    #             "key_file": "/path/to/client.key",
    #         },
    #     },
    #     "timeout": 5000,  # milliseconds
    # }
    # telemetry.init(telemetry_config)

    # Option 2: Use x509 provider config file
    telemetry.init_from_file('/path/to/x509_provider_config.json')

    # ... rest of your application logic ...
    await asyncio.gather(run_sink(), run_source())

    # Shutdown the Jaeger tracer
    telemetry.shutdown()

asyncio.run(main())
```

### Notes
- The `timeout` is specified in milliseconds.
- Ensure the configuration file path is correct when using `init_from_file`.
```

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

### Savant Module Docker Compose Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/introduction/2_running.rst

Example docker-compose.yml file for running a Savant module with source and sink adapters. This configuration defines services for the module, video input, and output.

```yaml
services:
  module:
    image: ${SAVANT_IMAGE:-ghcr.io/insight-platform/savant-rs:latest}
    build:
      context: ../../
      dockerfile: Dockerfile
    ports:
      - "5000:5000"
    volumes:
      - "${PWD}/config:/opt/savant/config"
      - "${PWD}/models:/opt/savant/models"
    environment:
      - DEEPSTREAM_APP_LIB=/opt/savant/lib/libnvds_savant.so
      - WEBSERVER_PORT=8080
      - LOG_LEVEL=info
    networks:
      - savant_network

  video-loop-source:
    image: ${SAVANT_EXAMPLES_IMAGE:-ghcr.io/insight-platform/savant-examples:latest}
    command: |
      python3 -m savant.deepstream.examples.video_loop_source
        --input-path /opt/savant/samples/streams/sample_720p.h264
        --output-path rtsp://127.0.0.1:8554/test
    ports:
      - "8554:8554"
    volumes:
      - "${PWD}/samples:/opt/savant/samples"
    networks:
      - savant_network
    depends_on:
      module:
        condition: service_healthy

  always-on-sink:
    image: ${SAVANT_EXAMPLES_IMAGE:-ghcr.io/insight-platform/savant-examples:latest}
    command: |
      python3 -m savant.deepstream.examples.always_on_sink
        --input-path rtsp://127.0.0.1:8554/test
        --output-path hls://127.0.0.1:8080/stream/output.m3u8
    ports:
      - "8080:8080"
    networks:
      - savant_network
    depends_on:
      module:
        condition: service_healthy

networks:
  savant_network:
    driver: bridge

```

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

### Run Bypass Model Demo (Docker Compose)

Source: https://github.com/insight-platform/savant/blob/develop/samples/bypass_model/README.md

Start the demo using Docker Compose. Choose the appropriate command based on your system architecture (x86 or Jetson).

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/bypass_model/docker-compose.x86.yml up -d

# if Jetson
docker compose -f samples/bypass_model/docker-compose.l4t.yml up -d
```

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

### Create and Start a Stream

Source: https://github.com/insight-platform/savant/blob/develop/samples/multiple_gige/README.md

Use curl with a PUT request to create and start a new stream on the Always-On-RTSP sink. Configure stream parameters such as stub file, framerate, bitrate, codec, and transfer mode in the JSON payload.

```bash
curl -X PUT \
    -H 'Content-Type: application/json' \
    -d '{"stub_file":"/stub_imgs/smpte100_1280x720.jpeg","framerate":"20/1","bitrate":4000000,"profile":"High","codec":"h264","max_delay_ms":1000,"latency_ms":null,"transfer_mode":"scale-to-fit","rtsp_keep_alive":true,"metadata_output":null,"sync_input":false}' \
    'http://localhost:13000/streams/gige-raw'
```

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

### Run Video Loop Source with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Execute the Video Loop Source adapter using the provided helper script. This simplifies the command-line execution.

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

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

### Start Receiving Frames from KVS

Source: https://github.com/insight-platform/savant/blob/develop/samples/aws_kinesis/README.md

Sends a 'play' command to the kvs-source after the kvs-sink has started, initiating the reception of frames from Kinesis Video Stream. This command is typically sent after observing the 'Creating Kinesis Video Client' message in the kvs-sink logs.

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

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

### Run Pass-through Processing Demo (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/pass_through_processing/README.md

Launches the pass-through processing demo using Docker Compose for x86 architecture. Ensure you are in the Savant directory.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/pass_through_processing/docker-compose.x86.yml up
```

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

### Run KVS Demo (Jetson)

Source: https://github.com/insight-platform/savant/blob/develop/samples/aws_kinesis/README.md

Starts the Kinesis Video Stream demo on Jetson devices using Docker Compose. Ensure AWS credentials are set in the .env file. Wait for the kvs-sink to start sending frames before sending the 'play' command.

```bash
# you are expected to be in Savant/ directory

# if Jetson
docker compose -f samples/aws_kinesis/docker-compose.l4t.yml up --build
```

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

### Download Video for Performance Measurement

Source: https://github.com/insight-platform/savant/blob/develop/samples/intersection_traffic_meter/README.md

Download a sample video file to the 'data' directory for performance benchmarking.

```bash
# you are expected to be in Savant/ directory

mkdir -p data
curl -o data/leeds_1080p.mp4 https://eu-central-1.linodeobjects.com/savant-data/demo/leeds_1080p.mp4
```

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

### Get Stream Configuration

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Retrieves the configuration details for a specific video stream.

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

### Description
Get configuration of a stream.

### Method
GET

### Endpoint
/streams/{source_id}

### Parameters
#### Path Parameters
- **source_id** (string) - Required - a source ID.

#### Query Parameters
- **format** (string) - Optional - a response format; one of: json, yaml; the default value is json.

### Response
#### Success Response (200)
- **stub_file** (string) - Description of stub file.
- **framerate** (string) - Description of framerate.
- **idr_period** (integer) - Description of IDR period.
- **bitrate** (integer) - Description of bitrate.
- **profile** (string) - Description of profile.
- **codec** (string) - Description of codec.
- **max_delay_ms** (integer) - Description of max delay in milliseconds.
- **latency_ms** (integer) - Description of latency in milliseconds.
- **transfer_mode** (string) - Description of transfer mode.
- **rtsp_keep_alive** (boolean) - Description of RTSP keep alive setting.
- **metadata_output** (string) - Description of metadata output.
- **sync_input** (boolean) - Description of sync input setting.
- **status** (object) - Description of status.
  - **is_alive** (boolean) - Indicates if the stream is alive.
  - **exit_code** (integer) - The exit code of the stream process.

### Request Example
```bash
curl 'http://localhost:13000/streams/test?format=json'
```

### Response Example
```json
{
  "stub_file": "/stub_imgs/smpte100_640x360.jpeg",
  "framerate": "30/1",
  "idr_period": 30,
  "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 Video File Source Adapter with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Use this command to run the video file source adapter with the helper script. Specify the source ID and the path to your video file.

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

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

### Start Playing a Stream

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Initiate playback for the current stream. This command does not require a request body.

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

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

### Run Demo Pipeline (x86)

Source: https://github.com/insight-platform/savant/blob/develop/samples/source_adapter_with_json_metadata/README.md

Launches the demo pipeline using Docker Compose for x86 architecture. The source adapter will terminate after processing all images, while other modules need manual stopping.

```bash
# you are expected to be in Savant/ directory

# if x86
docker compose -f samples/source_adapter_with_json_metadata/docker-compose.x86.yml up
```

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

### Run Buffer Adapter with Helper Script

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/savant_101/10_adapters.rst

Execute the buffer adapter using the provided helper script. This is an alternative to direct Docker execution.

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

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

### GstBuffer Get Savant Frame Meta

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/reference/api/libs.rst

Retrieves Savant frame metadata from a GStreamer buffer.

```APIDOC
## gst_buffer_get_savant_frame_meta

### Description
Retrieves Savant frame metadata from a GStreamer buffer.

### Function Signature
`gst_buffer_get_savant_frame_meta(buffer)`

### Parameters
- `buffer` (Gst.Buffer): The GStreamer buffer from which to retrieve metadata.

### Returns
- `object`: The Savant frame metadata, or None if not found.
```

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

### Run the Super Resolution Demo with Docker Compose

Source: https://github.com/insight-platform/savant/blob/develop/samples/super_resolution/README.md

Launch the super-resolution pipeline using Docker Compose. Access the output stream via RTSP or LL-HLS.

```bash
# you are expected to be in Savant/ directory

docker compose -f samples/super_resolution/docker-compose.x86.yml up

# open 'rtsp://127.0.0.1:554/stream/video-super-resolution' in your player
# or visit 'http://127.0.0.1:888/stream/video-super-resolution/' (LL-HLS)

# Ctrl+C to stop running the compose bundle
```

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

### Savant Frame Filter Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/recipes/1_python_multithreading.rst

A basic structure for a custom frame filter in Savant, inheriting from `BaseFrameFilter`.

```python
class MyFrameFilter(BaseFrameFilter):
    def should_process_frame(self, frame_meta):

```

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

### Download Video for Performance Measurement

Source: https://github.com/insight-platform/savant/blob/develop/samples/fisheye_line_crossing/README.md

Download the 'lab1.mp4' video file to the 'data' folder for performance benchmarking. Ensure the data folder exists.

```bash
# you are expected to be in Savant/ directory

mkdir -p data
curl -o data/lab1.mp4 https://eu-central-1.linodeobjects.com/savant-data/demo/lab1.mp4
```

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

### JSON Attribute Specification Example

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/9_input_json_metadata.rst

Shows the format for specifying attributes associated with an object, such as age with confidence.

```json
{
        "element_name": "age_model",
        "name": "age",
        "value": 69,
        "confidence": 0.9
    }
```

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

### Getting Attributes by Exact Match

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/15_embedded_kvs.rst

Retrieves attributes for a specific key using its exact namespace and name.

```APIDOC
## GET /kvs/get/(str: namespace)/(str: name)

### Description
Retrieves attributes for a specific key using its exact namespace and name.

### Method
GET

### Endpoint
/kvs/get/{namespace}/{name}

### Parameters
#### Path Parameters
- **namespace** (str) - Required - Exact namespace
- **name** (str) - Required - Exact name

### Response
#### Success Response (200)
Serialized AttributeSet
```

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

### Getting Attributes by Glob

Source: https://github.com/insight-platform/savant/blob/develop/docs/source/advanced_topics/15_embedded_kvs.rst

Retrieves attributes for keys that match the provided glob patterns for namespace and name.

```APIDOC
## GET /kvs/search/(str: namespace)/(str: name)

### Description
Retrieves attributes for keys that match the provided glob patterns for namespace and name.

### Method
GET

### Endpoint
/kvs/search/{namespace}/{name}

### Parameters
#### Path Parameters
- **namespace** (str) - Required - Glob pattern to match the namespace
- **name** (str) - Required - Glob pattern to match the name

### Response
#### Success Response (200)
Serialized AttributeSet
```