markdown/tutorials/basic/hello-world.md

   1 ---
   2 short-description: The mandatory 'Hello world' example
   3 ...
   4
   5 # Basic tutorial 1: Hello world!
   6
   7 ## Goal
   8
   9 Nothing better to get a first impression about a software library than
  10 to print “Hello World” on the screen!
  11
  12 But since we are dealing with multimedia frameworks, we are going to
  13 play a video instead.
  14
  15 Do not be scared by the amount of code below: there are only 4 lines
  16 which do *real* work. The rest is cleanup code, and, in C, this is
  17 always a bit verbose.
  18
  19 Without further ado, get ready for your first GStreamer application...
  20
  21 ## Hello world
  22
  23 Copy this code into a text file named `basic-tutorial-1.c` (or find it
  24 in the SDK installation).
  25
  26 **basic-tutorial-1.c**
  27
  28 {{ tutorials/basic-tutorial-1.c }}
  29
  30 Compile it as described in [Installing on Linux], [Installing on Mac OS
  31 X] or [Installing on Windows]. If you get compilation errors,
  32 double-check the instructions given in those sections.
  33
  34 If everything built fine, fire up the executable! You should see a
  35 window pop up, containing a video being played straight from the
  36 Internet, along with audio. Congratulations!
  37
  38 > ![Information] Need help?
  39 >
  40 > If you need help to compile this code, refer to the **Building the
  41 > tutorials** section for your platform: [Linux], [Mac OS X] or
  42 > [Windows], or use this specific command on Linux:
  43 >
  44 > `` gcc basic-tutorial-1.c -o basic-tutorial-1 `pkg-config --cflags --libs gstreamer-1.0` ``
  45 >
  46 > If you need help to run this code, refer to the **Running the
  47 > tutorials** section for your platform: [Linux][1], [Mac OS X][2] or
  48 > [Windows][3].
  49 >
  50 > This tutorial opens a window and displays a movie, with accompanying
  51 > audio. The media is fetched from the Internet, so the window might
  52 > take a few seconds to appear, depending on your connection speed.
  53 > Also, there is no latency management (buffering), so on slow
  54 > connections, the movie might stop after a few seconds. See how [Basic
  55 > tutorial 12: Streaming] solves this issue.
  56 >
  57 > Required libraries: `gstreamer-1.0`
  58
  59 ## Walkthrough
  60
  61 Let's review these lines of code and see what they do:
  62
  63 ``` c
  64     /* Initialize GStreamer */
  65     gst_init (&argc, &argv);
  66 ```
  67
  68 This must always be your first GStreamer command. Among other things,
  69 `gst_init()`:
  70
  71 -   Initializes all internal structures
  72
  73 -   Checks what plug-ins are available
  74
  75 -   Executes any command-line option intended for GStreamer
  76
  77 If you always pass your command-line parameters
  78 `argc` and `argv` to `gst_init()` your application will automatically
  79 benefit from the GStreamer standard command-line options (more on this
  80 in [Basic tutorial 10: GStreamer tools])
  81
  82 ``` c
  83     /* Build the pipeline */
  84     pipeline = gst_parse_launch ("playbin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm", NULL);
  85 ```
  86
  87 This line is the heart of this tutorial, and exemplifies **two** key
  88 points: `gst_parse_launch()` and `playbin`.
  89
  90 ### gst\_parse\_launch
  91
  92 GStreamer is a framework designed to handle multimedia flows. Media
  93 travels from the “source” elements (the producers), down to the “sink”
  94 elements (the consumers), passing through a series of intermediate
  95 elements performing all kinds of tasks. The set of all the
  96 interconnected elements is called a “pipeline”.
  97
  98 In GStreamer you usually build the pipeline by manually assembling the
  99 individual elements, but, when the pipeline is easy enough, and you do
 100 not need any advanced features, you can take the shortcut:
 101 `gst_parse_launch()`.
 102
 103 This function takes a textual representation of a pipeline and turns it
 104 into an actual pipeline, which is very handy. In fact, this function is
 105 so handy there is a tool built completely around it which you will get
 106 very acquainted with (see [Basic tutorial 10: GStreamer tools][Basic
 107 tutorial 10: GStreamer tools] to learn about `gst-launch-1.0` and the
 108 `gst-launch-1.0` syntax).
 109
 110 ### playbin
 111
 112 So, what kind of pipeline are we asking `gst_parse_launch()`to build for
 113 us? Here enters the second key point: We are building a pipeline
 114 composed of a single element called `playbin`.
 115
 116 `playbin` is a special element which acts as a source and as a sink, and
 117 is a whole pipeline. Internally, it creates and connects all the
 118 necessary elements to play your media, so you do not have to worry about
 119 it.
 120
 121 It does not allow the control granularity that a manual pipeline does,
 122 but, still, it permits enough customization to suffice for a wide range
 123 of applications. Including this tutorial.
 124
 125 In this example, we are only passing one parameter to `playbin`, which
 126 is the URI of the media we want to play. Try changing it to something
 127 else! Whether it is an `http://` or `file://` URI, `playbin` will
 128 instantiate the appropriate GStreamer source transparently!
 129
 130 If you mistype the URI, or the file does not exist, or you are missing a
 131 plug-in, GStreamer provides several notification mechanisms, but the
 132 only thing we are doing in this example is exiting on error, so do not
 133 expect much feedback.
 134
 135 ``` c
 136     /* Start playing */
 137     gst_element_set_state (pipeline, GST_STATE_PLAYING);
 138 ```
 139
 140 This line highlights another interesting concept: the state. Every
 141 GStreamer element has an associated state, which you can more or less
 142 think of as the Play/Pause button in your regular DVD player. For now,
 143 suffice to say that playback will not start unless you set the pipeline
 144 to the PLAYING state.
 145
 146 In this line, `gst_element_set_state()` is setting `pipeline` (our only
 147 element, remember) to the PLAYING state, thus initiating playback.
 148 ```
 149
 150 ``` c
 151     /* Wait until error or EOS */
 152     bus = gst_element_get_bus (pipeline);
 153     gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE, GST_MESSAGE_ERROR | GST_MESSAGE_EOS);
 154 ```
 155
 156 These lines will wait until an error occurs or the end of the stream is
 157 found. `gst_element_get_bus()` retrieves the pipeline's bus, and
 158 `gst_bus_timed_pop_filtered()` will block until you receive either an
 159 ERROR or an EOS (End-Of-Stream) through that bus. Do not worry much
 160 about this line, the GStreamer bus is explained in [Basic tutorial 2:
 161 GStreamer concepts].
 162
 163 And that's it! From this point onwards, GStreamer takes care of
 164 everything. Execution will end when the media reaches its end (EOS) or
 165 an error is encountered (try closing the video window, or unplugging the
 166 network cable). The application can always be stopped by pressing
 167 control-C in the console.
 168
 169 ### Cleanup
 170
 171 Before terminating the application, though, there is a couple of things
 172 we need to do to tidy up correctly after ourselves.
 173
 174 ``` c
 175     /* Free resources */
 176     if (msg != NULL)
 177       gst_message_unref (msg);
 178     gst_object_unref (bus);
 179     gst_element_set_state (pipeline, GST_STATE_NULL);
 180     gst_object_unref (pipeline);
 181 ```
 182
 183 Always read the documentation of the functions you use, to know if you
 184 should free the objects they return after using them.
 185
 186 In this case, `gst_bus_timed_pop_filtered()` returned a message which
 187 needs to be freed with `gst_message_unref()` (more about messages in
 188 [Basic tutorial 2: GStreamer concepts][Basic tutorial 2: GStreamer
 189 concepts]).
 190
 191 `gst_element_get_bus()` added a reference to the bus that must be freed
 192 with `gst_object_unref()`. Setting the pipeline to the NULL state will
 193 make sure it frees any resources it has allocated (More about states in
 194 [Basic tutorial 3: Dynamic pipelines]). Finally, unreferencing the
 195 pipeline will destroy it, and all its contents.
 196
 197 _______________________________________________________________________________
 198
 199 ## Conclusion
 200
 201 And so ends your first tutorial with GStreamer. We hope its brevity
 202 serves as an example of how powerful this framework is!
 203
 204 Let's recap a bit. Today we have learned:
 205
 206 -   How to initialize GStreamer using `gst_init()`.
 207
 208 -   How to quickly build a pipeline from a textual description using
 209     `gst_parse_launch()`.
 210
 211 -   How to create an automatic playback pipeline using `playbin`.
 212
 213 -   How to signal GStreamer to start playback using
 214     `gst_element_set_state()`.
 215
 216 -   How to sit back and relax, while GStreamer takes care of everything,
 217     using `gst_element_get_bus()` and `gst_bus_timed_pop_filtered()`.
 218
 219 The next tutorial will keep introducing more basic GStreamer elements,
 220 and show you how to build a pipeline manually.
 221
 222 It has been a pleasure having you here, and see you soon!
 223
 224   [Installing on Linux]: installing/on-linux.md
 225   [Installing on Mac OS X]: installing/on-mac-osx.md
 226   [Installing on Windows]: installing/on-windows.md
 227   [Information]: images/icons/emoticons/information.png
 228   [Linux]: installing/on-linux.md#InstallingonLinux-Build
 229   [Mac OS X]: installing/on-mac-osx.md#InstallingonMacOSX-Build
 230   [Windows]: installing/on-windows.md#InstallingonWindows-Build
 231   [1]: installing/on-linux.md#InstallingonLinux-Run
 232   [2]: installing/on-mac-osx.md#InstallingonMacOSX-Run
 233   [3]: installing/on-windows.md#InstallingonWindows-Run
 234   [Basic tutorial 12: Streaming]: tutorials/basic/streaming.md
 235   [Basic tutorial 10: GStreamer tools]: tutorials/basic/gstreamer-tools.md
 236   [Basic tutorial 2: GStreamer concepts]: tutorials/basic/concepts.md
 237   [Basic tutorial 3: Dynamic pipelines]: tutorials/basic/dynamic-pipelines.md