Manual Hello World

将下面代码copy到一个命名为basic-tutorial-1.c的文件中。

#include <gst/gst.h>int main(int argc, char *argv[]) {GstElement *pipeline, *source, *sink;GstBus *bus;GstMessage *msg;GstStateChangeReturn ret;/* Initialize GStreamer */gst_init (&argc, &argv);/* Create the elements */source = gst_element_factory_make ("videotestsrc", "source");sink = gst_element_factory_make ("autovideosink", "sink");/* Create the empty pipeline */pipeline = gst_pipeline_new ("test-pipeline");if (!pipeline || !source || !sink) {g_printerr ("Not all elements could be created.\n");return -1;}/* Build the pipeline */gst_bin_add_many (GST_BIN (pipeline), source, sink, NULL);if (gst_element_link (source, sink) != TRUE) {g_printerr ("Elements could not be linked.\n");gst_object_unref (pipeline);return -1;}/* Modify the source's properties */g_object_set (source, "pattern", 0, NULL);/* Start playing */ret = gst_element_set_state (pipeline, GST_STATE_PLAYING);if (ret == GST_STATE_CHANGE_FAILURE) {g_printerr ("Unable to set the pipeline to the playing state.\n");gst_object_unref (pipeline);return -1;}/* Wait until error or EOS */bus = gst_element_get_bus (pipeline);msg = gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE, GST_MESSAGE_ERROR | GST_MESSAGE_EOS);/* Parse message */if (msg != NULL) {GError *err;gchar *debug_info;switch (GST_MESSAGE_TYPE (msg)) {case GST_MESSAGE_ERROR: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);break;case GST_MESSAGE_EOS:g_print ("End-Of-Stream reached.\n");break;default:/* We should not reach here because we only asked for ERRORs and EOS */g_printerr ("Unexpected message received.\n");break;}gst_message_unref (msg);}/* Free resources */gst_object_unref (bus);gst_element_set_state (pipeline, GST_STATE_NULL);gst_object_unref (pipeline);return 0;
}

逐步解说

GStreamer的基本构造块为元素(elements)，它向下游流动从source elements（数据的制作者）向sink elements（数据的消费者），穿过过滤器元件（filter elements）而处理数据。

Element creation

/* Create the elements */
source = gst_element_factory_make ("videotestsrc", "source");
sink = gst_element_factory_make ("autovideosink", "sink");

可以看出在这段代码中，新元素可以用gst_element_factory_make()来创建。第一个参数是元素的创建类型（Basic tutorial 14: Handy elements：显示了一些常见的类型，以及 Basic tutorial 10: GStreamer tools：展示了如何获取所有可用类型的列表）。第二个参数是我们想给这个特定实例的名称。命名你的元素是非常有用以后对它们进行检索，如果你没有保持一个指针（和更有意义的调试输出）。如果你传递NULL的名字，然而，，GStreamer将会为您提供一个唯一的名称。

在本教程中，我们创建两个元素：一个 videotestsrc  和  autovideosink。

videotestsrc 是源元素（它产生的数据），它创建了一个测试视频模式。此元素对于调试目的（和教程）是有用的，而不是在实际应用中使用。

autovideosink是一个接收元素（它消耗的数据），它在一个窗口中显示接收到的图像。存在几个视频接收器，根据不同的操作系统，具有能力的变化范围。 autovideosink自动选择并实例化最好的一个，所以你不必担心的细节，你的代码更是平台无关的。

Pipeline creation

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

GStreamer中的所有元素都必须典型地包含在一个管道内才能使用它们，因为它需要一些时钟和短信功能护理。我们创建gst_pipeline_new()等的管道。

/* Build the pipeline */
gst_bin_add_many (GST_BIN (pipeline), source, sink, NULL);
if (gst_element_link (source, sink) != TRUE) {g_printerr ("Elements could not be linked.\n");gst_object_unref (pipeline);return -1;
}

管道是一种特殊类型的bin，这是用来包含其他元素的元素。因此，适用于bin的所有方法也适用于管道。在我们的例子中，我们调用 gst_bin_add_many() 将元素添加到管道（mind the cast）。这个函数接受要添加元素的列表，用NULL结束。单个元素可以用 gst_bin_add() 进行添加。

这些元素，但是，没有相互连接的呢。对于这一点，我们需要使用 gst_element_link() 。它的第一个参数是source，而第二个是destination。顺序计数，因为链接必须遵循数据流（这是 from source elements to sink elements）成立。请记住，只有居住在同一个bin的元素可以彼此链接，所以记得将它们添加到统一管道在试图链接它们之前！

Properties

/* Modify the source's properties */
g_object_set (source, "pattern", 0, NULL);

大多数的GStreamer元素具有可定制的属性：可以修改来改变元素的行为（可写属性），或者询问，了解元素的内部状态（可读属性）。属性用 g_object_get() 读取和用 g_object_set()写入。

g_object_set() accepts a NULL-terminated list of property-name, property-value pairs，这样多个属性可以一次改变（GStreamer的元素都是一种特殊的GObject，这是实体提供物业设施：这就是为什么属性的处理方法有g_前缀。

以上代码的行更改 videotestsrc 中的“模式”属性，该属性控制测试视频的类型元素输出。尝试不同的值！

所有属性的元素自曝的名称和可能的值可以使用Basic tutorial 10: GStreamer tools中描述的GST-检验工具中找到。

Error checking

在这一点上，我们有整个管道建造和设置，以及本教程的其余部分是非常相似的前一个，但我们将增加更多的错误检查：

/* Start playing */
ret = gst_element_set_state (pipeline, GST_STATE_PLAYING);
if (ret == GST_STATE_CHANGE_FAILURE) {g_printerr ("Unable to set the pipeline to the playing state.\n");gst_object_unref (pipeline);return -1;
}

我们称 gst_element_set_state()，但是这一次我们检查它的返回值的错误。改变状态是一个微妙的过程和一些更细节的Basic tutorial 3: Dynamic pipelines中给出。

/* Wait until error or EOS */
bus = gst_element_get_bus (pipeline);
msg = gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE, GST_MESSAGE_ERROR | GST_MESSAGE_EOS);/* Parse message */
if (msg != NULL) {GError *err;gchar *debug_info;switch (GST_MESSAGE_TYPE (msg)) {case GST_MESSAGE_ERROR: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);break;case GST_MESSAGE_EOS:g_print ("End-Of-Stream reached.\n");break;default:/* We should not reach here because we only asked for ERRORs and EOS */g_printerr ("Unexpected message received.\n");break;}gst_message_unref (msg);
}

gst_bus_timed_pop_filtered() 执行结束并返回等待一个 GstMessage 这是我们以前忽略。我们要求gst_bus_timed_pop_filtered()返回遇到的任何错误情况或EOS，所以我们需要检查哪一个发生的事情，并在屏幕上打印一条消息（您的应用程序可能要进行更复杂的动作）。

GstMessage 是它几乎可以提供任何种类的信息非常灵活的结构。幸运的是，GStreamer中提供了一系列分析功能，为各类消息的。

在这种情况下，一旦我们知道了消息中包含一个错误（使用 GST_MESSAGE_TYPE() 宏），我们可以使用 gst_message_parse_error() ，它返回一个GLib的 GError 错误信息结构和一个字符串用于调试。检查代码，看看它们是如何使用和释放。

The GStreamer bus

在这一点上是值得正式的介绍一下GStreamer总线。它负责把元素所生成的 GstMessage s提供给应用程序，为了与应用程序的线程保持联系。最后一点很重要，因为媒体的实际流工作是在另一个线程而不是应用程序。

消息可以从总线实时地通过 gst_bus_timed_pop_filtered()和它的兄弟姐妹，或异步，使用信号（在接下来的教程中所示）。您的应用程序应该始终注意错误和其他回放产生的相关问题。

代码的其余部分是在清理序列，这是相同 Basic tutorial 1: Hello world!。

Exercise

如果你觉得自己练，试试这个练习：添加source和the sink of this pipeline之间的视频过滤器元件。使用 vertigotv 会有一个不错的效果。您将需要创建它，将它添加到管道，并与其他元素联系起来。

根据您的平台，可用插件时，你可能会得到一个“谈判（negotiation）”的错误，因为接收器不明白的过滤器生产（更多关于谈判的 Basic tutorial 6: Media formats and Pad Capabilities：媒体格式和垫功能）。在这种情况下，添加过滤器后，尝试添加一个被称为  ffmpegcolorspace 的元素（这是，建立4个元素的管道，更多关于  ffmpegcolorspace 请参看Basic tutorial 14: Handy elements：方便的元素）。

Conclusion

本教程显示：

• 如何用 gst_element_factory_make() 建立元素

• 如何用 gst_pipeline_new() 建立一个空的管道

• 如何用 gst_bin_add_many() 将元素添加管道

• 如何用 gst_element_link()将元素彼此链接

这样就完成了最近两个教程致力于GStreamer的基本概念。

记住，此页你应该找到本教程的完整源代码，并建立它所需的任何附件文件。

很高兴你能受用这个教程，以后的教程再见！