Gstreamer应用开发实战指南(四)

一、GStreamer中的元素

        对于应用程序编程人员来说，GStreamer 中最重要的对象是 GstElement 对象。元素是媒体管道的基本构建基块。我们使用的所有不同的高级组件都派生自 。实际上，每个解码器、编码器、解复用器、视频或音频输出都是GstElement。

什么是元素？

        对于应用程序员来说，元素最好可视化为黑匣子。一方面，你可能会放一些东西进去，元素用它做一些事情，另一边有其他东西出来。例如，对于解码器元素，您将输入编码的数据，该元素将输出解码的数据。

源元素：

        源元素生成供管道使用的数据，例如从磁盘或声卡读取数据。源元素的可视化显示了我们将如何可视化源元素。我们总是在元素的右侧绘制一个源板。

        源元素不接受数据，它们只生成数据。您可以在图中看到这一点，因为它只有一个源板（在右侧）。源板只能生成数据。

        过滤器、转换器、解复用器、复用器和编解码器：

        滤波器和类似滤波器的元件具有输入和输出焊盘。它们对在输入（接收器）焊盘上接收的数据进行操作，并将在其输出（源）焊盘上提供数据。此类元素的示例包括音量元素（过滤器），视频缩放器（转换器），Ogg解复用器或Vorbis解码器。

        类似滤波器的元件可以具有任意数量的源极或灌电流垫。例如，视频解复用器将具有一个沉降垫和多个 （1-N） 源板，容器格式中包含的每个基本流对应一个源板。另一方面，解码器只有一个源和汇垫板。

        过滤器元件的可视化显示了我们将如何可视化类似过滤器的元件。此特定元素有一个源焊盘和一个汇焊盘。接收输入数据的接收器垫被描绘在元件的左侧；源焊盘仍在右侧。

        具有多个输出焊盘的滤波器元件的可视化显示了另一个类似滤波器的元件，该元件具有多个输出（源）焊盘。 例如，一个此类元素的示例可以是用于包含音频和视频的 Ogg 流的 Ogg 解复用器。 一个源板将包含基本视频流，另一个将包含基本音频流。 多路复用器通常会在创建新焊盘时发出信号。 然后应用程序程序员可以在信号处理程序中处理新的基本流。

水槽元素：

        接收器元素是媒体管道中的端点。 他们接受数据但不产生任何东西。 磁盘写入、声卡播放和视频输出都将由 sink 元素实现。 接收器元素的可视化显示了接收器元素。

创建GstElement ：

        创建元素的最简单方法是使用 gst_element_factory_make （）。此函数采用新创建元素的工厂名称和元素名称。例如，元素的名称是以后可用于在 bin 中查找元素的名称。该名称还将用于调试输出。可以使用NULL作为 name 参数传递以获取唯一的默认名称。

        当您不再需要该元素时，您需要使用gst_object_unref （） 将其取消。这会将元素的引用计数减少 1。元素在创建时的引用计数为 1。当引用计数减少到 0 时，元素将被完全销毁。

        下面的示例 [1] 演示如何从名为 fakesrc 的元素工厂创建一个名为 source 的元素。它检查创建是否成功。检查后，它将取消还原元素。

#include <gst/gst.h>

int main (int   argc, char *argv[])
{
  GstElement *element;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* create element */
  element = gst_element_factory_make ("fakesrc", "source");
  if (!element) {
    g_print ("Failed to create element of type 'fakesrc'\n");
    return -1;
  }

  gst_object_unref (GST_OBJECT (element));

  return 0;
}

        gst_element_factory_make实际上是两个函数组合的简写。GstElement 对象是从工厂创建的。若要创建元素，必须使用唯一的工厂名称访问 GstElementFactory 对象。这是通过 gst_element_factory_find （） 完成的。

        以下代码片段用于获取可用于创建 fakesrc 元素（假数据源）的工厂。函数gst_element_factory_create （） 将使用元素工厂创建具有给定名称的元素。

#include <gst/gst.h>

int main (int   argc, char *argv[])
{
  GstElementFactory *factory;
  GstElement * element;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* create element, method #2 */
  factory = gst_element_factory_find ("fakesrc");
  if (!factory) {
    g_print ("Failed to find factory of type 'fakesrc'\n");
    return -1;
  }
  element = gst_element_factory_create (factory, "source");
  if (!element) {
    g_print ("Failed to create element, even though its factory exists!\n");
    return -1;
  }

  gst_object_unref (GST_OBJECT (element));
  gst_object_unref (GST_OBJECT (factory));

  return 0;
}

使用元素作为 GObject：

        一个 GstElement 可以有几个使用标准 GObject 属性实现的属性。 因此支持查询、设置和获取属性值和 GParamSpecs 的常用 GObject 方法。

        每个 GstElement 从其父 GstObject 继承至少一个属性：“名称”属性。 这是我们为函数 gst_element_factory_make () 或 gst_element_factory_create () 提供的名称。 我们可以使用函数 gst_object_set_name 和 gst_object_get_name 获取和设置此属性，或者使用 GObject 属性机制，如下所示。

#include <gst/gst.h>

int main (int   argc, char *argv[])
{
  GstElement *element;
  gchar *name;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* create element */
  element = gst_element_factory_make ("fakesrc", "source");

  /* get name */
  g_object_get (G_OBJECT (element), "name", &name, NULL);
  g_print ("The name of the element is '%s'.\n", name);
  g_free (name);

  gst_object_unref (GST_OBJECT (element));

  return 0;
}

        大多数插件提供附加属性以提供有关其配置或配置元素的更多信息。 gst-inspect 是查询特定元素属性的有用工具，它还将使用属性自省来简要说明属性的功能以及它支持的参数类型和范围。 有关 gst-inspect 的详细信息，请参阅附录中的 gst-inspect。

        有关 GObject 属性的更多信息，我们建议您阅读 GObject 手册和 Glib 对象系统介绍。

        GstElement 还提供了各种可用作灵活回调机制的 GObject 信号。 在这里，您也可以使用 gst-inspect 查看特定元素支持哪些信号。 总之，信号和属性是元素和应用程序交互的最基本方式。

更多关于元素工厂：

        在上一节中，我们已经简要介绍了 GstElementFactory 对象作为创建元素实例的一种方式。 然而，元素工厂远不止这些。 元素工厂是从 GStreamer 注册表中检索到的基本类型，它们描述了 GStreamer 可以创建的所有插件和元素。 这意味着元素工厂对于自动元素实例化非常有用，例如 autopluggers 所做的事情，以及创建可用元素的列表。

使用工厂获取有关元素的信息：

        gst-inspect 之类的工具将提供有关元素的一些通用信息，例如编写插件的人、描述性名称（和短名称）、等级和类别。 类别可用于获取可以使用此元素工厂创建的元素的类型。 类别的示例包括 Codec/Decoder/Video（视频解码器）、Codec/Encoder/Video（视频编码器）、Source/Video（视频生成器）、Sink/Video（视频输出），所有这些都存在于音频中 ， 当然。 然后，还有 Codec/Demuxer 和 Codec/Muxer 等等。 gst-inspect 将给出所有工厂的列表，而 gst-inspect <factory-name> 将列出所有上述信息，以及更多信息。

#include <gst/gst.h>

int  main (int   argc, char *argv[])
{
  GstElementFactory *factory;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* get factory */
  factory = gst_element_factory_find ("fakesrc");
  if (!factory) {
    g_print ("You don't have the 'fakesrc' element installed!\n");
    return -1;
  }

  /* display information */
  g_print ("The '%s' element is a member of the category %s.\n"
           "Description: %s\n",
           gst_plugin_feature_get_name (GST_PLUGIN_FEATURE (factory)),
           gst_element_factory_get_metadata (factory, GST_ELEMENT_METADATA_KLASS),
           gst_element_factory_get_metadata (factory, GST_ELEMENT_METADATA_DESCRIPTION));

  gst_object_unref (GST_OBJECT (factory));

  return 0;
}

        我们可以使用 gst_registry_pool_feature_list (GST_TYPE_ELEMENT_FACTORY) 来获取 GStreamer 知道的所有元素工厂的列表。

        找出一个元素可以包含哪些焊盘：

        元素工厂最强大的功能可能是它们包含元素可以生成的 pad 的完整描述，以及这些 pad 的功能（用外行的话来说：哪些类型的媒体可以在这些 pad 上流式传输），而实际上不必 将这些插件加载到内存中。 这可用于为编码器提供编解码器选择列表，也可用于媒体播放器的自动插入目的。 当前所有基于 GStreamer 的媒体播放器和自动插入器都以这种方式工作。 在下一章了解 GstPad 和 GstCaps 时，我们将仔细研究这些特性： 焊盘和功能。

链接元素：

        通过将源元素与零个或多个类似过滤器的元素以及最后一个接收器元素链接，您可以设置媒体管道。 数据将流经元素。 这是 GStreamer 中媒体处理的基本概念。

         通过链接这三个元素，我们创建了一个非常简单的元素链。 这样做的效果是源元素的输出将用作类似过滤器的元素的输入。 类似过滤器的元素将对数据进行处理并将结果发送到最终的接收器元素。

        将上图想象成一个简单的 Ogg/Vorbis 音频解码器。 源是从磁盘读取文件的磁盘源。 第二个元素是 Ogg/Vorbis 音频解码器。 sink 元素是你的声卡，播放解码的音频数据。 我们将在本手册后面使用这个简单的图表来构建一个 Ogg/Vorbis 播放器。

        在代码中，上图是这样写的：

#include <gst/gst.h>

int  main (int   argc,  char *argv[])
{
  GstElement *pipeline;
  GstElement *source, *filter, *sink;

  /* init */
  gst_init (&argc, &argv);

  /* create pipeline */
  pipeline = gst_pipeline_new ("my-pipeline");

  /* create elements */
  source = gst_element_factory_make ("fakesrc", "source");
  filter = gst_element_factory_make ("identity", "filter");
  sink = gst_element_factory_make ("fakesink", "sink");

  /* must add elements to pipeline before linking them */
  gst_bin_add_many (GST_BIN (pipeline), source, filter, sink, NULL);

  /* link */
  if (!gst_element_link_many (source, filter, sink, NULL)) {
    g_warning ("Failed to link elements!");
  }

[..]

}

        对于更具体的行为，还有函数 gst_element_link () 和 gst_element_link_pads ()。 我们还可以获得对单个焊盘的引用并使用各种 gst_pad_link_* () 函数链接这些焊盘。 有关更多详细信息，请参阅 API 参考。

重要提示：

        我们必须先将元素添加到 bin 或管道，然后才能链接它们，因为将元素添加到 bin 会断开任何现有的链接。 此外，我们不能直接链接不在同一个 bin 或管道中的元素； 如果我们想链接不同层次级别的元素或焊盘，我们将需要使用幻影焊盘（稍后将详细介绍幻影焊盘）。

元素状态：

        创建后，元素实际上还不会执行任何操作。 您需要更改元素状态以使其执行某些操作。 GStreamer 知道4四种元素状态，每种状态都有非常具体的含义。 这4个状态是：

        GST_STATE_NULL：这是默认状态。 在此状态下没有分配任何资源，因此，转换到该状态将释放所有资源。 当元素的引用计数达到 0 并被释放时，元素必须处于此状态。

        GST_STATE_READY：处于就绪状态，一个元素已经分配了它所有的全局资源，即可以保留在流中的资源。 你可以考虑打开设备、分配缓冲区等等。 但是，在这种状态下，流并未打开，因此流位置自动为零。 如果一个流之前打开过，它应该在这个状态下关闭，并且位置、属性等应该被重置。

        GST_STATE_PAUSED：在这种状态下，一个元素已经打开了流，但没有主动处理它。 允许元素修改流的位置，读取和处理数据等，以便在状态更改为 PAUSED 时立即准备播放，但不允许播放会使时钟运行的数据。 总之，PAUSED 与 PLAYING 相同，但没有运行时钟。

进入 PAUSED 状态的元素应该为尽快进入 PLAYING 状态做好准备。 例如，视频或音频输出将等待数据到达并将其排队，以便在状态更改后立即播放。 此外，视频接收器已经可以播放第一帧（因为这还不影响时钟）。 Autopluggers 可以使用相同的状态转换来将管道连接在一起。 然而，大多数其他元素，例如编解码器或过滤器，不需要在此状态下显式执行任何操作。

        GST_STATE_PLAYING：在 PLAYING 状态下，元素的行为与 PAUSED 状态完全相同，只是时钟现在运行。

        我们可以使用函数 gst_element_set_state () 更改元素的状态。 如果将一个元素设置为另一个状态，GStreamer 将在内部遍历所有中间状态。 因此，如果我们将一个元素从 NULL 设置为 PLAYING，GStreamer 将在内部将该元素设置为 READY 和 PAUSED。

       当移动到 GST_STATE_PLAYING 时，管道将自动处理数据。 它们不需要以任何形式迭代。 在内部，GStreamer 将为它们启动执行此任务的线程。 GStreamer 还将通过使用 GstBus 将消息从管道的线程切换到应用程序自己的线程。 有关详细信息，请参阅总线。

        当您将 bin 或 pipeline 设置为某个目标状态时，它通常会自动将状态更改传播到 bin 或 pipeline 中的所有元素，因此通常只需设置顶级管道的状态即可启动管道 或将其关闭。 但是，当将元素动态添加到已经运行的管道时，例如 在“pad-added”信号回调中，您需要自己使用 gst_element_set_state () 或 gst_element_sync_state_with_parent () 将其设置为所需的目标状态。

        此示例的代码自动从文档中提取并构建在 GStreamer tarball 中的 tests/examples/manual 下。

二、GStreamer中的Bins

        bin 是一个容器元素。 我们可以将元素添加到 bin。 因为 bin 本身就是一个元素，所以可以像处理任何其他元素一样处理 bin。 因此，整个元素的特性也适用于bin。

什么是Bins？

        Bins 允许我们将一组链接元素组合成一个逻辑元素。 我们不再处理单个元素，而只处理一个元素，即 bin。 当我们要构建复杂的管道时，我们将看到这非常强大，因为它允许我们将管道分解成更小的块。

        bin 还将管理其中包含的元素。 它将对元素执行状态更改以及收集和转发总线消息。

 GStreamer 程序员可以使用一种特殊类型的 bin：

        管道：管理所含元素的同步和总线消息的通用容器。 顶层 bin 必须是一个管道，因此每个应用程序至少需要其中一个。

创建一个 bin

        bin 的创建方式与创建其他元素的方式相同，即使用元素工厂。 还有一些方便的函数可用（gst_bin_new () 和 gst_pipeline_new ()）。 要将元素添加到 bin 或从 bin 中删除元素，可以使用 gst_bin_add () 和 gst_bin_remove ()。 请注意，我们添加元素的 bin 将拥有该元素的所有权。 如果我们销毁 bin，该元素将被取消引用。 如果从 bin 中删除元素，它将自动取消引用。

#include <gst/gst.h>

int main (int   argc, char *argv[])
{
  GstElement *bin, *pipeline, *source, *sink;

  /* init */
  gst_init (&argc, &argv);

  /* create */
  pipeline = gst_pipeline_new ("my_pipeline");
  bin = gst_bin_new ("my_bin");
  source = gst_element_factory_make ("fakesrc", "source");
  sink = gst_element_factory_make ("fakesink", "sink");

  /* First add the elements to the bin */
  gst_bin_add_many (GST_BIN (bin), source, sink, NULL);
  /* add the bin to the pipeline */
  gst_bin_add (GST_BIN (pipeline), bin);

  /* link the elements */
  gst_element_link (source, sink);

[..]

}

        （当然，这是一个粗浅的例子，已经存在像这样更强大、更通用的自定义 bin：playbin 元素。）

        可以使用插件或从应用程序创建自定义箱。 我们将在 Plugin Writer's Guide 中找到有关创建自定义 bin 的更多信息。

        此类自定义 bin 的示例是 gst-plugins-base 中的 playbin 和 uridecodebin 元素。

箱管理它们孩子的状态

        箱管理其中包含的所有元素的状态。 如果我们使用 gst_element_set_state () 将 bin（或管道，这是一种特殊的顶级类型的 bin）设置为某个目标状态，它将确保其中包含的所有元素也将设置为该状态。 这意味着通常只需设置顶级管道的状态即可启动或关闭管道。

        bin 将对其所有子元素执行状态更改，从接收元素到源元素。 这确保当上游元素进入PAUSED 或 PLAYING 时，下游元素已准备好接收数据。 同样在关闭时，sink 元素会先设置为 READY 或 NULL，这将导致上游元素收到 FLUSHING 错误并在元素设置为 READY 或 NULL 状态之前停止流线程。

        但是请注意，如果将元素添加到已经运行的 bin 或管道中，例如 在“pad-added”信号回调中，它的状态不会自动与它添加到的 bin 或管道的当前状态或目标状态保持一致。 相反，在将元素添加到已经运行的管道时，我们需要自己使用 gst_element_set_state () 或gst_element_sync_state_with_parent () 将其设置为所需的目标状态。

三、GStreamer中的总线

总线

        总线是一个简单的系统，负责将消息从流式线程转发到其自己的线程上下文中的应用程序。 总线的优点是应用程序不需要线程感知就可以使用 GStreamer，即使 GStreamer 本身是重线程的。

        默认情况下，每个管道都包含一个总线，因此应用程序不需要创建总线或任何东西。 应用程序唯一应该做的就是在总线上设置一个消息处理程序，这类似于一个对象的信号处理程序。 当主循环运行时，会定期检查总线是否有新消息，当有任何消息可用时将调用回调。

如何使用总线

使用总线有两种不同的方式：

        运行 GLib/Gtk+ 主循环（或自己定期迭代默认的 GLib 主上下文）并将某种监测附加到总线上。 这样，GLib 主循环将检查总线是否有新消息，并在有消息时通知我们。

        在这种情况下，通常我们会使用 gst_bus_add_watch () 或 gst_bus_add_signal_watch ()。

        要使用总线，请使用 gst_bus_add_watch () 将消息处理程序附加到管道的总线。 每当管道向总线发出消息时，都会调用此处理程序。 在这个处理程序中，检查信号类型（见下一节）并做相应的事情。 处理程序的返回值应为 TRUE 以保持处理程序连接到总线，返回 FALSE 以将其删除。

        我们也可以使用 gst_bus_peek () 和/或 gst_bus_poll () 来完成自动监测总线上的消息。

#include <gst/gst.h>

static GMainLoop *loop;

static gboolean  my_bus_callback (GstBus * bus, GstMessage * message, gpointer data)
{
  g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));

  switch (GST_MESSAGE_TYPE (message)) {
    case GST_MESSAGE_ERROR:{
      GError *err;
      gchar *debug;

      gst_message_parse_error (message, &err, &debug);
      g_print ("Error: %s\n", err->message);
      g_error_free (err);
      g_free (debug);

      g_main_loop_quit (loop);
      break;
    }
    case GST_MESSAGE_EOS:
      /* end-of-stream */
      g_main_loop_quit (loop);
      break;
    default:
      /* unhandled message */
      break;
  }

  /* we want to be notified again the next time there is a message
   * on the bus, so returning TRUE (FALSE means we want to stop watching
   * for messages on the bus and our callback should not be called again)
   */
  return TRUE;
}

gint main (gint argc, gchar * argv[])
{
  GstElement *pipeline;
  GstBus *bus;
  guint bus_watch_id;

  /* init */
  gst_init (&argc, &argv);

  /* create pipeline, add handler */
  pipeline = gst_pipeline_new ("my_pipeline");

  /* adds a watch for new message on our pipeline's message bus to
   * the default GLib main context, which is the main context that our
   * GLib main loop is attached to below
   */
  bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
  bus_watch_id = gst_bus_add_watch (bus, my_bus_callback, NULL);
  gst_object_unref (bus);

  /* [...] */

  /* create a mainloop that runs/iterates the default GLib main context
   * (context NULL), in other words: makes the context check if anything
   * it watches for has happened. When a message has been posted on the
   * bus, the default main context will automatically call our
   * my_bus_callback() function to notify us of that message.
   * The main loop will be run until someone calls g_main_loop_quit()
   */
  loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);

  /* clean up */
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_object_unref (pipeline);
  g_source_remove (bus_watch_id);
  g_main_loop_unref (loop);

  return 0;
}

        重要的是要知道处理程序将在主循环的线程上下文中调用。这意味着管道和总线上的应用程序之间的交互是异步的，因此不适合某些实时目的，例如音轨之间的交叉淡入淡出，进行（理论上）无间隙播放或视频效果。所有这些事情都应该在管道上下文中完成，通过编写 GStreamer 插件是最简单的。不过，它的主要目的非常有用：将消息从管道传递到应用程序。这种方法的优点是 GStreamer 在内部执行的所有线程对应用程序都是隐藏的，应用程序开发人员根本不必担心线程问题。

        请注意，如果我们使用默认的 GLib 主循环集成，我们可以连接到总线上的“消息”信号，而不是附加监视。这样我们就不必在所有可能的消息类型上都使用 switch() ；只需以 message::<type> 的形式连接到有趣的信号，其中 <type> 是特定的消息类型（有关消息类型的说明，请参见下一节）。

上面的代码片段也可以写成：

GstBus *bus;
[..]

bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
gst_bus_add_signal_watch (bus);
g_signal_connect (bus, "message::error", G_CALLBACK (cb_message_error), NULL);
g_signal_connect (bus, "message::eos", G_CALLBACK (cb_message_eos), NULL);

[..]

        如果您不使用 GLib 主循环，则默认情况下异步消息信号将不可用。 但是，您可以安装一个自定义同步处理程序来唤醒自定义主循环并使用 gst_bus_async_signal_func () 来发出信号。

消息类型

        GStreamer 有一些可以通过总线传递的预定义消息类型。 但是，这些消息是可扩展的。 插件可以定义额外的消息，并且应用程序可以决定为这些消息提供特定代码或忽略它们。 强烈建议所有应用程序至少通过向用户提供视觉反馈来处理错误消息。

        所有消息都有消息源、类型和时间戳。 消息源可用于查看哪个元素发出了消息。 例如，对于某些消息，只有顶级管道发出的消息才会对大多数应用程序感兴趣（例如状态更改通知）。 以下是所有消息的列表，以及它们的作用以及如何解析特定于消息的内容的简短说明：

        错误、警告和信息通知：如果应向用户显示有关管道状态的消息，则元素使用这些通知。错误消息是致命的并终止数据传递。应修复该错误以恢复管道活动。警告不是致命的，但仍然意味着一个问题。信息消息用于非问题通知。所有这些消息都包含带有主要错误类型和消息的 GError，以及可选的调试字符串。两者都可以使用 gst_message_parse_error()、_parse_warning() 和 _parse_info() 提取。错误和调试字符串都应该在使用后被释放。

        流结束通知：当流结束时发出。管道的状态不会改变，但进一步的媒体处理将停止。应用程序可以使用它跳到播放列表中的下一首歌曲。在流结束后，也可以在流中回溯。播放将自动继续。此消息没有特定参数。

        标签：在流中找到元数据时发出。这可以为管道多次发出（例如，一次用于描述性元数据，例如艺术家姓名或歌曲标题，另一次用于流信息，例如采样率和比特率）。应用程序应在内部缓存元数据。应该使用 gst_message_parse_tag() 来解析 taglist，在不再需要时应该使用 gst_tag_list_unref()。

        状态更改：在成功更改状态后发出。 gst_message_parse_state_changed() 可以用来解析这个转换的新旧状态。

        缓冲：在网络流缓存期间发出。通过从 gst_message_get_structure() 返回的结构中提取“buffer-percent”属性，可以手动从消息中提取进度（以百分比为单位）。另请参阅缓冲

        元素消息：这些是特定元素独有的特殊消息，通常代表附加功能。元素的文档应详细提及特定元素可能发送的元素消息。例如，如果流包含重定向指令，则“qtdemux”QuickTime 解复用器元素可能会在某些情况下发送“重定向”元素消息。

        特定于应用程序的消息：可以通过获取消息结构（见上文）并读取其字段来提取有关这些消息的任何信息。通常可以安全地忽略这些消息。

        应用程序消息主要用于应用程序内部使用，以防应用程序需要将来自某个线程的信息编组到主线程中。这在应用程序使用元素信号时特别有用（因为这些信号将在流线程的上下文中发出）。