基础教程 1：世界你好！

## Goal 目标 
Nothing better to get a first impression about a software library than to print “Hello World” on the screen!
没有什么比在屏幕上打印 "Hello World "更能给人留下软件库的第一印象了！

But since we are dealing with multimedia frameworks, we are going to play a video instead.
但由于我们要处理的是多媒体框架，所以我们要播放一段视频。

Do not be scared by the amount of code below: there are only 4 lines which do real work. The rest is cleanup code, and, in C, this is always a bit verbose.
不要被下面的代码量吓到：只有 4 行是做实际工作的。其余的都是清理代码，而在 C 语言中，清理代码总是有点冗长。

Without further ado, get ready for your first GStreamer application...
话不多说，准备好使用您的第一个 GStreamer 应用程序吧...

## Hello world 世界你好 
Copy this code into a text file named basic-tutorial-1.c (or find it in your GStreamer installation).
将此代码复制到名为 basic-tutorial-1.c 的文本文件中（或在 GStreamer 安装文件中找到它）。

basic-tutorial-1.c basic-tutorial-1.c

```c
#include <gst/gst.h>

#ifdef __APPLE__
#include <TargetConditionals.h>
#endif

int
tutorial_main (int argc, char *argv[])
{
  GstElement *pipeline;
  GstBus *bus;
  GstMessage *msg;

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

/* Build the pipeline */
  pipeline =
      gst_parse_launch
      ("playbin uri=https://gstreamer.freedesktop.org/data/media/sintel_trailer-480p.webm",
      NULL);

/* Start playing */
  gst_element_set_state (pipeline, GST_STATE_PLAYING);

/* 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);

/* See next tutorial for proper error message handling/parsing */
  if (GST_MESSAGE_TYPE (msg) == GST_MESSAGE_ERROR) {
    g_error ("An error occurred! Re-run with the GST_DEBUG=*:WARN environment "
        "variable set for more details.");
  }

/* Free resources */
  gst_message_unref (msg);
  gst_object_unref (bus);
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_object_unref (pipeline);
  return 0;
}

int
main (int argc, char *argv[])
{
#if defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE
  return gst_macos_main ((GstMainFunc) tutorial_main, argc, argv, NULL);
#else
  return tutorial_main (argc, argv);
#endif
}
```

Compile it as described in Installing on Linux, Installing on Mac OS X or Installing on Windows. If you get compilation errors, double-check the instructions given in those sections.
按照安装在 Linux、安装在 Mac OSX 或安装在 Windows 中的说明进行编译。如果出现编译错误，请仔细检查这些章节中的说明。

If everything built fine, fire up the executable! You should see a window pop up, containing a video being played straight from the Internet, along with audio. Congratulations!
如果一切正常，请启动可执行文件！你会看到弹出一个窗口，其中包含一段直接从互联网上播放的视频和音频。恭喜您

****Information****
*Need help? 需要帮助吗？

If you need help to compile this code, refer to the Building the tutorials section for your platform: Linux, Mac OS X or Windows, or use this specific command on Linux:
如果在编译代码时需要帮助，请参阅 "为您的平台构建教程 "部分：Linux、Mac OS X 或 Windows，或在 Linux 上使用此特定命令：

`gcc basic-tutorial-1.c -o basic-tutorial-1 'pkg-config --cflags --libs gstreamer-1.0'`

If you need help to run this code, refer to the Running the tutorials section for your platform: Linux, Mac OS X or Windows.
如果您在运行此代码时需要帮助，请参阅 "运行教程 "部分，了解您的平台：Linux、Mac OS X 或 Windows。

Required libraries:  所需的库：gstreamer-1.0. gstreamer-1.0
*
This tutorial opens a window and displays a movie, with accompanying audio. The media is fetched from the Internet, so the window might take a few seconds to appear, depending on your connection speed. Also, there is no latency management (buffering), so on slow connections, the movie might stop after a few seconds. See how Basic tutorial 12: Streaming solves this issue.
本教程将打开一个窗口，并显示一部电影和相应的音频。媒体是从互联网上获取的，因此窗口可能需要几秒钟才能出现，具体取决于您的连接速度。此外，由于没有延迟管理（缓冲），在连接速度较慢的情况下，电影可能会在几秒钟后停止。

## Walkthrough 演练 
Let's review these lines of code and see what they do:
让我们回顾一下这几行代码，看看它们都做了些什么：

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

This must always be your first GStreamer command. Among other things, gst_init():
这必须是你的第一个 GStreamer 命令。其中包括 gst_init()：

- Initializes all internal structures
- 初始化所有内部结构

- Checks what plug-ins are available
- 检查有哪些插件可用

- Executes any command-line option intended for GStreamer
- 执行 GStreamer 的任何命令行选项

If you always pass your command-line parameters argc and argv to gst_init() your application will automatically benefit from the GStreamer standard command-line options (more on this in Basic tutorial 10: GStreamer tools)
如果您总是将命令行参数argc和argv传递给 gst_init()，您的应用程序将自动受益于 GStreamer 标准命令行选项（更多内容请参见***基础教程 10：GStreamer 工具***）。

```c
  /* Build the pipeline */
  pipeline =
      gst_parse_launch
      ("playbin uri=https://gstreamer.freedesktop.org/data/media/sintel_trailer-480p.webm",
      NULL);

```
This line is the heart of this tutorial, and exemplifies two key points: gst_parse_launch() and playbin.
这一行是本教程的核心，体现了两个关键点：gst_parse_launch() 和 playbin。

### gst_parse_launch 
GStreamer is a framework designed to handle multimedia flows. Media travels from the “source” elements (the producers), down to the “sink” elements (the consumers), passing through a series of intermediate elements performing all kinds of tasks. The set of all the interconnected elements is called a “pipeline”.
GStreamer 是一个用于处理多媒体流的框架。多媒体从 "源 "元素（生产者）流向 "汇 "元素（消费者），经过一系列执行各种任务的中间元素。所有相互连接的元素集合称为 "管道"。

In GStreamer you usually build the pipeline by manually assembling the individual elements, but, when the pipeline is easy enough, and you do not need any advanced features, you can take the shortcut: gst_parse_launch().
在 GStreamer 中，通常是通过手动组装单个元素来构建流水线，但当流水线足够简单且不需要任何高级功能时，可以使用快捷方式：gst_parse_launch() 。

This function takes a textual representation of a pipeline and turns it into an actual pipeline, which is very handy. In fact, this function is so handy there is a tool built completely around it which you will get very acquainted with (see Basic tutorial 10: GStreamer tools to learn about gst-launch-1.0 and the gst-launch-1.0 syntax).
该函数将管道的文本表示转换为实际管道，非常方便。事实上，这个函数非常方便，有一个完全围绕它构建的工具，你会非常熟悉它（参见***基础教程 10：GStreamer 工具***，了解 gst-launch-1.0 和 gst-launch-1.0 语法）。

### playbin 播放器 
So, what kind of pipeline are we asking gst_parse_launch() to build for us? Here enters the second key point: We are building a pipeline composed of a single element called playbin.
那么，我们要求 gst_parse_launch() 为我们构建什么样的管道呢？这里有第二个关键点：我们正在构建一个由名为 playbin 的单一元素组成的流水线。

playbin is a special element which acts as a source and as a sink, and is a whole pipeline. Internally, it creates and connects all the necessary elements to play your media, so you do not have to worry about it.
playbin 是一个特殊的元素，它既是源也是汇，是一个完整的管道。它在内部创建并连接了播放媒体所需的所有元素，因此你无需担心。

It does not allow the control granularity that a manual pipeline does, but, still, it permits enough customization to suffice for a wide range of applications. Including this tutorial.
虽然它的控制粒度不如手动流水线，但它允许足够的自定义，足以满足各种应用的需要。包括本教程。

In this example, we are only passing one parameter to playbin, which is the URI of the media we want to play. Try changing it to something else! Whether it is an http:// or file:// URI, playbin will instantiate the appropriate GStreamer source transparently!
在本例中，我们只向 playbin 传递了一个参数，即我们要播放的媒体的 URI。试着把它改成其他参数！无论它是 http:// 还是 file:// URI，playbin 都会透明地建立适当的 GStreamer 源！

If you mistype the URI, or the file does not exist, or you are missing a plug-in, GStreamer provides several notification mechanisms, but the only thing we are doing in this example is exiting on error, so do not expect much feedback.
如果你打错了 URI，或者文件不存在，或者缺少一个插件，GStreamer 会提供多种通知机制，但我们在本例中只是在出错时退出，所以不要期待太多反馈。

```c
  /* Start playing */
  gst_element_set_state (pipeline, GST_STATE_PLAYING);
```

This line highlights another interesting concept: the state. Every GStreamer element has an associated state, which you can more or less think of as the Play/Pause button in your regular DVD player. For now, suffice to say that playback will not start unless you set the pipeline to the PLAYING state.
这一行突出了另一个有趣的概念：状态。每个 GStreamer 元素都有一个相关的状态，你可以把它想象成普通 DVD 播放器中的 "播放/暂停 "按钮。现在只需说明，除非将流水线设置为 PLAYING 状态，否则播放将不会开始。

In this line, gst_element_set_state() is setting pipeline (our only element, remember) to the PLAYING state, thus initiating playback.
在这一行中，gst_element_set_state() 将 pipeline（我们唯一的元素，请记住）设置为 PLAYING 状态，从而开始播放。

```c
  /* 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);
```

These lines will wait until an error occurs or the end of the stream is found. gst_element_get_bus() retrieves the pipeline's bus, and gst_bus_timed_pop_filtered() will block until you receive either an ERROR or an EOS (End-Of-Stream) through that bus. Do not worry much about this line, the GStreamer bus is explained in Basic tutorial 2: GStreamer concepts.
gst_element_get_bus() 会检索流水线的总线，gst_bus_timed_pop_filtered() 则会阻塞流水线，直到收到 Error 或 EOS（End-Of-Stream）。不用太担心这一行，GStreamer 总线在基础教程 2:GStreamer 概念中已有解释。

And that's it! From this point onwards, GStreamer takes care of everything. Execution will end when the media reaches its end (EOS) or an error is encountered (try closing the video window, or unplugging the network cable). The application can always be stopped by pressing control-C in the console.
就是这样！从这时起，GStreamer 将负责一切。当媒体播放结束（EOS）或出现错误（尝试关闭视频窗口或拔下网线）时，程序将结束执行。在控制台中按下control-C键即可停止程序运行。

## Cleanup 清理 
Before terminating the application, though, there is a couple of things we need to do to tidy up correctly after ourselves.
不过，在终止应用程序之前，我们还需要做几件事来正确地整理自己的工作。

```c
  /* Free resources */
  gst_message_unref (msg);
  gst_object_unref (bus);
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_object_unref (pipeline);
  return 0;
```

Always read the documentation of the functions you use, to know if you should free the objects they return after using them.
请务必阅读所用函数的文档，以了解使用函数后是否应释放函数返回的对象。

In this case, gst_bus_timed_pop_filtered() returned a message which needs to be freed with gst_message_unref() (more about messages in Basic tutorial 2: GStreamer concepts).
在这种情况下，gst_bus_timed_pop_filtered() 返回了一条消息，需要用 gst_message_unref() 释放这条消息（有关消息的更多信息，请参见**基础教程 2：GStreamer 概念**）。

gst_element_get_bus() added a reference to the bus that must be freed with gst_object_unref(). Setting the pipeline to the NULL state will make sure it frees any resources it has allocated (More about states in Basic tutorial 3: Dynamic pipelines). Finally, unreferencing the pipeline will destroy it, and all its contents.
gst_element_get_bus() 添加了对总线的引用，必须用 gst_object_unref() 释放该引用。将管道设置为 NULL 状态将确保它释放所有已分配的资源（有关状态的更多信息，请参见**基础教程 3：动态管道**）。最后，取消引用管道将销毁管道及其所有内容。

## Conclusion 结论 
And so ends your first tutorial with GStreamer. We hope its brevity serves as an example of how powerful this framework is!
GStreamer 的第一个教程到此结束。我们希望它的简明扼要能作为一个例子，说明这个框架有多么强大！

Let's recap a bit. Today we have learned:
让我们来回顾一下。今天我们学到了

- How to initialize GStreamer using gst_init().
- 如何使用 gst_init()初始化 GStreamer。

- How to quickly build a pipeline from a textual description using gst_parse_launch().
- 如何使用 gst_parse_launch()，根据文字描述快速构建管道。

- How to create an automatic playback pipeline using playbin.
- 如何使用 playbin 创建自动播放管道。

- How to signal GStreamer to start playback using gst_element_set_state().
- 如何使用 gst_element_set_state() 向 GStreamer 发送开始播放的信号。

- How to sit back and relax, while GStreamer takes care of everything, using gst_element_get_bus() and gst_bus_timed_pop_filtered().
- 如何使用 gst_element_get_bus() 和 gst_bus_timed_pop_filtered()，在 GStreamer 处理一切事务时放松身心？

The next tutorial will keep introducing more basic GStreamer elements, and show you how to build a pipeline manually.
下一篇教程将继续介绍更多基本的 GStreamer 元素，并向你展示如何手动构建管道。

It has been a pleasure having you here, and see you soon!
很高兴你们能来这里，再见！