4. GStreamer 基本 Pipeline：创建第一个 Pipeline、文件播放、视频显示、音频输出

好，咱们进入实战环节。前面聊了那么多 H.265 的理论和 GStreamer 的架构，今天终于要动手了。这一章的目标很简单——让你亲手跑起来一个完整的 Pipeline，看到画面、听到声音。

我个人习惯，学一个新框架，先别急着啃文档。先搭一个最简单的链路，跑通了再说。GStreamer 的学习曲线其实挺陡的，但一旦你理解了 Pipeline 的“乐高”哲学，后面就顺了。

4.1 什么是 Pipeline？

Pipeline，说白了就是一条“数据流水线”。数据从源头进来，经过一个个处理节点，最后输出。每个节点叫 Element（元素），节点之间的连接叫 Pad（垫片）。

你想想看，这跟工厂里的传送带一模一样。原料从一头进去，经过清洗、切割、包装，最后成品出来。GStreamer 的 Pipeline 也是这个道理——视频流从文件或摄像头进来，经过解码、颜色空间转换、缩放，最后送到显示器。

我在项目中遇到过不少新手，直接用 gst-launch-1.0 拼命令，跑通了就以为懂了。其实真正重要的是理解 Pipeline 内部的 状态机 和 数据流。咱们后面会细讲，今天先感性认识一下。

4.2 创建第一个 Pipeline

GStreamer 提供了两种方式创建 Pipeline：命令行工具 gst-launch-1.0 和编程 API。咱们先从命令行入手，因为它最直观。

4.2.1 用 gst-launch-1.0 搭建 Pipeline

打开终端，输入下面这条命令：

gst-launch-1.0 videotestsrc ! autovideosink

如果一切正常，你会看到一个彩色的测试图案窗口。这就是你的第一个 Pipeline！

我们来拆解一下这条命令：

• videotestsrc：一个测试视频源，生成彩条、雪花等测试图案。调试时特别好用。
• !：管道符，表示数据从左边流向右边。
• autovideosink：自动选择合适的视频输出方式（X11、Wayland、Windows 窗口等）。

就这么简单？对，就这么简单。GStreamer 的设计哲学就是“组合优于继承”，Element 之间通过 Pad 协商格式，自动完成适配。

4.2.2 给 Pipeline 加点参数

Element 可以设置属性。比如让测试图案变成雪花：

gst-launch-1.0 videotestsrc pattern=2 ! autovideosink

pattern=2 就是设置 videotestsrc 的 pattern 属性为 2（雪花模式）。每个 Element 都有自己的一组属性，可以用 gst-inspect-1.0 videotestsrc 查看。

嗯，这里要注意：属性名和值之间用等号，不要加空格。这是 GStreamer 命令行解析的一个小坑。

4.3 文件播放：从本地文件读取视频

测试图案看够了，咱们来播一个真正的视频文件。假设你有一个 MP4 文件 test.mp4：

gst-launch-1.0 filesrc location=test.mp4 ! qtdemux ! h264parse ! avdec_h264 ! autovideosink

这条 Pipeline 做了这些事：

1. filesrc：从文件系统读取数据，输出原始字节流。
2. qtdemux：解复用器，把 MP4 容器拆成视频流和音频流。这里只取了视频流。
3. h264parse：解析 H.264 码流，把数据包切成帧。
4. avdec_h264：用 FFmpeg 的 H.264 解码器解码。
5. autovideosink：显示画面。

等一下，你可能注意到了——我们课程讲的是 H.265，这里怎么用 H.264？别急，我只是先用 H.264 演示通用流程。换成 H.265 只需要把 h264parse 换成 h265parse，avdec_h264 换成 avdec_h265：

gst-launch-1.0 filesrc location=test.mp4 ! qtdemux ! h265parse ! avdec_h265 ! autovideosink

4.4 视频显示：理解视频输出链路

视频显示不是简单的“把像素扔到屏幕上”。GStreamer 的视频输出链路涉及几个关键环节：

环节	作用	常见 Element
颜色空间转换	把解码后的 YUV 转成 RGB	videoconvert, videoscale
帧率控制	匹配显示器的刷新率	videorate
窗口管理	创建窗口、处理事件	ximagesink, waylandsink, autovideosink
同步	音画同步、时钟管理	Pipeline 自动处理

我个人建议，在调试阶段显式加上 videoconvert：

gst-launch-1.0 filesrc location=test.mp4 ! qtdemux ! h265parse ! avdec_h265 ! videoconvert ! autovideosink

为什么？因为 videoconvert 能处理各种颜色空间和像素格式的转换。有些解码器输出的格式，sink 不一定直接支持。加上它，Pipeline 的协商成功率会高很多。我在项目中遇到过不下十次因为缺了 videoconvert 导致 Pipeline 卡在 NEGOTIATING 状态的问题。

4.5 音频输出：让声音响起来

光有画面没声音，那跟看默片似的。咱们把音频也加进来。这里要用到 tee 元素来分流：

gst-launch-1.0 filesrc location=test.mp4 ! qtdemux name=demux \
  demux.video_0 ! queue ! h265parse ! avdec_h265 ! videoconvert ! autovideosink \
  demux.audio_0 ! queue ! aacparse ! avdec_aac ! audioconvert ! autoaudiosink

这条命令有点长，咱们拆开看：

• qtdemux name=demux：给解复用器起个名字，方便后面引用它的输出 Pad。
• demux.video_0：视频流输出。
• demux.audio_0：音频流输出。
• queue：缓冲队列，防止视频和音频互相阻塞。
• aacparse：解析 AAC 音频码流。
• avdec_aac：AAC 解码器。
• audioconvert：音频格式转换。
• autoaudiosink：自动选择音频输出设备。

我曾经在一个项目中，客户抱怨播放 4K H.265 视频时声音断断续续。排查了半天，发现就是 queue 的 size 设得太小。视频解码一卡，音频队列就被饿死了。把 queue 的 max-size-buffers 从默认的 100 调到 500，问题解决。

4.6 Pipeline 状态机：从 NULL 到 PLAYING

Pipeline 不是一创建就开始工作的。它有四个状态：

状态	含义	典型耗时
NULL	初始状态，未分配资源	瞬间
READY	已分配资源，但未打开设备	毫秒级
PAUSED	已打开设备，数据流准备就绪，但未开始播放	取决于解码器初始化
PLAYING	正在播放	持续运行

状态切换是严格按顺序的：NULL → READY → PAUSED → PLAYING。不能跳级。反过来停止时是 PLAYING → PAUSED → READY → NULL。

你可能会问：为什么要有 PAUSED 状态？

嗯，这里有个实际用途。PAUSED 状态下，数据流已经准备好了，但时钟没有启动。你可以在这个状态下做 preroll（预卷），让所有 Element 都拿到第一帧数据。这样从 PAUSED 切换到 PLAYING 时，画面能瞬间出来，不会有黑屏等待。

我在做直播推流时，就利用 PAUSED 状态来做“静默预热”——先把 Pipeline 推到 PAUSED，等所有编码器、封装器都初始化完毕，再切到 PLAYING。这样观众端看到的就是无缝启动。

4.7 本章知识体系

下面这张图总结了本章的核心逻辑：从文件源到音视频输出的完整 Pipeline 结构。

4.8 常见问题与避坑

最后，分享几个我实际踩过的坑：

• Pipeline 卡在 PAUSED 不进入 PLAYING：通常是某个 Element 的 Caps 协商失败。用 GST_DEBUG=*:3 环境变量启动，看日志里有没有 "NEGOTIATING" 相关的错误。
• 有视频没声音：检查音频设备权限。Linux 上用户需要属于 audio 组。我曾在 Docker 容器里折腾了半天，最后发现是 PulseAudio 没启动。
• 播放 H.265 视频花屏：大概率是解码器不支持当前的 Profile/Level。用 gst-inspect-1.0 avdec_h265 查看支持的 Profile。或者换硬件解码器试试。
• 命令行太长不好维护：把 Pipeline 写成 .launch 文件，或者用 Python 的 Gst.parse_launch()。后面章节会讲。