gstreamer/sdk-basic-tutorial-hello-world.md

237 lines
8.9 KiB
Markdown
Raw Normal View History

2016-06-05 20:54:27 +00:00
---
short-description: The mandatory 'Hello world' example
...
# Basic tutorial 1: Hello world!
2016-05-16 14:30:34 +00:00
2016-05-17 14:52:21 +00:00
## Goal
2016-05-16 14:30:34 +00:00
Nothing better to get a first impression about a software library than
2016-05-17 14:52:21 +00:00
to print “Hello World” on the screen!
2016-05-16 14:30:34 +00:00
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.
Without further ado, get ready for your first GStreamer application...
2016-05-17 14:52:21 +00:00
## Hello world
2016-05-16 14:30:34 +00:00
2016-05-17 14:52:21 +00:00
Copy this code into a text file named `basic-tutorial-1.c` (or find it
2016-05-16 14:30:34 +00:00
in the SDK installation).
**basic-tutorial-1.c**
2016-06-05 20:54:27 +00:00
{{ examples/basic-tutorial-1.c }}
2016-05-16 14:30:34 +00:00
Compile it as described in [Installing on Linux], [Installing on Mac OS
X] or [Installing on Windows]. If you get compilation errors,
2016-05-16 14:30:34 +00:00
double-check the instructions given in those sections.
2016-05-17 14:52:21 +00:00
If everything built fine, fire up the executable! You should see a
2016-05-16 14:30:34 +00:00
window pop up, containing a video being played straight from the
2016-05-17 14:52:21 +00:00
Internet, along with audio. Congratulations!
> ![Information] Need help?
2016-05-17 14:52:21 +00:00
>
> 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:
2016-05-17 14:52:21 +00:00
>
2016-05-27 18:49:41 +00:00
> `` gcc basic-tutorial-1.c -o basic-tutorial-1 `pkg-config --cflags --libs gstreamer-1.0` ``
2016-05-17 14:52:21 +00:00
>
> If you need help to run this code, refer to the **Running the
> tutorials** section for your platform: [Linux][1], [Mac OS X][2] or
> [Windows][3].
2016-05-17 14:52:21 +00:00
>
> 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.
2016-05-17 14:52:21 +00:00
>
> Required libraries: `gstreamer-1.0`
2016-05-17 14:52:21 +00:00
## Walkthrough
2016-05-16 14:30:34 +00:00
Let's review these lines of code and see what they do:
2016-06-06 00:58:09 +00:00
``` c
/* Initialize GStreamer */
gst_init (&argc, &argv);
2016-05-16 14:30:34 +00:00
```
This must always be your first GStreamer command. Among other things,
`gst_init()`:
- Initializes all internal structures
2016-05-16 14:30:34 +00:00
- Checks what plug-ins are available
2016-05-16 14:30:34 +00:00
- Executes any command-line option intended for GStreamer
2016-05-16 14:30:34 +00:00
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])
2016-05-16 14:30:34 +00:00
2016-06-06 00:58:09 +00:00
``` c
/* Build the pipeline */
pipeline = gst_parse_launch ("playbin uri=http://docs.gstreamer.com/media/sintel_trailer-480p.webm", NULL);
2016-05-16 14:30:34 +00:00
```
This line is the heart of this tutorial, and exemplifies **two** key
2016-05-17 14:52:21 +00:00
points: `gst_parse_launch()` and `playbin`.
2016-05-16 14:30:34 +00:00
### gst\_parse\_launch
2016-05-16 14:30:34 +00:00
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”.
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()`.
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][Basic
tutorial 10: GStreamer tools] to learn about `gst-launch-1.0` and the
`gst-launch-1.0` syntax).
2016-05-16 14:30:34 +00:00
2016-05-17 14:52:21 +00:00
### playbin
2016-05-16 14:30:34 +00:00
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
2016-05-17 14:52:21 +00:00
composed of a single element called `playbin`.
2016-05-16 14:30:34 +00:00
`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.
2016-05-16 14:30:34 +00:00
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.
2016-05-17 14:52:21 +00:00
In this example, we are only passing one parameter to `playbin`, which
2016-05-16 14:30:34 +00:00
is the URI of the media we want to play. Try changing it to something
2016-05-17 14:52:21 +00:00
else! Whether it is an `http://` or `file://` URI, `playbin` will
instantiate the appropriate GStreamer source transparently!
2016-05-16 14:30:34 +00:00
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.
2016-06-06 00:58:09 +00:00
``` c
/* Start playing */
gst_element_set_state (pipeline, GST_STATE_PLAYING);
2016-05-16 14:30:34 +00:00
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.
2016-05-17 14:52:21 +00:00
In this line, `gst_element_set_state()` is setting `pipeline` (our only
2016-05-16 14:30:34 +00:00
element, remember) to the PLAYING state, thus initiating playback.
2016-05-17 14:52:21 +00:00
```
2016-06-06 00:58:09 +00:00
``` c
/* Wait until error or EOS */
bus = gst_element_get_bus (pipeline);
gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE, GST_MESSAGE_ERROR | GST_MESSAGE_EOS);
2016-05-16 14:30:34 +00:00
```
2016-05-17 14:52:21 +00:00
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
2016-05-16 14:30:34 +00:00
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].
2016-05-16 14:30:34 +00:00
2016-05-17 14:52:21 +00:00
And that's it! From this point onwards, GStreamer takes care of
2016-05-16 14:30:34 +00:00
everything. Execution will end when the media reaches its end (EOS) or
2016-05-17 14:52:21 +00:00
an error is encountered (try closing the video window, or unplugging the
network cable). The application can always be stopped by pressing
2016-05-16 14:30:34 +00:00
control-C in the console.
2016-05-17 14:52:21 +00:00
### Cleanup
2016-05-16 14:30:34 +00:00
Before terminating the application, though, there is a couple of things
we need to do to tidy up correctly after ourselves.
2016-06-06 00:58:09 +00:00
``` c
/* Free resources */
if (msg != NULL)
gst_message_unref (msg);
gst_object_unref (bus);
gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (pipeline);
2016-05-16 14:30:34 +00:00
```
Always read the documentation of the functions you use, to know if you
should free the objects they return after using them.
2016-05-17 14:52:21 +00:00
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][Basic tutorial 2: GStreamer
concepts]).
2016-05-16 14:30:34 +00:00
2016-05-17 14:52:21 +00:00
`gst_element_get_bus()` added a reference to the bus that must be freed
2016-05-16 14:30:34 +00:00
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.
_______________________________________________________________________________
2016-05-16 14:30:34 +00:00
2016-05-17 14:52:21 +00:00
## Conclusion
2016-05-16 14:30:34 +00:00
And so ends your first tutorial with GStreamer. We hope its brevity
2016-05-17 14:52:21 +00:00
serves as an example of how powerful this framework is!
2016-05-16 14:30:34 +00:00
Let's recap a bit. Today we have learned:
- How to initialize GStreamer using `gst_init()`.
2016-05-16 14:30:34 +00:00
- How to quickly build a pipeline from a textual description using
2016-05-16 14:30:34 +00:00
`gst_parse_launch()`.
- How to create an automatic playback pipeline using `playbin`.
2016-05-16 14:30:34 +00:00
- How to signal GStreamer to start playback using
2016-05-16 14:30:34 +00:00
`gst_element_set_state()`.
- How to sit back and relax, while GStreamer takes care of everything,
2016-05-17 14:52:21 +00:00
using `gst_element_get_bus()` and `gst_bus_timed_pop_filtered()`.
2016-05-16 14:30:34 +00:00
The next tutorial will keep introducing more basic GStreamer elements,
and show you how to build a pipeline manually.
2016-05-17 14:52:21 +00:00
It has been a pleasure having you here, and see you soon!
2016-06-05 21:32:50 +00:00
[Installing on Linux]: sdk-installing-on-linux.md
[Installing on Mac OS X]: sdk-installing-on-mac-osx.md
[Installing on Windows]: sdk-installing-on-windows.md
[Information]: images/icons/emoticons/information.png
2016-06-05 21:32:50 +00:00
[Linux]: sdk-installing-on-linux.md#InstallingonLinux-Build
[Mac OS X]: sdk-installing-on-mac-osx.md#InstallingonMacOSX-Build
[Windows]: sdk-installing-on-windows.md#InstallingonWindows-Build
[1]: sdk-installing-on-linux.md#InstallingonLinux-Run
[2]: sdk-installing-on-mac-osx.md#InstallingonMacOSX-Run
[3]: sdk-installing-on-windows.md#InstallingonWindows-Run
[Basic tutorial 12: Streaming]: sdk-basic-tutorial-streaming.md
[Basic tutorial 10: GStreamer tools]: sdk-basic-tutorial-gstreamer-tools.md
[Basic tutorial 2: GStreamer concepts]: sdk-basic-tutorial-concepts.md
[Basic tutorial 3: Dynamic pipelines]: sdk-basic-tutorial-dynamic-pipelines.md