GStreamer Tutorial 中文翻译：Basic tutorial 8: Short-cutting the pipeline

GStreamer Tutorial 8中文翻译

---

---

前言

由于工作原因，用的GStreamer的图像解码库，所以记录GStreamer Tutorial 的中文翻译和个人的理解以便学习。若有不足请多指教。侵删。

---

Basic tutorial 8: Short-cutting the pipeline

目的

GStreamer 构建的pipelines不需要完全关闭。数据在任何时候可以注入pipeline并以各种方式取出。例程展示：

• 如何在通用GStreamer pipeline中传入外部数据；
• 如何从通用GStreamer pipeline中提取数据；
• 如何访问和操作这些数据。

简介

应用可以通过多种方式与pipeline中的数据流进行交互。本例程描述了最简单的一个方法，因为它使用的元素就是为了这个目的而创建的。
appsrc元素用于将应用数据注入GStreamer pipeline中，与之相对的，appsink元素用于将GStreamer pipeline中的数据传回应用中。为了防止名称混淆，从GStreamer的角度出发：appsrc是一个常规源，提供从应用传来的数据。appsink是一个常规的接收，数据流经pipeline最终在这里停止，应用使用数据。
appsrc和appsink是如此通用，以至于它们提供了自己的API(请参阅它们的文档)，可以通过链接gstreamer-app库来访问。然而，在本教程中，我们将使用一种更简单的方法，通过信号来控制它们。
appsrc可以在多种模式下工作:在pull模式下，每当需要数据时，它都会向应用程序请求数据。在push模式下，应用程序以自己的速度推送数据。此外，在push模式下，当应用程序已经提供了足够的数据时，可以选择在push功能中被阻塞，也可以侦听足够的数据和需要的数据信号来控制流量。本示例实现了后一种方法。关于其他方法的信息可以在appsrc文档中找到。

缓冲区（Buffers）

缓冲区是数据在GStreamer pipeline传输时流经的块。因为这个示例生成和使用数据，所以我们需要了解GstBuffer S。
source pads产生缓冲区，sink pads消耗;GStreamer接受这些缓冲区，并将它们从一个元素传递到另一个元素。
缓冲区只是表示一个数据单元，不要假设所有缓冲区都有相同的大小或表示相同的时间。 也不应该假设如果一个缓冲区输入一个元素，那么就会有一个缓冲区出来。元素可以随意处理接收到的缓冲区。GstBuffer S也可以包含多个实际的内存缓冲区。实际的内存缓冲区是使用GstMemory对象抽象出来的，并且一个GstBuffer可以包含多个GstMemory对象。
每个缓冲区都附加了时间戳和持续时间，用来描述缓冲区的内容在何时被解码、呈现或显示。时间戳是一个非常复杂和微妙的主题，但是这个简化的视图现在应该已经足够了。
例如，filesrc(读取文件的GStreamer元素)会生成带有“ANY”大写且没有时间戳信息的缓冲区。在解绑定（demux）之后(请参阅基本教程3:动态管道)，缓冲区可以有一些特定的Caps，例如“video/x-h264”。解码后，每个缓冲区将包含一个带有原始大写的视频帧(例如，“video/x-raw-yuv”)和非常精确的时间戳，指示该帧何时显示。

例程

本教程以两种方式扩展基本教程7:多线程和Pad Availability:首先，audiotestsrc被一个将生成音频数据的appsrc取代。其次，一个新的分支被添加到tee中，因此数据进入音频接收器和波显示也被复制到一个appsink中。appsink将信息上传回应用程序，然后应用程序只是通知用户已经接收到数据，但它显然可以执行更复杂的任务。

一种原始波形发生器

将代码复制到basic-tutorial-8.c中，或在你的GStreamer路径中找到它。需要引入gstreamer-audio-1.0库。

gcc basic-tutorial-8.c -o basic-tutorial-8 `pkg-config --cflags --libs gstreamer-1.0 gstreamer-audio-1.0`

#include <gst/gst.h>
#include <gst/audio/audio.h>
#include <string.h>

#define CHUNK_SIZE 1024   /* Amount of bytes we are sending in each buffer */
#define SAMPLE_RATE 44100 /* Samples per second we are sending */

/* Structure to contain all our information, so we can pass it to callbacks */
typedef struct _CustomData {
  GstElement *pipeline, *app_source, *tee, *audio_queue, *audio_convert1, *audio_resample, *audio_sink;
  GstElement *video_queue, *audio_convert2, *visual, *video_convert, *video_sink;
  GstElement *app_queue, *app_sink;

  guint64 num_samples;   /* Number of samples generated so far (for timestamp generation) */
  gfloat a, b, c, d;     /* For waveform generation */

  guint sourceid;        /* To control the GSource */

  GMainLoop *main_loop;  /* GLib's Main Loop */
} CustomData;

/* This method is called by the idle GSource in the mainloop, to feed CHUNK_SIZE bytes into appsrc.
 * The idle handler is added to the mainloop when appsrc requests us to start sending data (need-data signal)
 * and is removed when appsrc has enough data (enough-data signal).
 */
static gboolean push_data (CustomData *data) {
  GstBuffer *buffer;
  GstFlowReturn ret;
  int i;
  GstMapInfo map;
  gint16 *raw;
  gint num_samples = CHUNK_SIZE / 2; /* Because each sample is 16 bits */
  gfloat freq;

  /* Create a new empty buffer */
  buffer = gst_buffer_new_and_alloc (CHUNK_SIZE);

  /* Set its timestamp and duration */
  GST_BUFFER_TIMESTAMP (buffer) = gst_util_uint64_scale (data->num_samples, GST_SECOND, SAMPLE_RATE);
  GST_BUFFER_DURATION (buffer) = gst_util_uint64_scale (num_samples, GST_SECOND, SAMPLE_RATE);

  /* Generate some psychodelic waveforms */
  gst_buffer_map (buffer, &map, GST_MAP_WRITE);
  raw = (gint16 *)map.data;
  data->c += data->d;
  data->d -= data->c / 1000;
  freq = 1100 + 1000 * data->d;
  for (i = 0; i < num_samples; i++) {
    data->a += data->b;
    data->b -= data->a / freq;
    raw[i] = (gint16)(500 * data->a);
  }
  gst_buffer_unmap (buffer, &map);
  data->num_samples += num_samples;

  /* Push the buffer into the appsrc */
  g_signal_emit_by_name (data->app_source, "push-buffer", buffer, &ret);

  /* Free the buffer now that we are done with it */
  gst_buffer_unref (buffer);

  if (ret != GST_FLOW_OK) {
    /* We got some error, stop sending data */
    return FALSE;
  }

  return TRUE;
}

/* This signal callback triggers when appsrc needs data. Here, we add an idle handler
 * to the mainloop to start pushing data into the appsrc */
static void start_feed (GstElement *source, guint size, CustomData *data) {
  if (data->sourceid == 0) {
    g_print ("Start feeding\n");
    data->sourceid = g_idle_add ((GSourceFunc) push_data, data);
  }
}

/* This callback triggers when appsrc has enough data and we can stop sending.
 * We remove the idle handler from the mainloop */
static void stop_feed (GstElement *source, CustomData *data) {
  if (data->sourceid != 0) {
    g_print ("Stop feeding\n");
    g_source_remove (data->sourceid);
    data->sourceid = 0;
  }
}

/* The appsink has received a buffer */
static GstFlowReturn new_sample (GstElement *sink, CustomData *data) {
  GstSample *sample;

  /* Retrieve the buffer */
  g_signal_emit_by_name (sink, "pull-sample", &sample);
  if (sample) {
    /* The only thing we do in this example is print a * to indicate a received buffer */
    g_print ("*");
    gst_sample_unref (sample);
    return GST_FLOW_OK;
  }

  return GST_FLOW_ERROR;
}

/* This function is called when an error message is posted on the bus */
static void error_cb (GstBus *bus, GstMessage *msg, CustomData *data) {
  GError *err;
  gchar *debug_info;

  /* Print error details on the screen */
  gst_message_parse_error (msg, &err, &debug_info);
  g_printerr ("Error received from element %s: %s\n", GST_OBJECT_NAME (msg->src), err->message);
  g_printerr ("Debugging information: %s\n", debug_info ? debug_info : "none");
  g_clear_error (&err);
  g_free (debug_info);

  g_main_loop_quit (data->main_loop);
}

int main(int argc, char *argv[]) {
  CustomData data;
  GstPad *tee_audio_pad, *tee_video_pad, *tee_app_pad;
  GstPad *queue_audio_pad, *queue_video_pad, *queue_app_pad;
  GstAudioInfo info;
  GstCaps *audio_caps;
  GstBus *bus;

  /* Initialize custom data structure */
  memset (&data, 0, sizeof (data));
  data.b = 1; /* For waveform generation */
  data.d = 1;

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

  /* Create the elements */
  data.app_source = gst_element_factory_make ("appsrc", "audio_source");
  data.tee = gst_element_factory_make ("tee", "tee");
  data.audio_queue = gst_element_factory_make ("queue", "audio_queue");
  data.audio_convert1 = gst_element_factory_make ("audioconvert", "audio_convert1");
  data.audio_resample = gst_element_factory_make ("audioresample", "audio_resample");
  data.audio_sink = gst_element_factory_make ("autoaudiosink", "audio_sink");
  data.video_queue = gst_element_factory_make ("queue", "video_queue");
  data.audio_convert2 = gst_element_factory_make ("audioconvert", "audio_convert2");
  data.visual = gst_element_factory_make ("wavescope", "visual");
  data.video_convert = gst_element_factory_make ("videoconvert", "video_convert");
  data.video_sink = gst_element_factory_make ("autovideosink", "video_sink");
  data.app_queue = gst_element_factory_make ("queue", "app_queue");
  data.app_sink = gst_element_factory_make ("appsink", "app_sink");

  /* Create the empty pipeline */
  data.pipeline = gst_pipeline_new ("test-pipeline");

  if (!data.pipeline || !data.app_source || !data.tee || !data.audio_queue || !data.audio_convert1 ||
      !data.audio_resample || !data.audio_sink || !data.video_queue || !data.audio_convert2 || !data.visual ||
      !data.video_convert || !data.video_sink || !data.app_queue || !data.app_sink) {
    g_printerr ("Not all elements could be created.\n");
    return -1;
  }

  /* Configure wavescope */
  g_object_set (data.visual, "shader", 0, "style", 0, NULL);

  /* Configure appsrc */
  gst_audio_info_set_format (&info, GST_AUDIO_FORMAT_S16, SAMPLE_RATE, 1, NULL);
  audio_caps = gst_audio_info_to_caps (&info);
  g_object_set (data.app_source, "caps", audio_caps, "format", GST_FORMAT_TIME, NULL);
  g_signal_connect (data.app_source, "need-data", G_CALLBACK (start_feed), &data);
  g_signal_connect (data.app_source, "enough-data", G_CALLBACK (stop_feed), &data);

  /* Configure appsink */
  g_object_set (data.app_sink, "emit-signals", TRUE, "caps", audio_caps, NULL);
  g_signal_connect (data.app_sink, "new-sample", G_CALLBACK (new_sample), &data);
  gst_caps_unref (audio_caps);

  /* Link all elements that can be automatically linked because they have "Always" pads */
  gst_bin_add_many (GST_BIN (data.pipeline), data.app_source, data.tee, data.audio_queue, data.audio_convert1, data.audio_resample,
      data.audio_sink, data.video_queue, data.audio_convert2, data.visual, data.video_convert, data.video_sink, data.app_queue,
      data.app_sink, NULL);
  if (gst_element_link_many (data.app_source, data.tee, NULL) != TRUE ||
      gst_element_link_many (data.audio_queue, data.audio_convert1, data.audio_resample, data.audio_sink, NULL) != TRUE ||
      gst_element_link_many (data.video_queue, data.audio_convert2, data.visual, data.video_convert, data.video_sink, NULL) != TRUE ||
      gst_element_link_many (data.app_queue, data.app_sink, NULL) != TRUE) {
    g_printerr ("Elements could not be linked.\n");
    gst_object_unref (data.pipeline);
    return -1;
  }

  /* Manually link the Tee, which has "Request" pads */
  //tee_audio_pad = gst_element_request_pad_simple (data.tee, "src_%u");
  tee_audio_pad = gst_element_get_request_pad(data.tee, "src_%u");
  g_print ("Obtained request pad %s for audio branch.\n", gst_pad_get_name (tee_audio_pad));
  queue_audio_pad = gst_element_get_static_pad (data.audio_queue, "sink");
  // tee_video_pad = gst_element_request_pad_simple (data.tee, "src_%u");
  tee_video_pad = gst_element_get_request_pad(data.tee, "src_%u");
  g_print ("Obtained request pad %s for video branch.\n", gst_pad_get_name (tee_video_pad));
  queue_video_pad = gst_element_get_static_pad (data.video_queue, "sink");
  // tee_app_pad = gst_element_request_pad_simple (data.tee, "src_%u");
  tee_app_pad = gst_element_get_request_pad(data.tee, "src_%u");
  g_print ("Obtained request pad %s for app branch.\n", gst_pad_get_name (tee_app_pad));
  queue_app_pad = gst_element_get_static_pad (data.app_queue, "sink");
  if (gst_pad_link (tee_audio_pad, queue_audio_pad) != GST_PAD_LINK_OK ||
      gst_pad_link (tee_video_pad, queue_video_pad) != GST_PAD_LINK_OK ||
      gst_pad_link (tee_app_pad, queue_app_pad) != GST_PAD_LINK_OK) {
    g_printerr ("Tee could not be linked\n");
    gst_object_unref (data.pipeline);
    return -1;
  }
  gst_object_unref (queue_audio_pad);
  gst_object_unref (queue_video_pad);
  gst_object_unref (queue_app_pad);

  /* Instruct the bus to emit signals for each received message, and connect to the interesting signals */
  bus = gst_element_get_bus (data.pipeline);
  gst_bus_add_signal_watch (bus);
  g_signal_connect (G_OBJECT (bus), "message::error", (GCallback)error_cb, &data);
  gst_object_unref (bus);

  /* Start playing the pipeline */
  gst_element_set_state (data.pipeline, GST_STATE_PLAYING);

  /* Create a GLib Main Loop and set it to run */
  data.main_loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (data.main_loop);

  /* Release the request pads from the Tee, and unref them */
  gst_element_release_request_pad (data.tee, tee_audio_pad);
  gst_element_release_request_pad (data.tee, tee_video_pad);
  gst_element_release_request_pad (data.tee, tee_app_pad);
  gst_object_unref (tee_audio_pad);
  gst_object_unref (tee_video_pad);
  gst_object_unref (tee_app_pad);

  /* Free resources */
  gst_element_set_state (data.pipeline, GST_STATE_NULL);
  gst_object_unref (data.pipeline);
  return 0;
}

代码走读

创建pipeline的代码(第131至205行)是基础教程7:多线程和Pad可用性的放大版。它涉及到实例化所有元素，将元素链接到Always Pads，并手动链接tee元素的Request Pads。
关于appsrc和appsink元素的配置:

/* Configure appsrc */
gst_audio_info_set_format (&info, GST_AUDIO_FORMAT_S16, SAMPLE_RATE, 1, NULL);
audio_caps = gst_audio_info_to_caps (&info);
g_object_set (data.app_source, "caps", audio_caps, NULL);
g_signal_connect (data.app_source, "need-data", G_CALLBACK (start_feed), &data);
g_signal_connect (data.app_source, "enough-data", G_CALLBACK (stop_feed), &data);

appsrc中需要设置的第一个属性是caps。它指定了元素将要产生的数据类型，因此GStreamer可以检查是否可能链接下游元素(也就是说，下游元素是否理解这种数据)。这个属性必须是一个GstCaps对象，它可以很容易地从一个带有gst_caps_from_string()的字符串构建。
然后我们连接到need-data和enough-data信号。它们分别在appsrc的内部数据队列运行不足或几乎满时被触发。我们将使用这些信号启动和停止(分别)我们的信号生成过程。

/* Configure appsink */
g_object_set (data.app_sink, "emit-signals", TRUE, "caps", audio_caps, NULL);
g_signal_connect (data.app_sink, "new-sample", G_CALLBACK (new_sample), &data);
gst_caps_unref (audio_caps);

关于appsink配置，我们连接到new-sample信号，该信号在sink每次接收到缓冲区时发出。此外，需要通过emit-signals属性启用信号发射，因为在默认情况下，它是禁用的。
启动pipeline，等待消息，并像往常一样完成最后的清理。让我们回顾一下刚刚注册的回调函数:

/* This signal callback triggers when appsrc needs data. Here, we add an idle handler
 * to the mainloop to start pushing data into the appsrc */
static void start_feed (GstElement *source, guint size, CustomData *data) {
  if (data->sourceid == 0) {
    g_print ("Start feeding\n");
    data->sourceid = g_idle_add ((GSourceFunc) push_data, data);
  }
}

当appsrc的内部队列即将耗尽(耗尽数据)时，将调用此函数。我们在这里做的唯一一件事就是向g_idle_add()注册一个GLib空闲函数，该函数将数据提供给appsrc，直到它再次被填满。GLib空闲函数是一种方法，每当GLib处于“空闲”状态(即没有更高优先级的任务要执行时)时，GLib就会从它的主循环中调用它。显然，它需要一个GLib GMainLoop实例化并运行。
这只是appsrc使用的多种方法之一。特别是，不需要使用GLib从主线线程将缓冲区提供给appsrc，也不需要使用need-data和enough-data信号来与appsrc同步(尽管据说这是最方便的方式)。
我们注意到g_idle_add()返回的是sourceid，因此以后可以禁用它。

/* This callback triggers when appsrc has enough data and we can stop sending.
 * We remove the idle handler from the mainloop */
static void stop_feed (GstElement *source, CustomData *data) {
  if (data->sourceid != 0) {
    g_print ("Stop feeding\n");
    g_source_remove (data->sourceid);
    data->sourceid = 0;
  }
}

当appsrc的内部队列已满这个函数会被调用，所以我们停止推送数据。在这里，我们只需使用g_source_remove()删除空闲函数(空闲函数作为GSource实现)。

/* This method is called by the idle GSource in the mainloop, to feed CHUNK_SIZE bytes into appsrc.
 * The ide handler is added to the mainloop when appsrc requests us to start sending data (need-data signal)
 * and is removed when appsrc has enough data (enough-data signal).
 */
static gboolean push_data (CustomData *data) {
  GstBuffer *buffer;
  GstFlowReturn ret;
  int i;
  gint16 *raw;
  gint num_samples = CHUNK_SIZE / 2; /* Because each sample is 16 bits */
  gfloat freq;

  /* Create a new empty buffer */
  buffer = gst_buffer_new_and_alloc (CHUNK_SIZE);

  /* Set its timestamp and duration */
  GST_BUFFER_TIMESTAMP (buffer) = gst_util_uint64_scale (data->num_samples, GST_SECOND, SAMPLE_RATE);
  GST_BUFFER_DURATION (buffer) = gst_util_uint64_scale (num_samples, GST_SECOND, SAMPLE_RATE);

  /* Generate some psychodelic waveforms */
  raw = (gint16 *)GST_BUFFER_DATA (buffer);

这是推送数据给appsrc的函数。GLib有时会调用它，调用速率超出我们的控制，但我们知道，当它的工作完成时(当appsrc中的队列已满时)，我们会禁用它。
它的第一个任务是使用gst_buffer_new_and_alloc()创建一个给定大小的新缓冲区(在本例中，它被任意设置为1024字节)。
我们计算到目前为止使用CustomData.num_amples变量生成的示例的数量，所以我们可以在GstBuffer中使用GST_BUFFER_TIMESTAMP宏对这个缓冲区设置时间戳。
因为我们生成的缓冲区大小相同，所以它们的持续时间是相同的，并且在GstBuffer中使用GST_BUFFER_DURATION进行设置。
Gst_util_uint64_scale()是一个实用函数，可以缩放(乘和除)可以很大的数字，而不用担心溢出。
可以在GstBuffer中使用GST_BUFFER_DATA访问缓冲区的字节(注意不要写入超过缓冲区的末尾:您已经分配了它，所以您知道它的大小)。
我们将跳过波形生成，因为它超出了本教程的范围(它只是一种生成非常迷幻的波形的有趣方法)。

/* Push the buffer into the appsrc */
g_signal_emit_by_name (data->app_source, "push-buffer", buffer, &ret);

/* Free the buffer now that we are done with it */
gst_buffer_unref (buffer);

一旦我们准备好了缓冲区，我们将它与push-buffer动作信号传递给appsrc(见播放教程1:Playbin用法末尾的信息框)，然后gst_buffer_unref()它，因为我们不再需要它。

/* The appsink has received a buffer */
static GstFlowReturn new_sample (GstElement *sink, CustomData *data) {
  GstSample *sample;
  /* Retrieve the buffer */
  g_signal_emit_by_name (sink, "pull-sample", &sample);
  if (sample) {
    /* The only thing we do in this example is print a * to indicate a received buffer */
    g_print ("*");
    gst_sample_unref (sample);
    return GST_FLOW_OK;
  }
  return GST_FLOW_ERROR;
}

最后，这是当appsink收到缓冲区时被调用的函数。我们使用pull-sample动作信号来获取缓冲区，然后在屏幕上打印一些指示器即可。我们可以使用GST_BUFFER_DATA宏检索数据指针，使用GstBuffer中的GST_BUFFER_SIZE宏检索数据大小。记住，这个缓冲区不必与我们在push_data函数中产生的缓冲区相匹配，路径中的任何元素都可以以任何方式改变缓冲区（在这个例子中没有：在appsrc和appsink之间的路径中只有一个tee，而且它没有改变缓冲区的内容）。
然后我们用gst_buffer_unref()方法处理这个缓冲区，这个教程就完成了。

结论

这个例程展示应用如何能够完成：

• 使用appsrc元素往pipeline中传入数据；
• 使用appsink元素从pipeline中提出数据；
• 过访问GstBuffer来操作数据。