mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-08-01 03:05:10 +00:00
Basic+tutorial+1+Hello+world.markdown: cleanup
This commit is contained in:
Thibault Saunier
parent
3fbdccaaeb
commit
36731c755f
|
|
@ -1,4 +1,4 @@
|
|||
# Basic tutorial 1: Hello world!
|
||||
# Basic tutorial 1: Hello world!
|
||||
|
||||
## Goal
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ in the SDK installation).
|
|||
|
||||
**basic-tutorial-1.c**
|
||||
|
||||
```
|
||||
``` lang=c
|
||||
#include <gst/gst.h>
|
||||
|
||||
int main(int argc, char *argv[]) {
|
||||
|
|
@ -52,62 +52,67 @@ int main(int argc, char *argv[]) {
|
|||
}
|
||||
```
|
||||
|
||||
Compile it as described in [Installing on
|
||||
Linux](Installing+on+Linux.markdown), [Installing on Mac OS
|
||||
X](Installing+on+Mac+OS+X.markdown) or [Installing on
|
||||
Windows](Installing+on+Windows.markdown). If you get compilation errors,
|
||||
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.
|
||||
|
||||
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!
|
||||
|
||||
> 
|
||||
> Need help?
|
||||
> ![Information] Need help?
|
||||
>
|
||||
> If you need help to compile this code, refer to the **Building the tutorials** section for your platform: [Linux](Installing+on+Linux.markdown#InstallingonLinux-Build), [Mac OS X](Installing+on+Mac+OS+X.markdown#InstallingonMacOSX-Build) or [Windows](Installing+on+Windows.markdown#InstallingonWindows-Build), or use this specific command on Linux:
|
||||
> 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:
|
||||
>
|
||||
> ``gcc basic-tutorial-1.c -o basic-tutorial-1 `pkg-config --cflags --libs gstreamer-0.10` ``
|
||||
> `` gcc basic-tutorial-1.c -o basic-tutorial-1 `pkg-config --cflags --libs gstreamer-0.10` ``
|
||||
>
|
||||
>If you need help to run this code, refer to the **Running the tutorials** section for your platform: [Linux](Installing+on+Linux.markdown#InstallingonLinux-Run), [Mac OS X](Installing+on+Mac+OS+X.markdown#InstallingonMacOSX-Run) or [Windows](Installing+on+Windows.markdown#InstallingonWindows-Run).
|
||||
> 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].
|
||||
>
|
||||
>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](Basic+tutorial+12+Streaming.markdown) solves this issue.
|
||||
> 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.
|
||||
>
|
||||
>Required libraries: `gstreamer-1.0`
|
||||
> Required libraries: `gstreamer-1.0`
|
||||
|
||||
## Walkthrough
|
||||
|
||||
Let's review these lines of code and see what they do:
|
||||
|
||||
```
|
||||
/* Initialize GStreamer */
|
||||
gst_init (&argc, &argv);
|
||||
``` lang=c
|
||||
/* Initialize GStreamer */
|
||||
gst_init (&argc, &argv);
|
||||
```
|
||||
|
||||
This must always be your first GStreamer command. Among other things,
|
||||
`gst_init()`:
|
||||
|
||||
- Initializes all internal structures
|
||||
- Initializes all internal structures
|
||||
|
||||
- Checks what plug-ins are available
|
||||
- Checks what plug-ins are available
|
||||
|
||||
- Executes any command-line option intended for GStreamer
|
||||
- Executes any command-line option intended for 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](Basic+tutorial+10+GStreamer+tools.markdown))
|
||||
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])
|
||||
|
||||
```
|
||||
/* Build the pipeline */
|
||||
pipeline = gst_parse_launch ("playbin uri=http://docs.gstreamer.com/media/sintel_trailer-480p.webm", NULL);
|
||||
``` lang=c
|
||||
/* Build the pipeline */
|
||||
pipeline = gst_parse_launch ("playbin uri=http://docs.gstreamer.com/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
|
||||
### gst\_parse\_launch
|
||||
|
||||
GStreamer is a framework designed to handle multimedia flows. Media
|
||||
travels from the “source” elements (the producers), down to the “sink”
|
||||
|
|
@ -123,9 +128,9 @@ not need any advanced features, you can take the shortcut:
|
|||
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.markdown) to
|
||||
learn about `gst-launch-1.0` and the `gst-launch-1.0` syntax).
|
||||
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).
|
||||
|
||||
### playbin
|
||||
|
||||
|
|
@ -133,10 +138,10 @@ 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`.
|
||||
|
||||
`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` 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.
|
||||
|
||||
It does not allow the control granularity that a manual pipeline does,
|
||||
but, still, it permits enough customization to suffice for a wide range
|
||||
|
|
@ -152,10 +157,9 @@ 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.
|
||||
|
||||
```
|
||||
/* Start playing */
|
||||
gst_element_set_state (pipeline, GST_STATE_PLAYING);
|
||||
```
|
||||
``` lang=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
|
||||
|
|
@ -165,11 +169,12 @@ to the PLAYING state.
|
|||
|
||||
In this line, `gst_element_set_state()` is setting `pipeline` (our only
|
||||
element, remember) to the PLAYING state, thus initiating playback.
|
||||
|
||||
```
|
||||
/* 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);
|
||||
|
||||
``` lang=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);
|
||||
```
|
||||
|
||||
These lines will wait until an error occurs or the end of the stream is
|
||||
|
|
@ -177,8 +182,7 @@ 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](Basic+tutorial+2+GStreamer+concepts.markdown).
|
||||
GStreamer concepts].
|
||||
|
||||
And that's it! From this point onwards, GStreamer takes care of
|
||||
everything. Execution will end when the media reaches its end (EOS) or
|
||||
|
|
@ -191,13 +195,13 @@ control-C in the console.
|
|||
Before terminating the application, though, there is a couple of things
|
||||
we need to do to tidy up correctly after ourselves.
|
||||
|
||||
```
|
||||
/* 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);
|
||||
``` lang=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);
|
||||
```
|
||||
|
||||
Always read the documentation of the functions you use, to know if you
|
||||
|
|
@ -205,16 +209,16 @@ 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](Basic+tutorial+2+GStreamer+concepts.markdown)).
|
||||
[Basic tutorial 2: GStreamer concepts][Basic tutorial 2: GStreamer
|
||||
concepts]).
|
||||
|
||||
`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](Basic+tutorial+3+Dynamic+pipelines.markdown)).
|
||||
Finally, unreferencing the pipeline will destroy it, and all its
|
||||
contents.
|
||||
[Basic tutorial 3: Dynamic pipelines]). Finally, unreferencing the
|
||||
pipeline will destroy it, and all its contents.
|
||||
|
||||
_______________________________________________________________________________
|
||||
|
||||
## Conclusion
|
||||
|
||||
|
|
@ -223,20 +227,35 @@ serves as an example of how powerful this framework is!
|
|||
|
||||
Let's recap a bit. Today we have learned:
|
||||
|
||||
- How to initialize GStreamer using `gst_init()`.
|
||||
- How to initialize GStreamer using `gst_init()`.
|
||||
|
||||
- How to quickly build a pipeline from a textual description using
|
||||
- How to quickly build a pipeline from a textual description using
|
||||
`gst_parse_launch()`.
|
||||
|
||||
- How to create an automatic playback pipeline using `playbin`.
|
||||
- How to create an automatic playback pipeline using `playbin`.
|
||||
|
||||
- How to signal GStreamer to start playback using
|
||||
- How to signal GStreamer to start playback using
|
||||
`gst_element_set_state()`.
|
||||
|
||||
- How to sit back and relax, while GStreamer takes care of everything,
|
||||
- How to sit back and relax, while GStreamer takes care of everything,
|
||||
using `gst_element_get_bus()` and `gst_bus_timed_pop_filtered()`.
|
||||
|
||||
The next tutorial will keep introducing more basic GStreamer elements,
|
||||
and show you how to build a pipeline manually.
|
||||
|
||||
It has been a pleasure having you here, and see you soon!
|
||||
|
||||
[Installing on Linux]: Installing+on+Linux.markdown
|
||||
[Installing on Mac OS X]: Installing+on+Mac+OS+X.markdown
|
||||
[Installing on Windows]: Installing+on+Windows.markdown
|
||||
[Information]: images/icons/emoticons/information.png
|
||||
[Linux]: Installing+on+Linux.markdown#InstallingonLinux-Build
|
||||
[Mac OS X]: Installing+on+Mac+OS+X.markdown#InstallingonMacOSX-Build
|
||||
[Windows]: Installing+on+Windows.markdown#InstallingonWindows-Build
|
||||
[1]: Installing+on+Linux.markdown#InstallingonLinux-Run
|
||||
[2]: Installing+on+Mac+OS+X.markdown#InstallingonMacOSX-Run
|
||||
[3]: Installing+on+Windows.markdown#InstallingonWindows-Run
|
||||
[Basic tutorial 12: Streaming]: Basic+tutorial+12+Streaming.markdown
|
||||
[Basic tutorial 10: GStreamer tools]: Basic+tutorial+10+GStreamer+tools.markdown
|
||||
[Basic tutorial 2: GStreamer concepts]: Basic+tutorial+2+GStreamer+concepts.markdown
|
||||
[Basic tutorial 3: Dynamic pipelines]: Basic+tutorial+3+Dynamic+pipelines.markdown
|
||||
|
|
|
|||
|
|
@ -5,7 +5,6 @@ gstreamer.com content to hotdoc
|
|||
|
||||
Pages to review:
|
||||
- Basic+tutorials.markdown
|
||||
- Basic+tutorial+1+Hello+world.markdown
|
||||
- Basic+tutorial+2+GStreamer+concepts.markdown
|
||||
- Basic+tutorial+3+Dynamic+pipelines.markdown
|
||||
- Basic+tutorial+4+Time+management.markdown
|
||||
|
|
@ -74,6 +73,7 @@ Reviewed pages:
|
|||
- Android+tutorial+2+A+running+pipeline.markdown
|
||||
- GStreamer+reference.markdown
|
||||
- Playback+tutorial+1+Playbin+usage.markdown
|
||||
- Basic+tutorial+1+Hello+world.markdown
|
||||
|
||||
For-later pages:
|
||||
- Qt+tutorials.markdown [tpm: this should all be rewritten from scratch with qmlglsink; QtGStreamer is outdated and unmaintained, we should not promote it]
|
||||
|
|
|
|||
Loading…
Reference in a new issue