企业官网建设流程全解析

如果你已经跟着前面的开发记录把 GStreamer 的基础玩法摸熟了，比如会用 gst-launch-1.0 拼管线，能顺手创建 pipeline 跑通文件，那我猜你现在八成正卡在这件事上：怎么把输出的画面弄到自己写的界面上，顺便搞明白那些稀奇古怪的 caps 到底是什么玩意儿。这两个问题在 GStreamer 开发记录系列里分别对应第五和第六篇，我在实际接手一个上位机视频预览功能时，把它们合并消化了，因为工程里它们就是绑在一起出现的：你要把视频显示到窗口里，就必须理解 sink 和界面框架的关系；你要让画面正常出来，就绕不开 caps 协商。这篇文章把这两块内容串起来讲，从 GUI 集成的几种主流方案，到 Caps 协商的底层机制，再到一套能直接跑的 Qt 示例，最后附上问题排查表，适合正在做播放器、视频预览工具或者各类流媒体上位机的开发者参考。

1. 为什么 GUI 集成和 Caps 协商是 GStreamer 开发的两道坎

1.1 从"能跑命令行"到"能显示到界面"的差距

先说说我自己最初的挫败感。命令行下跑一个gst-launch-1.0 videotestsrc ! autovideosink非常简单，画面一闪就出来了，似乎没什么需要动脑的地方。可一旦换成自己的程序，用gst_element_factory_make创建同样的管线，问题就来了：要么窗口一片黑，要么程序直接崩，要么画面出来了但刷新率明显不对。命令行工具帮我们隐藏了太多细节，autovideosink会自己选择合适的视频 sink，会自己处理窗口创建，甚至会在 Wayland 和 X11 之间自动切换。到了自研 GUI 里，这些"自动"全部失效，你必须手动回答三个问题：用哪个 sink、窗口句柄怎么给、画面怎么同步到界面线程。

GUI 集成最难的地方不在 GStreamer 本身，而在"两个系统怎么交接口径一致"。GStreamer 的视频渲染线程和 Qt 或 GTK 的界面线程是两套独立的东西，视频帧从解码器出来以后，sink 负责把它交给显示系统，但显示系统并不知道你的窗口长什么样。这就需要一个交接过程，而这个过程在不同平台、不同界面框架下的做法完全不同。这也是为什么 GUI 集成教程在网上一搜一大把，但大多只覆盖一种环境，换个窗口系统就失效。

1.2 两者之间的隐藏关联

GUI 集成和 Caps 协商看着是两个话题，实际是一条链上的两个环节。视频 sink 接收数据之前，上游必须和它协商好视频格式，sink 说自己只收video/x-raw, format=BGRA, width=1920, height=1080，而上游给的是 NV12 或者别的格式，协商立刻失败，画面自然出不来。很多黑屏问题，根子上其实不是窗口句柄给错了，而是 sink 的 caps 和上游不匹配。

反过来说，Caps 协商也不只是纯格式层面的"纸上谈兵"，它最终决定了数据在 CPU、GPU、显存之间的搬运方式。比如你想用零拷贝的方式把视频帧直接送进 GPU 纹理，那 caps 里就得带GST_CAPS_FEATURE_MEMORY_DMAP之类的特性标识；而你的窗口绘制 API 如果根本不认这类内存，协商出来的 caps 再"高级"也没用。所以这两个知识点必须放在一起学，单独看任何一个都很容易陷入误区。

2. GUI 集成实战：把视频画面请进你的程序窗口

2.1 先搞懂几种主流 sink 方案

先明确一个概念：GStreamer 里负责"把帧渲染出来"的元素统称 video sink，常见的有autovideosink、xvimagesink、ximagesink、waylandsink、gtksink、gtkglsink、qmlglsink、appsink等。它们的工作方式可以粗暴分成两类：自绘型和回调型。

自绘型 sink 自己会创建一个原生窗口或嵌入现有窗口，典型的如xvimagesink（X11 环境下用 XVideo 扩展渲染）、waylandsink（Wayland 合成器渲染）、gtksink（包一个 GtkWidget 给你）。这类 sink 渲染效率最高，因为视频帧直接在显示层合成，没有跨层拷贝。缺点是和界面框架耦合紧，比如gtksink你用不了在 Qt 里，waylandsink需要窗口系统是 Wayland。

回调型 sink 的代表是appsink。它不负责渲染，只把视频帧以一个一个GstSample的形式通过信号回调交给你的程序，你想拿它干嘛都行：转成 QImage 画到 QWidget 上、丢给 OpenGL 上传纹理、甚至直接做算法处理。代价是方案比较底层，要在应用层处理格式转换、线程同步、丢帧策略，效率也比自绘 sink 差一些，但胜在通用性极强。

还有一个容易被忽视的方案是gst_video_overlay_set_window_handle系列接口，它适用于支持"嵌入外部窗口"的 sink（X11 下的 ximagesink/xvimagesink 是主力）。你把你程序里一个控件的原生窗口 ID 塞给 GStreamer，sink 就直接在你那个控件的位置上渲染视频。这个方案在 Qt 和 GTK 里都有过广泛使用，但在 Wayland 下基本失效，因为 Wayland 安全模型不允许客户端随便把别人的窗口嵌进来。

2.2 Qt 工程实操：从 Pipeline 到 QImage

我这次在项目里用的是 Qt 6 + appsink 的方案，原因很简单：目标设备有的走 X11，有的走 Wayland，还有的是嵌入式环境，自绘 sink 无法统一覆盖。appsink 这套只要 Qt 能画图就能用。核心思路是：管线末端挂 appsink，设置好输出 caps，让管线跑在独立线程里，每当 appsink 收到一帧就发 Qt 信号，主窗口收到信号后把 QImage 刷新出来。

先看管线构建部分：

// pipeline_builder.cpp GstElement *pipeline = gst_pipeline_new("video_pipeline"); GstElement *src = gst_element_factory_make("filesrc", "src"); GstElement *demux = gst_element_factory_make("qtdemux", "demux"); GstElement *decodebin = gst_element_factory_make("decodebin", "decoder"); GstElement *convert = gst_element_factory_make("videoconvert", "convert"); GstElement *sink = gst_element_factory_make("appsink", "appsink0"); g_object_set(src, "location", "/path/to/video.mp4", NULL); // 关键是让 appsink 输出 BGRA，Qt 的 QImage::Format_RGB32 正好对应 GstCaps *sink_caps = gst_caps_from_string( "video/x-raw, format=BGRA, framerate=0/1" ); g_object_set(sink, "caps", sink_caps, "max-buffers", 4, "drop", TRUE, "sync", FALSE, NULL); gst_caps_unref(sink_caps); gst_bin_add_many(GST_BIN(pipeline), src, demux, decodebin, convert, sink, NULL); gst_element_link(src, demux); // demux 到 decodebin 是动态连接，见后面第 4 节

这里面drop=TRUE和max-buffers=4是经验值。appsink 内部有一个缓冲队列，如果解码速度快于界面消费速度，队列会越积越长，延迟越来越大。设置最大缓冲数和丢帧策略后，队列满了就丢新帧保旧帧，画面延迟能压在一个可接受的范围。播放视频这种场景用drop=TRUE没问题，但如果你做的是录屏或逐帧分析，就得改成drop=FALSE并调大缓冲数，否则会丢关键帧。

接着拿到采样数据，转换成 QImage：

// video_receiver.cpp static void on_new_sample(GstElement *sink, gpointer user_data) { VideoReceiver *self = static_cast<VideoReceiver *>(user_data); GstSample *sample = gst_app_sink_pull_sample(GST_APP_SINK(sink), NULL); if (!sample) return; GstCaps *caps = gst_sample_get_caps(sample); GstVideoInfo info; if (!gst_video_info_from_caps(&info, caps)) { gst_sample_unref(sample); return; } GstBuffer *buffer = gst_sample_get_buffer(sample); GstMapInfo map; if (gst_buffer_map(buffer, &map, GST_MAP_READ)) { QImage image(map.data, info.width, info.height, info.stride[0] ? info.stride[0] : info.width * 4, QImage::Format_RGB32); emit self->frameReady(image.copy()); // 注意必须 copy gst_buffer_unmap(buffer, &map); } gst_sample_unref(sample); }

有一个细节必须提醒：QImage用map.data构造时是浅拷贝，数据区归 GStreamer 管，而信号是异步的，等主线程真正画图时这块内存可能已经被 Sink 回收了。所以发信号前必须image.copy()深拷贝一份，或者改用QImage::Format_RGB32后立刻把像素拷进自己的缓冲区。这一步漏掉的结果是画面随机花屏、闪烁，而且极难复现，排查起来非常痛苦。

2.3 传统 X11 路线：Overlay 窗口嵌入

如果你的目标平台明确是 X11，并且没有 Wayland 的顾虑，用xvimagesink加 overlay 嵌入是效率最高的方案。核心代码很简短：

GstElement *sink = gst_element_factory_make("xvimagesink", "video_sink"); // 你必须拿到 QWidget 的原生窗口句柄 guintptr win_id = (guintptr)ui->videoWidget->winId(); gst_video_overlay_set_window_handle(GST_VIDEO_OVERLAY(sink), win_id); // 注意时序：必须在 pipeline 进入 PLAYING 之前设置 gst_element_set_state(pipeline, GST_STATE_READY); gst_element_set_state(pipeline, GST_STATE_PLAYING);

最容易踩的坑是把窗口句柄设置放到了 PLAYING 之后。GStreamer 的 video overlay 在进入 READY 状态时查询窗口信息，如果那时句柄还是 0，后续再设置虽然可能生效，但某些驱动下会黑屏或者只在第一次渲染时有效。稳妥的做法是在gst_element_set_state(pipeline, GST_STATE_NULL)之后、GST_STATE_PLAYING之前，先把管线拉到 READY，再设置句柄，再继续播放。另外winId()不能在窗口还没显示的时候调用，否则拿到的句柄不合法。

还有一个坑：如果你的 QWidget 启用了合成透明度或者被某些样式表影响，X11 嵌入渲染会出现奇怪的重叠和闪烁。解决办法是把视频控件单独放在一个独立的最上层子窗口里，不要和别的控件做复杂叠加，必要时设置WA_NativeWindow属性强制它拥有独立原生窗口。

2.4 方案对比与选型建议

我的建议很直白：如果是快速原型或者必须跨平台，先上 appsink，把功能跑通再说性能；如果目标平台锁定 X11，直接 xvimagesink 嵌入，代码量少一半，性能还好；如果项目基于 GTK，优先 gtksink；基于 Qt6/QML 且画面要跟 UI 做融合特效，再研究 qmlglsink 路线。注意 appsink 输出 BGRA 后 CPU 消耗不小，4K 分辨率下我实测单是要把 RGBA 数据搬到 QImage 就要占掉一个核的相当比例，所以真到高性能需求时，还得回到硬件 sink 或者 GPU 上传路线。

3. Caps 协商机制深度拆解

3.1 Caps 结构：类型、特征与 ANY

Caps（Capabilities）是 GStreamer 里描述数据格式的结构，本质上是一个GstCaps对象，内部包含若干GstStructure，每个 structure 描述一种可能的格式。拿最常见的视频原始格式举例：

video/x-raw, format=(string)BGRA, width=(int)1920, height=(int)1080, framerate=(fraction)30/1

这里的video/x-raw是媒体类型（media type），后面跟的是该类型下的特征字段。音频就是audio/x-raw，压缩视频流则是video/x-h264这种编码类型。Caps 可以是受限的，如上例固定了宽高和帧率；也可以是宽松的，比如video/x-raw, format=BGRA没指定分辨率，代表任意分辨率下都接受 BGRA；还可以是完全通配的ANY，代表任何格式都接受，一般只在新建元素时用作默认值。

必须理解的一点是：caps 不只是"格式描述"，还包含可选的 caps features。features 带在媒体类型之前，像这样：

memory:DMABuf, video/x-raw, format=BGRA

它表示这段数据是用 DMABuf 内存承载的，下游如果要零拷贝访问 GPU 内存，就必须认可这个 feature。日常开发里，videoconvert这类元素会把 caps features 抹掉，输出一份普通内存的格式，所以加了它之后很多 GPU 加速的链路就断了，但换来的是格式转换的自由度。这个 trade-off 要心里有数。

3.2 协商流程：link 时与运行时的两阶段

Caps 协商有两个阶段，理解这两个阶段能解释大部分报错。第一阶段是元素连接（link）时：你用gst_element_link把两个元素连起来，框架会询问两个 pad 的模板，尝试找一组两者都能接受的 caps。比如videotestsrc的 src pad 支持几十种格式，appsink的 sink pad 模板是ANY，连接时两边一商量，先不固定具体格式，留到运行时再说。

第二阶段是运行时协商：上游元素开始输出数据前，必须确定实际的格式。这时候上游通常先向"协商差点（negotiation point）"发起 caps 事件，常见做法是上游先发一个 caps 事件给下游，下游如果接受就固定下来；如果不接受，下游会返回GST_PAD_LINK_FAILED，管线报not negotiated。这就是为什么很多报错出现在READY转PLAYING那一刻，因为真正的格式敲定发生在进入 PLAYING 后、第一帧数据之前。

从机制实现看，协商是一个"下游提需求、上游做决定"的过程。直接的表述是：下游 sink pad 会把自身支持的格式清单（通常是 query caps）抛给上游，上游在清单里挑一个自己最容易产生的格式，发 caps 事件固定下来。若上游发现清单里没有自己能输出的格式，就只能报协商失败。链路越长、中间元素越多，双方格式的交集可能越小，这也是为什么单纯在命令里加videoconvert就能解决大量协商问题——它把"格式必须完全一致"变成了"格式不一致时我来转换"。

3.3 用 capsfilter 主动干预协商

理解协商之后，你会发现一个常用的干预手段：capsfilter。它的作用就是在链路上强制指定一段 caps，把协商范围压缩到你想要的区域。

gst-launch-1.0 videotestsrc ! video/x-raw,format=I420,width=1280,height=720 ! videoconvert ! autovideosink

videotestsrc与videoconvert之间的video/x-raw,...实际上创建了一个隐式的 capsfilter，要求这一段格式必须是 I420 且 720p。videotestsrc 的输出能力很宽，它会在自己的能力里挑一个满足你 filter 的格式。这种写法比显式声明capsfilter caps=...元素更简洁，GStreamer 的 parse 语法会自动把它转化为一个capsfilter实例，效果完全相同。

工程上 capsfilter 最常用的场景是统一摄像头输入格式。比如你接的 USB 摄像头支持 MJPG、YUY2、NV12 三种格式，但你的算法模块只写了 NV12，那就直接：

v4l2src device=/dev/video0 ! video/x-raw,format=NV12,width=1280,height=720,framerate=30/1 ! videoconvert ! ...

注意，你约定的格式必须落在上游元素的能力范围内。如果上游输出能力里根本没有 NV12 这个选项，negotiation 必然失败。可以用gst-inspect-1.0 v4l2src查看它的 Pad Templates 来确认支持范围，这一步能省掉大量无意义的试错。

3.4 动态协商与重协商

普通静态管线协商一次就完事，但真实工程里虚线场景太多：文件是 mp4，你没法在构建时确定里面是 H.264 还是 H.265，甚至分辨率和帧率都可能在播放过程中变化。GStreamer 的应对方案是动态 pad。典型情况是decodebin：你把它连到一个 demuxer 上，它根据实际流内容动态创建 src pad，再由应用层在pad-added信号里把新 pad 连到下游。

static void on_pad_added(GstElement *element, GstPad *pad, gpointer user_data) { // 拿到下游元素的 sink pad GstElement *convert = (GstElement *)user_data; GstPad *sinkpad = gst_element_get_static_pad(convert, "sink"); // 关键：等 pad 上出现可见 caps 再连，否则你不知道它是什么类型 if (gst_pad_has_current_caps(pad)) { gst_pad_link(pad, sinkpad); } else { // 常见做法是挂一个 probe，等 caps 事件到达后再连 gst_pad_add_probe(pad, GST_PAD_PROBE_TYPE_CAPS, on_caps_probe, sinkpad, NULL); } }

运行时重协商在直播流切换清晰度或者播放器跳转时会触发。这时上游会把新的 caps 发下来，下游如果不能接受就必须动态改变自身状态。videoconvert和videoscale这类元素支持运行时换格式，所以它们在动态链路中几乎是必加的。我自己遇到过最典型的坑是：用playbin播放一个视频，播到一半后续视频流从 1080p 换成了 480p，如果链路里没有videoscale，下游解码后直接塞给固定 1080p 的 sink，画面就被拉伸或者直接协商失败报错。

4. 完整示例：Qt 视频播放器 + 状态监控

4.1 环境准备与工程配置

我这次的实验环境是 Ubuntu 22.04，GStreamer 1.22，Qt 6.4，编译工具 CMake。需要安装的包：

sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \ gstreamer1.0-plugins-ugly qt6-base-dev

这里有个认知点：开发头文件属于-dev包，具体的编解码实现在-plugins-good/bad/ugly里。如果程序编译过了但运行时报找不到某个 element，十有八九是插件包没装全。排查命令是gst-inspect-1.0 元素名，能查到就是已安装。

工程结构不用复杂，一个main.cpp负责创建 QApplication 和主窗口，一个VideoReceiver类封装 GStreamer 管线并发出帧信号，一个MainWindow显示 QImage。注意 GStreamer 的初始化gst_init要放在 Qt 的QApplication构造之前还是之后？实践上没有强制顺序，但我习惯在main一开始调用gst_init(NULL, NULL)，避免后续一些插件加载时机的问题。

4.2 构建管线与 Caps 日志打印

我测试时故意构造了一个容易出现协商问题的场景：文件源是 mp4，里面是 H.264，我们要在界面上显示 BGRA。管线是：

filesrc -> qtdemux -> decodebin -> videoconvert -> appsink

为了让调试过程更直观，我在关键点插入了自定义的 pad probe 打印 caps：

static GstPadProbeReturn print_caps(GstPad *pad, GstPadProbeInfo *info, gpointer data) { GstCaps *caps = gst_pad_get_current_caps(pad); if (caps) { gchar *caps_str = gst_caps_to_string(caps); g_print("caps: %s\n", caps_str); g_free(caps_str); gst_caps_unref(caps); } return GST_PAD_PROBE_OK; } // 挂到 videoconvert 的 sink pad 上，观察解码后的格式 GstPad *convert_sink = gst_element_get_static_pad(convert, "sink"); gst_pad_add_probe(convert_sink, GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM, print_caps, NULL, NULL);

GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM会捕捉流经该 pad 的 caps 等相关事件，这比单纯看终端日志多一层"视角"。开发阶段我习惯在 pipeline 的每个关键转换点都挂上这种打印，等系统稳定了再去掉。可以看到 H.264 解码后大概率输出video/x-raw的 NV12 或 I420 格式，然后经过 videoconvert 转成 BGRA 给 appsink。

4.3 动态 Pad 连接与异常处理

真正写程序的时候，那行gst_element_link(demux, decodebin)是不能静态连接的，因为 qtdemux 在读取文件头之前不知道里面有什么流。正确的做法是只连filesrc -> qtdemux，在 qtdemux 的pad-added信号里把新 pad 连到 decodebin。decodebin 自己还会再产生新的动态 pad，再往上连到 videoconvert。

我封装了一个递归处理的函数，核心逻辑是：所有动态 pad 统一走on_pad_added，判断 caps 类型，视频流才连到下游，音频流另接音频链路，同时做好失败重试的兜底：

static gboolean try_link_pad(GstPad *srcpad, GstElement *downstream) { GstPad *sinkpad = gst_element_get_static_pad(downstream, "sink"); if (!sinkpad || !gst_pad_is_linked(sinkpad) && gst_pad_link(srcpad, sinkpad) != GST_PAD_LINK_OK) { gst_object_unref(sinkpad); return FALSE; } gst_object_unref(sinkpad); return TRUE; }

异常处理方面，主循环里要监听 bus 消息。特别是GST_MESSAGE_ERROR和GST_MESSAGE_EOS。GStreamer 里很多错误是异步抛出的，不在创建管线的函数里，而在运行中。如果你不在 bus 上处理 error，程序可能毫无提示地退出或者卡死。我的习惯是单独起一个定时器或线程去gst_bus_timed_pop_filtered，把 error 和 warning 打出来，同时把 state change 消息也存一份，这样出问题时能看到到底是哪个环节的状态切换失败。

5. 常见问题速查表与排查实录

5.1 黑屏、花屏、延迟异常的典型现象

花屏这个坑我特别想多说一句。QImage::Format_RGB32在内存里是小端序的0xAARRGGBB，而 GStreamer 里常见的BGRA和RGBA都会让新手晕头。摄像头默认很可能是YUY2，你转成BGRA之后喂给 Qt，如果 Qt 侧用了Format_RGB32，通道顺序正好反了，画面呈现一种诡异的蓝绿色调或者彩色条纹。排查这类问题最快的方式是先用gst-launch-1.0加videotestsrc输出已知测试画面，如果测试源也花屏，那就是格式定义错了，跟数据源无关。

5.2 Caps 协商失败的核心报错解读

最常见的报错是not negotiated，完整信息一般是：

ERROR pipeline: Internal data stream error ERROR pipeline: not negotiated

这意味着某个 pad 在发送数据时还没有成功确定 caps。根因大多是两种：一是两个元素连上了但找不到公共格式，比如把v4l2src直接连到仅支持video/x-raw的下游，而摄像头只输出压缩格式image/jpeg；二是根本没有把 pad 连起来，动态 pad 的pad-added回调里你没做连接，上游流动数据时下游不存在。

另一种高频报错是could not link。运行gst-launch时，如果两个元素之间没有任何一种共同 caps，GStreamer 会在命令行里直接拒绝连接：

WARNING: erroneous pipeline: could not link element1 to element2

解决套路几乎固定：在中间插入videoconvert（格式转换）和videoscale（分辨率缩放），必要时再加上capsfilter限制你真正需要的范围。我见过不少新手从头到尾只用一个autovideosink，一旦改用自己的固定 caps sink 就报错，其实不是 sink 的问题，而是链路里少了转换元素。

5.3 调试三板斧：GST_DEBUG / gst-inspect / gst-launch

遇到问题先别急着改代码，三板斧走一遍能省一半时间。第一斧是用GST_DEBUG环境变量开详细日志：

GST_DEBUG=*:3 ./your_application GST_DEBUG=caps:5,*.negotiation:5 ./your_application

*:3是 WARNING 级别，能看绝大部分显性错误；caps:5可以让 caps 协商日志打得非常详细，从每个 pad 的候选清单到最终选择结果都会打出来。你会直观看到下游抛出的 query 和上游的答复，协商失败的原因一目了然。

第二斧是gst-inspect-1.0，查元素能力范围。开发前先花两分钟：

gst-inspect-1.0 videotestsrc | grep -A 20 "Pad Templates"

看看元素 src pad 模板支持的格式列表，再对照你自己的 capsfilter 是否越界。第三斧是gst-launch-1.0，用命令行把同样的链路先跑起来。命令行能跑通而程序跑不通，问题大概率在程序侧的设置；命令行也跑不通，问题在链路和元素本身。这一步能把"我的代码问题"和"GStreamer 用法问题"迅速区分开。

6. 个人经验与踩坑启示

6.1 关于 Caps 协商的三个反直觉认知

第一个反直觉的地方是：协商成功不代表格式最优。GStreamer 会选一个双方都接受、但未必是效率最高的格式。比如摄像头原始输出 NV12，你却强制协商成 BGRA，中间就得插一个videoconvert，多一次全帧内存拷贝。很多所谓性能问题，根本根源不在解码而在格式链路上多绕了一圈。建议是尽量让整条链路保持同一种格式，不到最后一步不转。

第二个是动态 pad 的时序问题永远不能靠"猜"。我曾经在pad-added回调里直接gst_pad_link，偶发失败，查了两天才意识到当时 pad 上还没有 caps，下游无法判断要不要这个流。后来改成先挂 probe 等 caps 到达再接，问题才稳定解决。动态场景里，永远假设事件到达顺序和你预期的不一样。

第三个是 "playing 状态下最好不要动 caps"。运行中直接改 capsfilter 或重新 link 是危险行为，轻则丢帧，重则死锁。如果确实要改分辨率或帧率，规范姿势是先暂停管线、改结构、再恢复播放。我自己做分辨率动态切换时走了不少弯路，最后就老老实实GST_STATE_PAUSED等异步状态切换完成再改。

6.2 GUI 集成的一条最实用建议

如果只让我留一条建议，那一定是：把 GStreamer 线程和 GUI 线程彻底分开，用信号槽或者线程安全队列传递视频帧，不要试图在 GStreamer 回调里直接画图。我在早期图省事，直接在new-sample回调里调用QLabel::setPixmap，结果就是随机崩溃和界面卡顿。Qt 的 GUI 操作必须在主线程，而 GStreamer 的回调跑在它自己的流线程里，两者并发操作同一个控件，崩溃只是时间问题。改成emit frameReady(image.copy())之后，主线程通过队列接收，帧率稳定了，崩溃也消失了。

还有一个小细节值得提：appsink 的sync=FALSE会让帧不按时间戳等待直接交给应用，低延迟效果好，但如果源视频本身就是 30fps，而界面刷新跟不上，画面会显得"跳"。这时可以保留时间戳，在应用层用定时器限制刷新率，或者干脆接受丢帧，毕竟视频预览场景里，延迟比帧率更重要。

这段开发记录写到这，其实想表达的核心就一句：GUI 集成和 Caps 协商这两个话题，看着是 GStreamer 的进阶内容，实际是每个正经做应用的开发者绕不过去的基本功。工具链再抽象、封装再完善，底层这两个概念不懂，遇到黑屏和报错就只会盲试。把上面的机制理清楚，再拿着示例代码去改自己的工程，你会发现自己突然能看懂那些以前完全没头绪的报错日志了。