4、GStreamer Caps 协商机制：什么是 Caps？Caps 如何影响管道连接？如何查看和设置 Caps？

好，咱们今天聊一个硬核话题——Caps 协商。说实话，我刚开始用 GStreamer 的时候，被这个 Caps 折腾得够呛。管道搭好了，一运行就报错，说「无法协商 Caps」。那时候我还不明白，这玩意儿到底在协商什么？

后来做项目做多了，才慢慢摸透。说白了，Caps 就是 GStreamer 里描述数据格式的「身份证」。两个元件要连在一起，得先看看对方的身份证，格式对得上才能握手成功。

什么是 Caps？

Caps 的全称是 Capabilities，也就是能力集。它描述了一个 pad 能处理的数据格式。比如视频是 RGB 还是 YUV？分辨率是多少？帧率多少？音频是 16 位还是 32 位？采样率 44100 还是 48000？

我举个例子你就明白了：

video/x-raw, format=I420, width=1920, height=1080, framerate=30/1

这串东西就是一个 Caps。它告诉你：这是原始视频数据，格式是 I420（YUV 的一种），分辨率 1920x1080，帧率 30fps。

每个 Caps 由两部分组成：

  • MIME 类型：比如 video/x-raw、audio/x-raw、video/x-h264
  • 属性键值对：比如 format=I420、width=1920

核心要点：Caps 就是 GStreamer 世界里描述数据格式的「协议」。没有它，元件之间就是鸡同鸭讲。

Caps 如何影响管道连接？

好，现在问题来了：两个元件怎么通过 Caps 握手？

这个过程叫 Caps 协商。我习惯把它比作相亲——两个 pad 互相看对方的条件，合适就在一起，不合适就拉倒。

具体流程是这样的：

  1. 源元件的 src pad 先列出自己能输出的所有格式（一个 Caps 列表）
  2. 接收元件的 sink pad 也列出自己能接收的所有格式
  3. 双方找一个交集——共同的格式
  4. 如果找到交集，就确定下来，开始传输数据
  5. 如果找不到交集，管道就报错，连接失败

嗯，这里要注意：协商不是一次性的。有时候数据流到一半，格式变了（比如分辨率切换），会触发 重新协商。我在做视频会议项目时就遇到过，摄像头突然从 1080p 切到 720p，整个管道得重新走一遍协商流程。

避坑指南：我曾经在项目中遇到一个诡异的问题——视频流播放到一半突然卡住。查了半天，发现是解码器输出的格式变了，但后面的元件没准备好接收新格式。从那以后，我写管道都会加上 capssetter 或者 capsfilter 来固定格式，避免意外协商。

如何查看 Caps？

查看 Caps 是调试管道的必备技能。我常用的方法有几种：

方法一：命令行查看

用 gst-inspect-1.0 可以查看元件的 pad 信息：

# 查看 videotestsrc 的 src pad 支持哪些 Caps
gst-inspect-1.0 videotestsrc | grep -A 20 "Src pads"

# 查看 xvimagesink 的 sink pad 支持哪些 Caps
gst-inspect-1.0 xvimagesink | grep -A 20 "Sink pads"

方法二：运行时打印 Caps

在管道中插入 fakesink 并设置 dump=true：

gst-launch-1.0 videotestsrc ! fakesink dump=true

这样就能看到实际传输的 Caps 信息。我个人调试时经常用这招，简单粗暴。

方法三：用 GST_DEBUG 环境变量

设置 Caps 相关的调试级别：

GST_DEBUG=GST_CAPS:5 gst-launch-1.0 videotestsrc ! autovideosink

你会看到密密麻麻的协商日志。嗯，信息量很大，但看多了就习惯了。

如何设置 Caps？

设置 Caps 最常用的元件是 capsfilter。它就像一个「过滤器」，强制管道使用你指定的格式。

基本用法

gst-launch-1.0 videotestsrc ! video/x-raw,width=640,height=480 ! autovideosink

这里 video/x-raw,width=640,height=480 就是一个 Caps 过滤器。它告诉上游：我只要 640x480 的原始视频，别的不要。

用 capsfilter 元件

gst-launch-1.0 videotestsrc ! capsfilter caps="video/x-raw,width=1280,height=720" ! autovideosink

你想想看，如果不加这个过滤器，videotestsrc 可能会输出默认的 320x240 分辨率。加了之后，它就乖乖输出 1280x720。

在代码中设置 Caps

如果你写 C 代码，可以这样：

GstCaps *caps;
GstElement *filter;

filter = gst_element_factory_make("capsfilter", "myfilter");
caps = gst_caps_new_simple("video/x-raw",
                           "format", G_TYPE_STRING, "I420",
                           "width", G_TYPE_INT, 1920,
                           "height", G_TYPE_INT, 1080,
                           NULL);
g_object_set(filter, "caps", caps, NULL);
gst_caps_unref(caps);

小技巧：我建议你在写管道时，尽量在关键位置加上 capsfilter。特别是涉及到硬件编解码器的时候，固定格式能避免很多莫名其妙的协商失败问题。比如硬解码器只支持 NV12 格式，你最好在它前面强制转成 NV12。

Caps 协商的常见问题

问题 原因 解决方法
管道启动报错「negotiation failed」 两个 pad 的 Caps 没有交集 检查双方的 Caps，用 capsfilter 强制指定中间格式
视频播放花屏 Caps 协商成功但格式不匹配 用 fakesink dump=true 查看实际传输的 Caps
性能突然下降 协商到了低效的格式（比如 RGB 转 YUV 多次转换） 用 capsfilter 固定为硬件友好的格式
硬解码器不工作 输入格式不是硬件支持的 Caps 查看硬解码器的 Caps，用 videoconvert 转换格式

说实话，Caps 协商是 GStreamer 里最容易踩坑的地方之一。我刚开始做硬件编解码整合时，80% 的调试时间都花在 Caps 上。但一旦你理解了它的机制，后面就顺了。

最后送你一句话：遇到管道问题，先查 Caps。这是我在无数次踩坑后总结出来的血泪教训。

← 上一章 📖 返回目录 下一章 →