【Gstreamer 11】基础教程之调试工具

最新推荐文章于 2025-06-11 00:25:12 发布

原创最新推荐文章于 2025-06-11 00:25:12 发布 · 981 阅读

28 ·

CC 4.0 BY-SA版权

文章标签：

#linux #音视频 #媒体

开源库学习专栏收录该内容

25 篇文章

订阅专栏

官网地址

Basic tutorial 11: Debugging tools

一、目标

有时事情不会按预期进行，从总线检索到的错误消息（如果有的话）可能无法提供足够的信息。幸运的是，GStreamer 提供了大量的调试信息，这些信息通常可以提示问题的可能原因。本教程展示了：

如何从 GStreamer 获取更多调试信息。
如何将自己的调试信息打印到 GStreamer 日志中。
如何获取管道图。

二、打印调试信息

2.1、调试日志

GStreamer 及其插件充满了调试跟踪信息，这些信息是代码中特别有趣的部分，会打印到控制台，并附带时间戳、进程、类别、源代码文件、函数和元素信息。

调试输出由 GST_DEBUG 环境变量控制。以下是一个 GST_DEBUG=2 的示例：

0:00:00.868050000  1592   09F62420 WARN                 filesrc gstfilesrc.c:1044:gst_file_src_start:<filesrc0> error: No such file "non-existing-file.webm"

如你所见，这些信息非常详细。事实上，GStreamer 的调试日志非常冗长，当完全启用时，可能会导致应用程序无响应（由于控制台滚动）或填满数兆字节的文本文件（当重定向到文件时）。因此，日志被分类，你很少需要一次性启用所有类别。

第一个类别是调试级别，它是一个数字，指定所需的输出量：

要启用调试输出，请将 GST_DEBUG 环境变量设置为所需的调试级别。低于该级别的所有消息也会显示（例如，如果设置为 GST_DEBUG=2，你将同时收到 ERROR 和 WARNING 消息）。此外，每个插件或 GStreamer 的每个部分都定义了自己的调试类别，

因此你可以为每个单独的类别指定调试级别。例如，GST_DEBUG=2,audiotestsrc:6 将为 audiotestsrc 元素使用调试级别 6，而为其他所有类别使用级别 2。

GST_DEBUG 环境变量是一个以逗号分隔的类别:级别对列表，开头可以有一个可选的级别，表示所有类别的默认调试级别。

还可以使用通配符 *。例如，GST_DEBUG=2,audio*:6 将为所有以 audio 开头的类别使用调试级别 6。GST_DEBUG=*:2 等同于 GST_DEBUG=2。

使用 gst-launch-1.0 --gst-debug-help 获取所有已注册类别的列表。请注意，每个插件都会注册自己的类别，因此在安装或删除插件时，此列表可能会发生变化。

当 GStreamer 总线上的错误信息无法帮助你定位问题时，可以使用 GST_DEBUG。通常的做法是将输出日志重定向到文件，然后在稍后检查文件，搜索特定消息。

GStreamer 允许自定义调试信息处理程序，但在使用默认处理程序时，调试输出中每行的内容如下：

0:00:00.868050000  1592   09F62420 WARN                 filesrc gstfilesrc.c:1044:gst_file_src_start:<filesrc0> error: No such file "non-existing-file.webm"

2.2、添加自定义调试信息

在与 GStreamer 交互的代码部分中，使用 GStreamer 的调试工具非常有用。这样，你可以将所有调试输出保存在同一个文件中，并保留不同消息之间的时间关系。

为此，可以使用 GST_ERROR()、GST_WARNING()、GST_INFO()、GST_LOG() 和 GST_DEBUG() 宏。它们接受与 printf 相同的参数，并使用默认类别（默认类别在输出日志中显示为 Debug 类别）。

要将类别更改为更有意义的名称，请在代码顶部添加以下两行：

GST_DEBUG_CATEGORY_STATIC (my_category);
#define GST_CAT_DEFAULT my_category

然后在初始化 GStreamer（使用 gst_init()）后添加以下代码：

GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");

这将注册一个新类别（仅在你的应用程序运行期间有效：不会存储在任何文件中），并将其设置为代码的默认类别。有关 GST_DEBUG_CATEGORY_INIT() 的详细信息，请参阅文档。

2.3、获取管道图

当你的管道变得过于复杂，难以跟踪连接关系时，GStreamer 可以生成图文件。这些是 .dot 文件，可以使用 GraphViz 等免费程序查看，描述管道的拓扑结构以及每个链接中协商的 Caps。

这对于使用 playbin 或 uridecodebin 等一体化元素非常有用，因为它们内部实例化了多个元素。使用 .dot 文件可以了解它们在内部创建的管道结构（同时学习一些 GStreamer 知识）。

要生成 .dot 文件，只需将 GST_DEBUG_DUMP_DOT_DIR 环境变量设置为希望保存文件的文件夹路径。gst-launch-1.0 会在每次状态更改时创建一个 .dot 文件，因此你可以看到 Caps 协商的演变过程。取消设置该变量以禁用此功能。在你的应用程序中，可以使用 GST_DEBUG_BIN_TO_DOT_FILE() 和 GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS() 宏按需生成 .dot 文件。

以下是 playbin 生成的管道图示例。它非常复杂，因为 playbin 可以处理许多不同的情况：你的手动管道通常不需要这么长。如果你的手动管道开始变得非常庞大，请考虑使用 playbin。