> ## Documentation Index > Fetch the complete documentation index at: https://imsdkdocs.qualcomm.com/llms.txt > Use this file to discover all available pages before exploring further. # Coding Agent > Use the QIM SDK C++ App Builder skill to generate C++ pipeline apps with an AI coding agent. ## What is the C++ App Builder Skill? The **QIM SDK C++ App Builder** is an AI coding skill that generates C++ applications using the `QIM SDK C++ API`. You describe the pipeline behavior and configuration in natural language, and the agent produces a ready-to-build `main.cc` and `CMakeLists.txt` built on the `QIM SDK C++ API` — along with a `README.md` that documents the information about the generated application. **Flow** QIM SDK coding agent workflow **What it generates** For each request, the agent produces an artifact folder named `qimsdk-cpp-/` containing: * **`main.cc`** — a complete, buildable C++ application using the QIM SDK C++ API, including pipeline construction, element wiring, stream filters, and ML inference configuration * **`CMakeLists.txt`** — the build script that compiles `main.cc` and links against `qimsdk-app-builder` * **`README.md`** — a detailed document covering: * Purpose and pipeline behavior summary * Configuration placeholders (input, model, labels, output paths) * A step-by-step pipeline flow (text summary + Mermaid diagram) * Steps to compile and run the app on device * **`A YAML config file`** — only when you request declarative YAML pipeline mode **Supported use cases:** | Category | Details | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **AI pipelines** | Object detection, image classification, semantic segmentation, face detection, pose estimation, super resolution, depth estimation, audio classification, object tracking, gesture recognition | | **Inputs** | ISP camera, USB camera, file source (MP4/H.264), RTSP stream | | **Outputs** | HDMI display, encoded file (MP4), RTSP stream, Redis/MQTT metadata | | **ML backends** | TFLite (HTP/NPU), QNN, SNPE | | **Pipeline patterns** | Single-stream, multi-stream, daisy-chained models, ML-bin fused inference, custom pre/post-processing, AppSrc/AppSink bridges, YAML config mode | ## Prerequisites ### For generating code Qualcomm dev kits are not needed for code generation. **Host Machine**: Any PC with internet access **Coding Agent**: Any AI coding agent installed (Claude Code, Cursor, Codex, etc.) which supports skills — the skills provided are agent-agnostic. This skill is designed to work well even with low-reasoning / smaller models. Eg: A Sonnet 4.5 model is sufficient. ### For deploying and running apps The target devices where QIM SDK is supported (see [QIM SDK Installation Guide](/installation)) ## How to Use ### Step 1: Get the skill Clone the skill repository to your host machine, then copy the **QIM SDK C++ App Builder skill** into your coding agent's skills directory. Also copy the **qimsdk-deploy** skill, which builds, deploys, and runs the generated app on device (see [Step 4](#step-4-running-the-applications)): ```bash theme={null} git clone https://github.com/qualcomm/qimsdk-agentic-skills # Set this to your coding agent's skills directory. # Claude Code example (see your agent's docs for its skills path): # App Builder skill — generates the app cp -r qimsdk-agentic-skills/skills/qimsdk-cpp-app-builder ~/.claude/skills # Deploy skill — builds, pushes, and runs the app on device cp -r qimsdk-agentic-skills/skills/qimsdk-deploy ~/.claude/skills ``` After copying, your skills directory should look like this: ``` / ├── qimsdk-cpp-app-builder/ │ ├── SKILL.md # Skill definition with rules and API quick reference │ └── references/ # Condensed reference documents └── qimsdk-deploy/ ├── SKILL.md # Deploy skill definition └── references/ # Condensed reference documents ``` The skills directory is agent-specific — Claude Code uses `~/.claude/skills/`. Check your coding agent's documentation for its skills location. You can also scope skills to a single workspace (e.g. Claude Code supports `/.claude/skills/`). *** ### Step 2: Load the skill Restart (or reload) your coding agent after placing the skills so it picks them up. They will appear automatically in the `/skills` list. To verify, open the agent panel and run: ``` /skills ``` You should see both `qimsdk-cpp-app-builder` and `qimsdk-deploy` listed. *** ### Step 3: Generate the application Describe your pipeline to the agent. It will automatically activate the skill and generate a complete `main.cc`, `CMakeLists.txt`, and `README.md`. #### Sample Prompt **Prompt format — describe pipeline behavior and configuration:** ``` Create a QIM SDK C++ app for single-stream YOLOX object detection from an MP4 file, encoding the result to a file. ## Pipeline Behavior - Decode an MP4 file using Qualcomm hardware decoder - Run YOLOX object detection on full frames using TFLite external delegate on HTP/NPU - Merge metadata with the video stream before overlay - Overlay bounding boxes and labels - Encode the overlaid video and save to an output MP4 file ## Configuration - Input: ~/Downloads/qimsdk_samples/media/ai_demo_sample.mp4 - Model: ~/Downloads/qimsdk_samples/models/yolox_w8a8.tflite - Labels: ~/Downloads/qimsdk_samples/labels/yolov8.json - Backend: TFLite external delegate, HTP/NPU - Confidence: 51.0 - Output: ~/Downloads/qimsdk_samples/media/obj_detect_out.mp4 ``` More sample prompts can be found in the [Available Sample Prompts](#available-sample-prompts) section below. #### Generated `README.md` The README documents the generated app in full: * **Purpose** — a plain-English summary of what the pipeline does * **Files** — lists `main.cc`, `CMakeLists.txt`, and `README.md` with descriptions * **Assumptions** — codec format, quantization requirements, camera defaults, output directory pre-conditions * **Configuration** — all user-supplied paths (input, model, labels, output) with instructions on where to change them * **Placeholders to Fill** — any values you still need to supply, or a note that none remain when the request was fully specified * **Pipeline Flow** — a `Text Summary` walkthrough of every element plus a `Mermaid Diagram` of the full pipeline * **Steps to compile** — how to build the app against the QIM SDK with CMake * **Steps to Run** — exact commands to run on device, including any setup (e.g. `mkdir -p` for output directories) # QIM SDK C++ App — Single-Stream YOLOX Object Detection (MP4 → MP4) ## Purpose Decode an MP4 file with the Qualcomm hardware decoder, run **YOLOX** object detection on full frames using the **TFLite external delegate on the HTP/NPU**, merge the detection metadata with the video stream, overlay bounding boxes and class labels, then hardware-encode the annotated video to an output MP4 file. Headless (no display branch). ## Files * `main.cc` — the qimsdk C++ pipeline app * `CMakeLists.txt` — build target (`qimsdk-cpp-yolox-obj-detect-encode`) * `README.md` — this file ## Assumptions * Input is H.264-in-MP4, decoded with `v4l2h264dec` (`capture-io-mode=4`, `output-io-mode=4` — file source decoded through the hardware decoder). * YOLOX (`yolox_w8a8.tflite`) uses the `yolov8` postprocess module with the `yolov8.json` labels, per the model catalog. * Confidence threshold is applied as inline postprocess settings `{"confidence": 51.0}`. * No display: the annotated stream is normalized back to NV12 (`render_vf`), encoded (`v4l2h264enc`, `capture/output-io-mode=4/4`, the correct pairing for a transform/decoder-produced NV12 buffer), parsed, muxed (`mp4mux`), and written to the output MP4 (`filesink`). * `pipeline.eos(true)` is set so `mp4mux` finalizes the container on EOS. * `HOME` is resolved once in C++ (`std::getenv("HOME")` with an unset/empty check) and prepended to every file path, because C++ string literals do not expand `$HOME`. ## Configuration (fixed constants in `main.cc`) | Value | Path | | ------ | --------------------------------------------------------- | | Input | `$HOME/Downloads/qimsdk_samples/media/ai_demo_sample.mp4` | | Model | `$HOME/Downloads/qimsdk_samples/models/yolox_w8a8.tflite` | | Labels | `$HOME/Downloads/qimsdk_samples/labels/yolov8.json` | | Output | `$HOME/Downloads/qimsdk_samples/media/obj_detect_out.mp4` | ## Placeholders to Fill None. All paths, model, labels, confidence, and delegate options are concrete. `${QIMSDK_BINDIR}` is expected to be defined by the parent SDK build. ## Pipeline Flow ### Text Summary `filesrc` reads the MP4 and `qtdemux` extracts the H.264 elementary stream, which `h264parse` prepares and `v4l2h264dec` hardware-decodes. A `queue` (`q_dec`) decouples the decoder thread, then a `VideoFilter` (`vf`) constrains the stream to NV12. A `tee` (`split`) branches: * **Passthrough / video branch** → `qtimetamux` (`metamux`). * **AI branch** → `queue` (`q_ai`) → `qtimlvconverter` (`pre`, preprocess to model tensor) → `qtimltflite` (`infer`, YOLOX, external delegate, HTP/NPU) → `qtimlpostprocess` (`post`, `module=yolov8`, labels, `{"confidence": 51.0}`) → `TextFilter` (`mlf`) → `qtimetamux` (`metamux`). `qtimetamux` merges the detection metadata back onto the video frames, `qtivoverlay` draws the bounding boxes and class labels, a `VideoFilter` (`render_vf`) normalizes the overlaid frames to NV12 for the encoder, and the stream is hardware-encoded by `v4l2h264enc`, parsed by `h264parse` (`h264parser`), muxed by `mp4mux`, and written by `filesink` to the output MP4. ### Mermaid Diagram ```mermaid theme={null} flowchart TD SRC[filesrc] --> DEMUX[qtdemux] DEMUX --> PARSE[h264parse] PARSE --> DEC[v4l2h264dec] DEC --> QDEC[queue q_dec] QDEC --> NV12[NV12 VideoFilter vf] NV12 --> SPLIT[tee split] SPLIT -->|passthrough| MUX[qtimetamux metamux] SPLIT -->|AI| QAI[queue q_ai] QAI --> PRE[qtimlvconverter pre] PRE --> INFER[qtimltflite YOLOX HTP] INFER --> POST[qtimlpostprocess module=yolov8] POST --> TEXT[TextFilter mlf] TEXT --> MUX MUX --> OVL[qtivoverlay] OVL --> RENDER[NV12 VideoFilter render_vf] RENDER --> ENC[v4l2h264enc] ENC --> PARSEOUT[h264parse h264parser] PARSEOUT --> MP4[mp4mux] MP4 --> SINK[filesink] ``` ## Steps to Compile Yocto: [https://imsdkdocs.qualcomm.com/advanced/yocto-build#steps-to-build-custom-application](https://imsdkdocs.qualcomm.com/advanced/yocto-build#steps-to-build-custom-application) ## Steps to Run First ensure all referenced files — the input MP4, the `yolox_w8a8.tflite` model, and the `yolov8.json` labels — are already present on the device at the paths configured in `main.cc`. ```bash theme={null} # Copy the app to device scp qimsdk-cpp-yolox-obj-detect-encode @:~/ # SSH into device and run ssh @ chmod +x ~/qimsdk-cpp-yolox-obj-detect-encode ./qimsdk-cpp-yolox-obj-detect-encode ``` The input MP4 must exist at `$HOME/Downloads/qimsdk_samples/media/ai_demo_sample.mp4` on the device, and the output directory (`$HOME/Downloads/qimsdk_samples/media/`) must be writable so the app can create `obj_detect_out.mp4`. The app runs to end-of-file, finalizes the MP4, and exits. #### Generated `main.cc` * The generated application constructs a tee-split pipeline: decoded frames are split into a passthrough branch and an AI branch. * The AI branch runs `qtimlvconverter` (preprocess) → `qtimltflite` (YOLOX inference via HTP/NPU) → `qtimlpostprocess` → `TextFilter`, then merges back into `qtimetamux` with the passthrough video. * `qtivoverlay` draws bounding boxes, and the result is hardware-encoded and written to an MP4 file via `filesink`. * Pipeline construction and `.execute()` live inside `create_and_execute_pipeline()`; `main()` sets up logging, wraps the call in a try/catch, and returns a non-zero exit code on error. * All paths are `$HOME`-relative and resolved once via a checked `std::getenv("HOME")` helper — C++ string literals do not expand shell variables. ```cpp theme={null} #include #include #include #include using namespace qti; // C++ string literals never expand $HOME; resolve it once at startup with an // explicit unset/empty check so HOME-relative paths fail loudly if HOME is unset. const std::string HOME_PATH = [] { const char* home = std::getenv("HOME"); if (home == nullptr || *home == '\0') { throw std::runtime_error("HOME is not set; cannot resolve filesystem paths"); } return std::string(home); }(); // Example pipeline: // // filesrc -> qtdemux -> h264parse -> v4l2h264dec -> [vf NV12] -> tee // tee (passthrough) -> qtimetamux -> qtivoverlay -> [render vf NV12] -> encoder -> parser -> muxer -> filesink // tee (AI branch) -> qtimlvconverter -> qtimltflite (YOLOX, HTP external delegate) // -> qtimlpostprocess (module=yolov8, labels, confidence=51.0) // -> [TextFilter] -> qtimetamux // // The pipeline reads an MP4/H.264 file, decodes it with the hardware decoder, // runs YOLOX object detection on full frames via the HTP/NPU (TFLite external // delegate), merges the detection metadata back with the video, overlays // bounding boxes and class labels on each frame, encodes the overlaid video // with the hardware H.264 encoder, and writes the result to an output MP4 file. void create_and_execute_pipeline() { // Reads the input media file as raw bytes. Element src("filesrc", "src"); src.set("location", HOME_PATH + "/Downloads/qimsdk_samples/media/ai_demo_sample.mp4"); // Extracts elementary streams from the MP4 container. // Dynamic pad-added linking is handled internally by the SDK. Element demux("qtdemux", "demux"); // Prepares the H.264 bitstream for the decoder. Element parse("h264parse", "parse"); // Decodes the compressed H.264 stream into raw video frames. // // The I/O mode is configured to enforce DMA buffer usage, // avoiding unnecessary buffer copies. Element decoder("v4l2h264dec", "decoder"); decoder.set("output-io-mode", 4); decoder.set("capture-io-mode", 4); // Queue immediately after the hardware decoder before any filter/tee. Element q_dec("queue", "q_dec"); // Normalizes decoded output to NV12 before branching/AI preprocessing. auto vf = VideoFilter().format("NV12"); // Splits the normalized video into a passthrough (main video) branch and // an AI inference branch. Element split("tee", "split"); // Queue to isolate the AI branch from the tee. Element q_ai("queue", "q_ai"); // Converts raw video frames into normalized tensors for inference. Element preprocess("qtimlvconverter", "pre"); // Runs YOLOX object detection via the TFLite HTP/NPU external delegate. Element infer("qtimltflite", "infer"); infer.set("delegate", "external"); infer.set("external-delegate-path", "libQnnTFLiteDelegate.so"); infer.set("external-delegate-options", "QNNExternalDelegate,backend_type=htp,log_level=(string)1;"); infer.set("model", HOME_PATH + "/Downloads/qimsdk_samples/models/yolox_w8a8.tflite"); // Decodes YOLOX output tensors into bounding boxes + class labels. // module=yolov8 is the documented compatibility mapping for YOLOX detection. // The confidence threshold (51.0) is applied as inline JSON settings. Element post("qtimlpostprocess", "post"); post.set("module", "yolov8"); post.set("labels", HOME_PATH + "/Downloads/qimsdk_samples/labels/yolov8.json"); post.set("settings", "{\"confidence\": 51.0}"); // Serialized detection metadata bus feeding qtimetamux. auto mlf = TextFilter(); // Synchronizes AI detection metadata with the original video buffer. Element metamux("qtimetamux", "metamux"); // Draws bounding boxes and class labels on the video frame. Element overlay("qtivoverlay", "overlay"); // Encoder requires NV12 raw video input. auto render_vf = VideoFilter().format("NV12"); // Encodes the overlaid raw video frames into H.264. // // File/decode source path: driver manages both encoder input and output // buffers via dmabuf, so both io-modes are 4. Element encoder("v4l2h264enc", "encoder"); encoder.set("output-io-mode", 4); encoder.set("capture-io-mode", 4); // Parses the encoded H.264 bitstream for muxing. Element h264parser("h264parse", "h264parser"); // Muxes the encoded stream into an MP4 container. Element muxer("mp4mux", "muxer"); // Writes the muxed MP4 stream to the output file. Element sink("filesink", "sink"); sink.set("location", HOME_PATH + "/Downloads/qimsdk_samples/media/obj_detect_out.mp4"); // Creates the pipeline, adds and links elements, and executes it. // // Explicit linking is applied for the tee/metamux branches. // eos(true) lets mp4mux finalize the container correctly on EOS. Pipeline pipeline("qimsdk-cpp-yolox-obj-detect-encode"); pipeline.add(src) .add(demux) .add(parse) .add(decoder) .add(q_dec) .add_stream_filter("vf", vf) .add(split) .add(metamux) .add(q_ai) .add(preprocess) .add(infer) .add(post) .add_stream_filter("mlf", mlf) .add(overlay) .add_stream_filter("render_vf", render_vf) .add(encoder) .add(h264parser) .add(muxer) .add(sink) .eos(true) .link("src", "demux", "parse", "decoder", "q_dec", "vf", "split") .link("split", "metamux") .link("split", "q_ai", "pre", "infer", "post", "mlf", "metamux") .link("metamux", "overlay", "render_vf", "encoder", "h264parser", "muxer", "sink") .execute(); } int main() { // Route GStreamer logs through the IMSDK logger and enable debug output. qti::SetImsdkGstLogMode(qti::ImsdkGstLogMode::ImsdkLog); qti::SetImsdkLogLevel(qti::ImsdkLogLevel::Debug); try { create_and_execute_pipeline(); } catch (const std::exception &ex) { std::cerr << "Exception: " << ex.what() << std::endl; return 1; } return 0; } ``` #### Generated `CMakeLists.txt` * Defines a single executable target (`qimsdk-cpp-yolox-obj-detect-encode`) built from `main.cc`. * Links against `qimsdk-app-builder` — no direct GStreamer package dependency. * Installs the binary to `${QIMSDK_BINDIR}` (defined by the parent SDK build) with standard executable permissions. ```cmake theme={null} cmake_minimum_required(VERSION 3.8.2) set(TEST_TARGET qimsdk-cpp-yolox-obj-detect-encode) add_executable(${TEST_TARGET} main.cc ) target_link_libraries(${TEST_TARGET} PRIVATE qimsdk-app-builder ) install( TARGETS ${TEST_TARGET} RUNTIME DESTINATION ${QIMSDK_BINDIR} PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ WORLD_EXECUTE WORLD_READ ) ``` *** ### Step 4: Running the applications | File | Download | Save as | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | | YOLOX W8A8 model | [Qualcomm AI Hub — YOLOX](https://aihub.qualcomm.com/iot/models/yolox) | `yolox_w8a8.tflite` | | Detection labels | yolov8.json | `yolov8.json` | | Sample video | Input video | `ai_demo_sample.mp4` | If the downloaded model file is a `.zip` archive, extract it on your host machine before copying: `unzip filename.zip` The input video, model, and labels must be present on the device before running — regardless of how you build and run the app. Copy them to the paths `main.cc` expects: ```bash theme={null} # Replace and with your device credentials. ssh @ "mkdir -p ~/Downloads/qimsdk_samples/media ~/Downloads/qimsdk_samples/models ~/Downloads/qimsdk_samples/labels" # Copy the assets to device (paths must match main.cc) scp ai_demo_sample.mp4 @:~/Downloads/qimsdk_samples/media/ scp yolox_w8a8.tflite @:~/Downloads/qimsdk_samples/models/ scp yolov8.json @:~/Downloads/qimsdk_samples/labels/ ``` The C++ app must be compiled before it can run. With the assets in place, you have two options to build and run the agent-generated app: **Option A — Use the QIM SDK Deploy skill (Recommended):** The `qimsdk-deploy` skill builds the app on your host against the Yocto SDK, then pushes the compiled binary to the device and runs it over SSH. It handles only the app build and binary transfer — the assets from the previous step must already be on the device. **Option B — Follow the generated README:** Follow the steps in the [`README.md`](#generated-readme-md) to compile the app, then push the binary to the device and run it: 1. **Compile the app** by following the steps at [Yocto Build](/advanced/yocto-build). 2. **Push the compiled binary to the device and run it:** ```bash theme={null} # Copy the built binary to device scp qimsdk-cpp-yolox-obj-detect-encode @:~/ # SSH into device and run ssh @ chmod +x ~/qimsdk-cpp-yolox-obj-detect-encode ./qimsdk-cpp-yolox-obj-detect-encode ``` On completion (EOS), the annotated video is written to `~/Downloads/qimsdk_samples/media/obj_detect_out.mp4`. *** ## Available Sample Prompts | # | Prompt | | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | [Camera YOLOv8 object detection using fused TFLite ML-bin](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_01_mlbin_yolov8_camera_overlay.md) | | 2 | [Two-stage PPE daisy-chain — person detection → PPE detection → overlay display](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_02_mlbin_ppe_daisy_chain_display.md) | | 3 | [Object detection with custom C++ postprocess placeholder](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_03_custom_postprocess_detection_placeholder.md) | | 4 | [Pose estimation with custom C++ postprocess placeholder](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_04_custom_postprocess_pose_placeholder.md) | | 5 | [Inference app with tensor output via custom callback placeholder](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_05_tensor_dump_callback_placeholder.md) | | 6 | [YOLOv8 object detection pipeline with generated YAML config](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_06_yaml_yolov8_generated_config.md) | | 7 | [Object detection with custom C++ preprocess placeholder](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_07_custom_preprocess_detection_placeholder.md) | | 8 | [Object detection with TFLite ML-bin custom preprocess placeholder](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_08_mlbin_custom_preprocess_detection_placeholder.md) | | 9 | [Load existing YOLOv8 detection pipeline from external YAML config](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_09_yaml_yolov8_external_config.md) | | 10 | [Single-stream YOLOX object detection from MP4, encoded to file](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_10_single_stream_object_detection.md) | | 11 | [AI wall — four parallel AI inference streams composed into a 2×2 grid display](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_11_ai_wall.md) | | 12 | [Four-stage gesture recognition daisy-chain pipeline](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_12_gesture_recognition.md) | | 13 | [Audio classification — classify audio events from video and overlay results](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/AI_13_audio_classification.md) | | 14 | [Two pipelines bridged through application-managed buffers (AppSrc/AppSink)](https://github.com/qualcomm/qimsdk-agentic-skills/blob/main/sample-prompts/qimsdk-cpp-app-builder/MM_01_appsrc_appsink_bridge.md) |