概述

qtimetamux 元素是支持 AI 的 GStreamer 流水线的核心组件。它的作用是将后处理的 AI/CV 结果与原始媒体缓冲区同步，并使用 GStreamer 提供的标准元数据机制将这些结果作为 GstMeta 附加。在实践中，ML 后处理阶段生成的输出——例如：

边界框坐标
类别标签
分割掩码
关键点
运动矢量
其他自定义 AI/CV 元数据

都可以与相应的视频或音频帧关联，并作为单个统一的缓冲区在流水线中向前传递。这种设计使构建推理结果与原始帧紧密耦合的流水线变得更加容易。下游组件可以同时消费媒体缓冲区及其元数据，而无需单独的同步逻辑。通过将元数据直接嵌入到帧中，qtimetamux 支持几种常见的 AI 流水线模式：

实时可视化——元数据可以被 qtivoverlay 等叠加元素消费，将边界框、标签和其他推理结果直接渲染到视频输出上。
级联 AI 流水线——携带元数据的缓冲区可以传递给后续的推理阶段，实现一个模型的输出馈入下一个模型的多阶段 AI 工作流。
应用层访问——生成的缓冲区可以发送到 appsink，使自定义应用程序能够访问媒体帧及其附加的元数据，用于业务逻辑或决策。
元数据序列化与外部集成——元数据可以转发给 qtimlmetaparser，后者将其转换为 JSON。该 JSON 随后可以通过 qtiredissink 发布到外部系统，例如 MQTT、Kafka 或 REDIS 服务器。

除了 AI 推理输出外，qtimetamux 还能够附加其他元数据类型，例如运动矢量，使其对 AI 和更广泛的基于计算机视觉的工作流都很有用。 qtimetamux_workflow

示例流水线

下载所需文件

文件	下载	保存为
YOLOX W8A8 模型	Qualcomm AI Hub — YOLOX	`yolo_x_w8a8.tflite`
检测标签	yolov8.json	`yolov8.json`
示例视频	输入视频	`Draw_1080p_180s_30FPS.mp4`

将文件复制到设备

# Replace $HOME to the appropriate device path before running the commands.
# For QLI:    /root
# For Ubuntu: /home/ubuntu
# Modify this based on your platform and ensure files are copied to the correct location on the device.
# Run from your host machine — replace <user> and <device-ip>

ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels,media,media/output}"
scp yolo_x_w8a8.tflite          <user>@<device-ip>:$HOME/models/
scp yolov8.json                  <user>@<device-ip>:$HOME/labels/
scp Draw_1080p_180s_30FPS.mp4   <user>@<device-ip>:$HOME/media/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels,media,media/output}
export MODEL_NAME=yolo_x_w8a8.tflite
export LABELS_NAME=yolov8.json
export SRC_VIDEO_NAME=Draw_1080p_180s_30FPS.mp4

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
filesrc location=$HOME/media/$SRC_VIDEO_NAME ! qtdemux ! h264parse ! \
v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! \
tee name=t ! qtimetamux name=obj_mux ! qtivoverlay ! waylandsink fullscreen=true sync=false \
t. ! queue ! qtimlvconverter ! queue ! \
qtimltflite model=$HOME/models/$MODEL_NAME delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
  external-delegate-options="QNNExternalDelegate,backend_type=htp,log_level=(string)1;" ! queue ! \
qtimlpostprocess module=yolov8 labels=$HOME/labels/$LABELS_NAME \
  settings="{\"confidence\": 51.0}" ! text/x-raw ! queue ! obj_mux.

层次结构

GObject
   GstObject
      GstElement
         qtimetamux

Pad 模板

sink

能力
`video/x-raw(ANY)`	`format: NA`
`audio/x-raw(ANY)`	`format: NA`
可用性：始终
方向：sink
Pad 名称：`sink`

能力
`text/x-raw`	`format: utf8`
`cv/x-optical-flow`	`format: NA`
可用性：按请求
方向：sink
Pad 名称：`data_%u`

src

能力
`video/x-raw(ANY)`	`format: NA`
`audio/x-raw(ANY)`	`format: NA`
可用性：始终
方向：source

元素属性

属性	描述
`latency`	以纳秒为单位的附加延迟，为上游生成当前位置的元数据条目留出更多时间。在同步模式下，当元数据生成时间超过默认保持窗口时非常有用。 `Type: Unsigned Integer64` `Default: 0` `Range: 0 - 18446744073709551615` `Flags: readable/writable (changeable only in NULL or READY state)`
`mode`	控制用于将元数据缓冲区与主媒体帧关联的同步策略。 `Type: Enum` `Default: 0, "async"` `Range:` `(0): async - No timestamp synchronization. The N-th incoming media frame is held until the N-th data buffer has been received on all data pads. Suitable for fixed, predictable sequences` `(1): sync - Timestamp-based synchronization. Each incoming frame is held for up to 1 / framerate (video) or 1 / rate (audio). Metadata with matching timestamps is attached before the frame is forwarded downstream` `Flags: readable/writable (changeable only in NULL or READY state)` `Example: mode="sync" (or) mode=1`
`queue-size`	设置内部输入和输出队列的大小。 `Type: Unsigned Integer` `Default: 10` `Range: 3 - 4294967295` `Flags: readable/writable (changeable only in NULL or READY state)`

主缓冲区、元数据同步与延迟控制

该插件设计有一个接收主视频或音频缓冲区的单一主 sink pad，以及多个收集 ML 后处理结果或 CV 运动矢量的辅助数据 pad。到达辅助 pad 的数据可以以字符串或 blob 形式提供，并被解析为结构化表示。解析后，插件将每个数据缓冲区与其对应的主媒体帧匹配，并将结果作为 GstMeta 附加。

异步模式

这是默认的同步模式。不执行基于时间戳的匹配。相反，元数据缓冲区以严格的 1:1 顺序与主帧关联：

第 N 个传入的视频/音频帧被保持，直到在所有数据 pad 上都收到第 N 个数据缓冲区。
一旦该帧所需的所有数据可用，即附加元数据。
然后将增强后的缓冲区推送到下游。

当媒体缓冲区和元数据缓冲区以固定、可预测的顺序生成时，此模式很适用。

同步模式

在同步模式下，插件执行基于时间戳的同步。每个传入的主帧最多保持 1 / framerate 秒（视频）或 1 / rate 秒（音频）的有限时间窗口。例如，在 30 fps 时，帧可能被保持约 33.3 毫秒。在此保持期间，插件在其辅助 pad 上等待时间戳与主帧时间戳匹配的数据缓冲区：

如果所有预期的数据缓冲区在时间窗口内到达，则在转发之前附加它们。
如果一个或多个辅助 pad 未能及时提供匹配的缓冲区，则仅附加成功匹配的元数据，并将主缓冲区释放到下游。

延迟控制

在某些用例中，同步模式下的默认保持时间可能太短——尤其是在元数据生成耗时超出预期时。latency 属性通过接受以纳秒为单位的整数值来延长等待时间，允许插件在转发主帧之前为迟到的数据缓冲区等待更长时间。 qtimetamux_latency_control

用法

人员检测

下载所需文件

文件	下载	保存为
YOLOX W8A8 模型	Qualcomm AI Hub — YOLOX	`yolo_x_w8a8.tflite`
检测标签	yolov8.json	`yolov8.json`
示例视频	输入视频	`Draw_1080p_180s_30FPS.mp4`

如果任何下载的文件是 .zip 压缩包，请在复制之前在主机上解压： unzip filename.zip

将文件复制到设备

# Replace $HOME to the appropriate device path before running the commands.
# For QLI:    /root
# For Ubuntu: /home/ubuntu
# Modify this based on your platform and ensure files are copied to the correct location on the device.
# Run from your host machine — replace <user> and <device-ip>

ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels,media,media/output}"
scp yolo_x_w8a8.tflite           <user>@<device-ip>:$HOME/models/
scp yolov8.json                  <user>@<device-ip>:$HOME/labels/
scp Draw_1080p_180s_30FPS.mp4    <user>@<device-ip>:$HOME/media/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

export MODEL_NAME=yolo_x_w8a8.tflite
export LABELS_NAME=yolov8.json
export SRC_VIDEO_NAME=Draw_1080p_180s_30FPS.mp4

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
filesrc location=$HOME/media/$SRC_VIDEO_NAME ! qtdemux ! h264parse ! \
v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! \
tee name=t ! qtimetamux name=obj_mux ! qtivoverlay ! waylandsink fullscreen=true sync=false \
t. ! queue ! qtimlvconverter ! queue ! \
qtimltflite model=$HOME/models/$MODEL_NAME delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
external-delegate-options="QNNExternalDelegate,backend_type=htp,log_level=(string)1;" ! queue ! \
qtimlpostprocess module=yolov8 labels=$HOME/labels/$LABELS_NAME \
settings="{\"confidence\": 51.0}" ! text/x-raw ! queue ! obj_mux.

检测-分类级联流水线

此流水线演示了一种级联推理方法，其中一个模型（检测）的输出用于裁剪感兴趣区域（ROI），然后将其馈入辅助模型（分类）。

下载所需文件

文件	下载	保存为
YOLOX 模型	Qualcomm AI Hub — YOLOX	`yolox-yolo-x-w8a8.tflite`
YOLO 标签	yolov8.json	`yolov8.json`
MobileNet 模型	mobilenet-softmax	`mobilenet_v2-mobilenet-v2-w8a8.tflite`
MobileNet 标签	mobilenet.json	`mobilenet_v2.json`
输入视频	输入视频	`video.mp4`

将文件复制到设备

ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels,media}"
scp yolox-yolo-x-w8a8.tflite                     <user>@<device-ip>:$HOME/models/
scp yolov8.json                                  <user>@<device-ip>:$HOME/labels/
scp mobilenet_v2-mobilenet-v2-w8a8.tflite        <user>@<device-ip>:$HOME/models/
scp mobilenet_v2.json                            <user>@<device-ip>:$HOME/labels/
scp video.mp4                                    <user>@<device-ip>:$HOME/media/

连接到设备

ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels,media}

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
  qtimlvconverter name=det_conv \
  qtimltflite name=det_infer delegate=external external-delegate-path=libQnnTFLiteDelegate.so external-delegate-options="QNNExternalDelegate,backend_type=htp,log_level=(string)1;" model=$HOME/models/yolox-yolo-x-w8a8.tflite \
  qtimlpostprocess name=det_post module=yolov8 labels=$HOME/labels/yolov8.json settings="{\"confidence\": 51.0}" \
  qtimetamux name=det_mux \
  qtivoverlay name=main_overlay \
  qtimlvconverter name=cls_conv \
  qtimltflite name=cls_infer delegate=external external-delegate-path=libQnnTFLiteDelegate.so external-delegate-options="QNNExternalDelegate,backend_type=htp,log_level=(string)1;" model=$HOME/models/mobilenet_v2-mobilenet-v2-w8a8.tflite \
  qtimlpostprocess name=cls_post module=mobilenet labels=$HOME/labels/mobilenet_v2.json settings="{\"confidence\": 51.0}" \
  qtimetamux name=cls_mux \
  qtivoverlay name=cls_overlay \
  filesrc location=$HOME/media/video.mp4 ! qtdemux ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! tee name=src_tee \
  src_tee. ! queue ! det_mux. \
  src_tee. ! queue ! det_conv. det_conv. ! queue ! det_infer. det_infer. ! queue ! det_post. det_post. ! text/x-raw ! queue ! det_mux. \
  det_mux. ! queue ! tee name=meta_tee \
  meta_tee. ! queue ! cls_mux. \
  meta_tee. ! queue ! cls_conv. cls_conv. ! queue ! cls_infer. cls_infer. ! queue ! cls_post. cls_post. ! text/x-raw ! queue ! cls_mux. \
  cls_mux. ! queue ! cls_overlay. cls_overlay. ! queue ! waylandsink fullscreen=true sync=false

Introduction

Architecture

Key Documents

Technologies

System

Release Notes

qtimetamux

概述

示例流水线

层次结构

Pad 模板

sink

src

元素属性

主缓冲区、元数据同步与延迟控制

异步模式

同步模式

延迟控制

用法

人员检测

检测-分类级联流水线

​概述

​示例流水线

​层次结构

​Pad 模板

​sink

​src

​元素属性

​主缓冲区、元数据同步与延迟控制

​异步模式

​同步模式

​延迟控制

​用法

​人员检测

​检测-分类级联流水线

概述

示例流水线

层次结构

Pad 模板

sink

src

元素属性

主缓冲区、元数据同步与延迟控制

异步模式

同步模式

延迟控制

用法

人员检测

检测-分类级联流水线