Quick start guide

What is the QIM SDK Python App Builder?

Overview

The QIM SDK Python App Builder is a modern Python SDK for building, running, and managing multimedia and AI pipelines on Qualcomm platforms. It sits as a high-level abstraction layer on top of GStreamer, taking care of framework-level concerns such as element negotiation, pad linking, signal management, event loops, and state transitions, so developers can stay focused on application logic instead of framework boilerplate.

Key Capabilities

No GStreamer expertise required — the SDK manages all underlying GStreamer mechanics internally, with no compile-time dependency on GStreamer headers.
Less code, no GStreamer boilerplate — a fluent, high-level API bundles away the pipeline construction, element linking, and state management that GStreamer’s native API would otherwise require, so a functional camera-to-display pipeline can be written in just a few lines of Python.
Custom pre/post-processing — plug in your own pre- and post-processing logic around the built-in ML bins without writing a custom GStreamer element.
AI inference support — built-in ML bins for TFLite, QNN, SNPE, and ONNX models.
Broad multimedia support — video capture, signal processing, ML inference, overlay rendering, and display output.

API Reference

API	Description	API Code Reference
Pipeline	Builds, links, and manages the full lifecycle of a GStreamer pipeline. Supports both programmatic (Python fluent API) and declarative (YAML) pipeline definition. Key methods: `add()`, `link()`, `add_stream_filter()`, `execute()`, `prepare()`, `start()`, `stop()`, `get()`.	`p = Pipeline("cam-pipeline") p.add("qtiqmmfsrc", "src").add("waylandsink", "sink").execute()`
Element	Generic wrapper around a GStreamer element. Supports fluent property setting at create time or at runtime to update a live pipeline.	`sink = Element("waylandsink", "display") sink.set("fullscreen", True) sink.set("sync", False)`
Buffer	Unified buffer abstraction over native GStreamer memory. Provides read/write access, timestamp metadata, and zero-copy transfer paths. Key methods: `data()`, `size()`, `resize()`, `pts()`, `dts()`, `duration()`.	`def consume_buffer(buf): data = buf.data() pts = buf.pts() sink.set_buffer_consumer(consume_buffer)`
AppSrc	App-facing source. Feeds buffers from application code into the pipeline using lambda callbacks or a push API.	`def produce_buffer(buf): # fill buf.data() return True src = AppSrc(pipeline.get("src")) src.set_buffer_producer(produce_buffer)`
AppSink	App-facing sink. Delivers pipeline output buffers to application code with zero-copy.	`def consume_buffer(buf): # consume buf.data() pass sink = AppSink(pipeline.get("sink")) sink.set_buffer_consumer(consume_buffer)`
CamSrc	Built-in ISP camera source. Exposes an API for runtime image capture and snapshots.	`cam = CamSrc(pipeline.get("source")) cam.capture_image("snapshot.jpg")`
MLPreProcess	Attaches a custom Python callback for pre-processing input frames before ML inference.	`def preprocess(buf): # transform input frame pass pre = MLPreProcess(pipeline.get("preproc")) pre.set_handler(preprocess)`
MLPostProcess	Attaches a custom Python callback for post-processing raw inference tensor output.	`def postprocess(buf): # parse inference output pass pp = MLPostProcess(pipeline.get("postproc")) pp.set_handler(postprocess)`
MLVideoTFLiteBin / MLVideoQNNBin / MLVideoSNPEBin / MLVideoONNXBin	All-in-one preprocess + inference + postprocess bins. Supports TFLite, QNN, SNPE, and ONNX models.	`pipeline.add("MLVideoTFLiteBin", "ml", "model", "/models/model.tflite", "delegate", "htp")`
VideoFilter / AudioFilter / ImageFilter / H264Filter / TensorFilter / TextFilter	Fluent caps builders for `add_stream_filter()`. Describes stream characteristics for caps negotiation between pipeline stages.	`pipeline.add_stream_filter("vf", VideoFilter().format("NV12").resolution(1920, 1080).framerate(30))`

Build your application

Before running any of the applications below, create the sample directory tree on the target device:

# ~ resolves automatically to the correct home directory on the device (/root on QLI, /home/ubuntu on Ubuntu).

ssh <user>@<device-ip> "mkdir -p ~/Downloads/qimsdk_samples/{media,models,labels}"

This is required even for apps that don’t download any media, model, or label files (such as the camera capture and recording apps), since they still write their output under this path.

USB Camera Source

USB (UVC) cameras are handled by the v4l2src node. Each USB camera comes with its own format and frame constraints. Because of this, we always place qtivtransform right after the USB camera to ensure that the rest of the pipeline receives a hardware-friendly NV12 (Semi-planar YUV420) video format. qtivtransform automatically operates in passthrough mode if the USB camera already supports NV12, so you don’t need to worry about any performance overhead.

Explicit coding style
Implicit coding style
YAML config style

Check application source code on GitHub: qimsdk_ref_usb_cameraPre-built application on device: /usr/bin/qimsdk_ref_usb_camera.py

"""USB camera preview using explicit linking."""

import argparse

from qimsdk import Element, Pipeline, VideoFilter

#  Example pipeline:
#
#    source -> transform -> [videofilter] -> display
#
#  The pipeline reads frames from a USB (V4L2) camera, rotates them, restricts
#  the stream to NV12/1080p/30fps, and displays the result through Wayland.


def create_and_execute_pipeline(device: str = "/dev/video2") -> None:

    # Captures frames from the USB camera source.
    source = (
        Element("v4l2src", "source")
        .set("device", device)
    )

    # Applies geometric transforms to video frames.
    transform = Element("qtivtransform", "transform")

    # Stream filters used in branch links.
    # They define specific stream characteristics from the supported options.
    videofilter = VideoFilter().format("NV12").resolution(1920, 1080).framerate(30)

    # Render video stream on display.
    #
    # sync=false disables strict rendering synchronization to the pipeline clock.
    # fullscreen=true renders the output fullscreen on the target display.
    display = (
        Element("waylandsink", "display")
        .set("sync", False)
        .set("fullscreen", True)
    )

    # Creates the pipeline, adds elements, links them explicitly, and executes it.
    pipeline = (
        Pipeline("usb-cam-pipeline")
        .add(source)
        .add(transform)
        .add_stream_filter("videofilter", videofilter)
        .add(display)
        .link("source", "transform", "videofilter", "display")
    )

    pipeline.execute()


def main() -> None:

    from qimsdk import ImsdkGstLogMode, ImsdkLogLevel, SetImsdkGstLogMode, SetImsdkLogLevel
    SetImsdkGstLogMode(ImsdkGstLogMode.ImsdkLog)
    SetImsdkLogLevel(ImsdkLogLevel.Debug)

    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "-d", "--device", default="/dev/video2",
        help="V4L2 device node to capture from (default: %(default)s)",
    )
    args = parser.parse_args()

    create_and_execute_pipeline(args.device)


if __name__ == "__main__":
    main()

Connect a USB camera

Connect a USB (UVC) camera to the target device and verify it is exposed as /dev/video2 (update the pipeline’s device property if your camera is exposed on a different node).

Run the application

python3 /usr/bin/qimsdk_ref_usb_camera.py --input-config /dev/video2

Expected Output

The live camera feed is rotated and rendered fullscreen on the display in NV12 format at 1080p/30fps.

To stop the application, press CTRL + C.

Check application source code on GitHub: qimsdk_ref_usb_camera_implPre-built application on device: /usr/bin/qimsdk_ref_usb_camera_impl.py

"""USB camera preview using auto-linking."""

import argparse

from qimsdk import Pipeline, VideoFilter

#  Example pipeline:
#
#    source -> transform -> [videofilter] -> display
#
#  The pipeline reads frames from a USB (V4L2) camera, rotates them, restricts
#  the stream to NV12/1080p/30fps, and displays the result through Wayland.


def create_and_execute_pipeline(device: str = "/dev/video2") -> None:

    # Creates the pipeline, adds and links elements, and executes it.
    #
    # Elements are created on the fly as they are added, and linking is
    # implicit, following the order in which elements are added.
    #
    # sync=false disables strict rendering synchronization to the pipeline clock.
    # fullscreen=true renders the output fullscreen on the target display.
    pipeline = (
        Pipeline("usb-cam-pipeline")
        # Captures frames from the USB camera source.
        .add("v4l2src", "source", "device", device)
        # Applies geometric transforms to video frames.
        .add("qtivtransform", "transform")
        # Stream filter used in the branch link.
        # It defines specific stream characteristics from the supported options.
        .add_stream_filter(
            "videofilter",
            VideoFilter().format("NV12").resolution(1920, 1080).framerate(30),
        )
        # Render video stream on display.
        .add("waylandsink", "display", "sync", False, "fullscreen", True)
    )

    pipeline.execute()


def main() -> None:

    from qimsdk import ImsdkGstLogMode, ImsdkLogLevel, SetImsdkGstLogMode, SetImsdkLogLevel
    SetImsdkGstLogMode(ImsdkGstLogMode.ImsdkLog)
    SetImsdkLogLevel(ImsdkLogLevel.Debug)

    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "-d", "--device", default="/dev/video2",
        help="V4L2 device node to capture from (default: %(default)s)",
    )
    args = parser.parse_args()

    create_and_execute_pipeline(args.device)


if __name__ == "__main__":
    main()

Connect a USB camera

Connect a USB (UVC) camera to the target device and verify it is exposed as /dev/video2 (update the pipeline’s device property if your camera is exposed on a different node).

Run the application

python3 /usr/bin/qimsdk_ref_usb_camera_impl.py --input-config /dev/video2

Expected Output

The live camera feed is rotated and rendered fullscreen on the display in NV12 format at 1080p/30fps.

To stop the application, press CTRL + C.

See the full YAML configuration here: qimsdk_ref_usb_camera.yamlCheck application source code on GitHub: qimsdk_ref_yml.pyPre-built application on device: /usr/bin/qimsdk_ref_yml.pyYAML configuration saved on device: /etc/qimsdk/qimsdk_ref_usb_camera.yaml

pipeline:
  elements:
    - type: v4l2src
      name: source
      device: /dev/video2

    - type: qtivtransform
      name: transform

    - type: filter
      name: videostream
      video:
        format: NV12
        width: 1920
        height: 1080
        framerate: 30

    - type: waylandsink
      name: display
      sync: false
      fullscreen: true

Connect a USB camera

Connect a USB (UVC) camera to the target device and verify it is exposed as /dev/video2 (update the pipeline’s device property if your camera is exposed on a different node).

Run the application

qimsdk_ref_yml.py /etc/qimsdk/qimsdk_ref_usb_camera.yaml

Expected Output

The live camera feed is rotated and rendered fullscreen on the display in NV12 format at 1080p/30fps.

To stop the application, press CTRL + C.

Object Detection

This pipeline captures from a built-in camera, runs an object detection model through an ML inference bin, renders bounding box overlays on the output frames, and displays the result. The ML bin handles preprocessing, inference, and postprocessing internally. The stream filter pins the input video format expected by the model. The overlay element draws detection results on each frame before display.

Explicit coding style

Check application source code on GitHub: qimsdk_ref_camera_yolov8Pre-built application on device: /usr/bin/qimsdk_ref_camera_yolov8.py

Download Required Files

File	Download	Save as
YOLOv8 detection model	Qualcomm AI Hub — YOLOv8	`yolov8_det_quantized.tflite`
Detection labels	yolov8.json	`yolov8.json`

If the downloaded model file is a .zip archive, extract it on your host machine before copying: unzip filename.zipSome AI Hub models require running the AI Hub export/optimize step for your target runtime before the downloaded file is usable — download alone isn’t always sufficient.

Copy the assets to the device

The model and labels must be present on the device before running. Copy them to the paths the application expects:

# Replace <user> and <device-ip> with your device credentials.
# ~ resolves automatically to the correct home directory on the device (/root on QLI, /home/ubuntu on Ubuntu).

ssh <user>@<device-ip> "mkdir -p ~/Downloads/qimsdk_samples/models ~/Downloads/qimsdk_samples/labels"

# Copy the assets to device
scp yolov8_det_quantized.tflite <user>@<device-ip>:~/Downloads/qimsdk_samples/models/
scp yolov8.json <user>@<device-ip>:~/Downloads/qimsdk_samples/labels/

Connect an IMX camera

This application uses the built-in ISP camera. On platforms without an onboard ISP camera (e.g. IQ9), attach an external IMX camera (e.g. from RB3 Gen2) before running the application — see ISP Camera (Config #2 / qticamsrc) for the procedure to switch from libcamera to qticamsrc.

Run the application

python3 /usr/bin/qimsdk_ref_camera_yolov8.py

Expected Output

The live camera feed is rendered fullscreen on the display with YOLOv8 bounding boxes and class labels overlaid on each detected object in real time.

To stop the application, press CTRL + C.

Custom Post-Processing

The QIM SDK implements AI model post-processing through dedicated modules that take tensors as input and produce predictions. All underlying complexity — batching, daisy-chaining, image mask support, and ML metadata handling — is encapsulated within the post-processing plugin. This makes MLPostProcess the ideal integration point for application-specific logic, since the application does not need to handle any of that complexity directly. A specialized post-processing module manages the bindings between the pipeline and the application.

Explicit coding style

Check application source code on GitHub: qimsdk_ref_external_postprocess_mlbin_yolov8.pyPre-built application on device: /usr/bin/qimsdk_ref_external_postprocess_mlbin_yolov8.py

Download Required Files

File	Download	Save as
YOLOv8 detection model	Qualcomm AI Hub — YOLOv8	`yolov8_det_quantized.tflite`
Detection labels	yolov8.json	`yolov8.json`
Sample video	Input video	`ai_demo_sample.mp4`

Copy the assets to the device

The input video, model, and labels must be present on the device before running. Copy them to the paths the application expects:

# Replace <user> and <device-ip> with your device credentials.
# ~ resolves automatically to the correct home directory on the device (/root on QLI, /home/ubuntu on Ubuntu).

ssh <user>@<device-ip> "mkdir -p ~/Downloads/qimsdk_samples/media ~/Downloads/qimsdk_samples/models ~/Downloads/qimsdk_samples/labels"

# Copy the assets to device
scp ai_demo_sample.mp4 <user>@<device-ip>:~/Downloads/qimsdk_samples/media/
scp yolov8_det_quantized.tflite <user>@<device-ip>:~/Downloads/qimsdk_samples/models/
scp yolov8.json <user>@<device-ip>:~/Downloads/qimsdk_samples/labels/

Run the application

python3 /usr/bin/qimsdk_ref_external_postprocess_mlbin_yolov8.py

Expected Output

The video plays back with YOLOv8 bounding boxes and class labels decoded by the custom postprocessing callback, overlaid and rendered fullscreen on the display.

To stop the application, press CTRL + C.

Customize application

Refer to the Steps to build custom application section to customize this application.

Benefits of QIM SDK Python App Builder

Significantly reduced source code
Improved readability
Internal GStreamer state transition handling
Hidden End-of-Stream handling
Automatic error and state event handling
Automatic resource cleanup
Simplified AppSink/AppSrc interaction using lambda functions
SDK-managed buffer mapping and queries
Simplified buffer access anywhere in the pipeline using wrapped GST probes
YAML-based pipeline description

Getting Started

Examples

Design

Plugins

What is the QIM SDK Python App Builder?

Overview

Key Capabilities

API Reference

Build your application

USB Camera Source

Object Detection

Custom Post-Processing

Benefits of QIM SDK Python App Builder

​What is the QIM SDK Python App Builder?

​Overview

​Key Capabilities

​API Reference

​Build your application

​USB Camera Source

​Object Detection

​Custom Post-Processing

​Benefits of QIM SDK Python App Builder

What is the QIM SDK Python App Builder?

Overview

Key Capabilities

API Reference

Build your application

USB Camera Source

Object Detection

Custom Post-Processing

Benefits of QIM SDK Python App Builder