4、第一个GStreamer程序：从命令行到Python绑定

好，咱们正式开始动手了。这一章我带你写第一个GStreamer程序。别紧张，我们先用命令行工具试试水，再过渡到Python绑定。最后，我会聊聊那个让很多新手头疼的状态机。

我个人习惯，学一个新框架，先看它能不能跑起来。GStreamer最方便的就是gst-launch-1.0这个命令行工具。它就像一把瑞士军刀，调试、验证、快速原型，都靠它。

4.1 使用gst-launch-1.0播放音频文件

先来个最简单的。播放一个MP3文件，命令长这样：

gst-launch-1.0 filesrc location=test.mp3 ! decodebin ! audioconvert ! autoaudiosink

这条命令干了什么？说白了，就是一条流水线：

• filesrc：从文件读取数据。指定location属性告诉它文件路径。
• decodebin：自动检测格式并解码。MP3、AAC、WAV它都能处理。
• audioconvert：转换音频格式，确保后面的设备能认。
• autoaudiosink：自动选择音频输出设备，比如扬声器。

每个部分用感叹号!连接，数据从左往右流。我在项目中经常用这个命令快速验证音频文件是否损坏。有一次客户说文件播不了，我一跑这条命令，发现是文件头坏了，根本不是GStreamer的问题。

4.2 使用gst-launch-1.0播放视频文件

视频播放稍微复杂一点，因为要处理视频和音频两条流。命令如下：

gst-launch-1.0 filesrc location=test.mp4 ! decodebin name=decoder \
  decoder. ! queue ! videoconvert ! autovideosink \
  decoder. ! queue ! audioconvert ! autoaudiosink

这里用到了decodebin的name属性。它把解码后的视频和音频分成了两个分支：

• 视频分支：videoconvert转换格式，autovideosink显示窗口。
• 音频分支：audioconvert转换格式，autoaudiosink播放声音。

每个分支前加了个queue。为什么？因为视频和音频处理速度不一样。没有队列，视频卡一下，音频就断了。我曾经在一个嵌入式项目里忘了加queue，结果画面和声音完全不同步，排查了半天才发现是这个问题。

4.3 使用Python绑定创建简单管道

命令行虽好，但做不了复杂逻辑。这时候就需要Python绑定了。GStreamer的Python绑定叫PyGObject，它直接调用底层C库。

先安装依赖：

pip install pygobject

然后写一个最简单的播放器：

import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst, GLib

# 初始化GStreamer
Gst.init(None)

# 创建管道
pipeline = Gst.parse_launch(
    "filesrc location=test.mp3 ! decodebin ! audioconvert ! autoaudiosink"
)

# 开始播放
pipeline.set_state(Gst.State.PLAYING)

# 创建主循环，保持程序运行
loop = GLib.MainLoop()
try:
    loop.run()
except KeyboardInterrupt:
    # 按Ctrl+C退出
    pipeline.set_state(Gst.State.NULL)
    loop.quit()

这段代码做了几件事：

1. 导入GStreamer和GLib库。
2. 用Gst.parse_launch解析命令行风格的管道字符串。
3. 设置状态为PLAYING，开始播放。
4. 启动GLib主循环，让程序持续运行。

你想想看，这和命令行本质上是一样的。但Python版本可以加错误处理、用户交互、动态调整参数。我在做语音助手项目时，就是用Python绑定实时切换音频源，命令行根本做不到。

4.4 理解状态机：NULL、READY、PAUSED、PLAYING

GStreamer里每个元素都有状态。状态机是理解管道行为的关键。说白了，就是元素在生命周期里会经历几个阶段：

状态	含义	典型行为
NULL	初始状态，未分配资源	刚创建时就是这个状态
READY	已打开设备，但未开始处理	打开文件、分配内存
PAUSED	数据流已就绪，但时钟暂停	缓冲区填满，等待播放指令
PLAYING	正常播放，时钟运行	数据从源头流到接收端

状态切换是严格有序的：NULL → READY → PAUSED → PLAYING。反过来也一样，停止时逐级下降。你不能直接从NULL跳到PLAYING，GStreamer会帮你自动过渡，但理解这个过程对调试很有帮助。

举个例子。当你调用pipeline.set_state(Gst.State.PLAYING)时，GStreamer内部会：

1. 从NULL到READY：打开文件，分配缓冲区。
2. 从READY到PAUSED：开始读取数据，填满管道。
3. 从PAUSED到PLAYING：启动时钟，开始播放。

我曾经遇到一个坑：在READY状态下修改元素属性，结果管道卡住了。后来才发现，有些属性只能在NULL或READY状态下修改，PAUSED之后就不让动了。嗯，这里要注意，改属性前先检查状态。

状态机还有一个重要概念：状态变更的异步性。你调用set_state后，状态不会立刻改变。GStreamer会在后台线程里处理，完成后发送state-changed消息。所以，如果你在set_state后马上查询状态，可能还是旧值。正确的做法是监听消息总线。

好了，这一章的内容就这些。你学会了用命令行播放音频和视频，用Python写第一个管道，还理解了状态机的基本原理。下一章，我会带你深入消息总线，看看怎么捕获错误和状态变化。