mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-02 05:28:48 +00:00
Code Issues 1 Projects Releases Wiki Activity

Basic+tutorial+1+Hello+world.markdown: cleanup

Browse source
This commit is contained in:
Thibault Saunier 2016-05-27 14:44:08 -04:00
parent 3fbdccaaeb
commit 36731c755f
2 changed files with 83 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
Basic+tutorial+1+Hello+world.markdown
View file

@ -1,4 +1,4 @@
# Basic tutorial 1: Hello world! # Basic tutorial 1: Hello world!
## Goal ## Goal
@ -21,7 +21,7 @@ in the SDK installation).
**basic-tutorial-1.c** **basic-tutorial-1.c**
``` ``` lang=c
#include <gst/gst.h> #include <gst/gst.h>
int main(int argc, char *argv[]) { int main(int argc, char *argv[]) {
@ -52,62 +52,67 @@ int main(int argc, char *argv[]) {
} }
``` ```
Compile it as described in [Installing on Compile it as described in [Installing on Linux], [Installing on Mac OS
Linux](Installing+on+Linux.markdown), [Installing on Mac OS X] or [Installing on Windows]. If you get compilation errors,
X](Installing+on+Mac+OS+X.markdown) or [Installing on
Windows](Installing+on+Windows.markdown). If you get compilation errors,
double-check the instructions given in those sections. double-check the instructions given in those sections.
If everything built fine, fire up the executable! You should see a If everything built fine, fire up the executable! You should see a
window pop up, containing a video being played straight from the window pop up, containing a video being played straight from the
Internet, along with audio. Congratulations! Internet, along with audio. Congratulations!
> ![Information](images/icons/emoticons/information.png) > ![Information] Need help?
> 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 ## Walkthrough
Let's review these lines of code and see what they do: Let's review these lines of code and see what they do:
``` ``` lang=c
/* Initialize GStreamer */ /* Initialize GStreamer */
gst_init (&argc, &argv); gst_init (&argc, &argv);
``` ```
This must always be your first GStreamer command. Among other things, This must always be your first GStreamer command. Among other things,
`gst_init()`: `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 If you always pass your command-line parameters
`gst_init()`, your application will automatically benefit from the `argc` and `argv` to `gst_init()` your application will automatically
GStreamer standard command-line options (more on this in [Basic tutorial benefit from the GStreamer standard command-line options (more on this
10: GStreamer in [Basic tutorial 10: GStreamer tools])
tools](Basic+tutorial+10+GStreamer+tools.markdown))
``` ``` lang=c
/* Build the pipeline */ /* Build the pipeline */
pipeline = gst_parse_launch ("playbin uri=http://docs.gstreamer.com/media/sintel_trailer-480p.webm", NULL); 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 This line is the heart of this tutorial, and exemplifies **two** key
points: `gst_parse_launch()` and `playbin`. points: `gst_parse_launch()` and `playbin`.
### gst_parse_launch ### gst\_parse\_launch
GStreamer is a framework designed to handle multimedia flows. Media GStreamer is a framework designed to handle multimedia flows. Media
travels from the “source” elements (the producers), down to the “sink” 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 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 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 so handy there is a tool built completely around it which you will get
very acquainted with (see [Basic tutorial 10: GStreamer very acquainted with (see [Basic tutorial 10: GStreamer tools][Basic
tools](Basic+tutorial+10+GStreamer+tools.markdown) to tutorial 10: GStreamer tools] to learn about `gst-launch-1.0` and the
learn about `gst-launch-1.0` and the `gst-launch-1.0` syntax). `gst-launch-1.0` syntax).
### playbin ### 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 us? Here enters the second key point: We are building a pipeline
composed of a single element called `playbin`. composed of a single element called `playbin`.
`playbin` is a special element which acts as a source and as a sink, `playbin` is a special element which acts as a source and as a sink, and
and is a whole pipeline. Internally, it creates is a whole pipeline. Internally, it creates and connects all the
and connects all the necessary elements to play your media, so you do necessary elements to play your media, so you do not have to worry about
not have to worry about it. it.
It does not allow the control granularity that a manual pipeline does, It does not allow the control granularity that a manual pipeline does,
but, still, it permits enough customization to suffice for a wide range 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 only thing we are doing in this example is exiting on error, so do not
expect much feedback. expect much feedback.
``` ``` lang=c
/* Start playing */ /* Start playing */
gst_element_set_state (pipeline, GST_STATE_PLAYING); gst_element_set_state (pipeline, GST_STATE_PLAYING);
```
This line highlights another interesting concept: the state. Every This line highlights another interesting concept: the state. Every
GStreamer element has an associated state, which you can more or less 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 In this line, `gst_element_set_state()` is setting `pipeline` (our only
element, remember) to the PLAYING state, thus initiating playback. element, remember) to the PLAYING state, thus initiating playback.
``` ```
/* Wait until error or EOS */
bus = gst_element_get_bus (pipeline); ``` lang=c
gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE, GST_MESSAGE_ERROR | GST_MESSAGE_EOS); /* 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 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 `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 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: about this line, the GStreamer bus is explained in [Basic tutorial 2:
GStreamer GStreamer concepts].
concepts](Basic+tutorial+2+GStreamer+concepts.markdown).
And that's it! From this point onwards, GStreamer takes care of And that's it! From this point onwards, GStreamer takes care of
everything. Execution will end when the media reaches its end (EOS) or 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 Before terminating the application, though, there is a couple of things
we need to do to tidy up correctly after ourselves. we need to do to tidy up correctly after ourselves.
``` ``` lang=c
/* Free resources */ /* Free resources */
if (msg != NULL) if (msg != NULL)
gst_message_unref (msg); gst_message_unref (msg);
gst_object_unref (bus); gst_object_unref (bus);
gst_element_set_state (pipeline, GST_STATE_NULL); gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (pipeline); gst_object_unref (pipeline);
``` ```
Always read the documentation of the functions you use, to know if you 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 In this case, `gst_bus_timed_pop_filtered()` returned a message which
needs to be freed with `gst_message_unref()` (more about messages in needs to be freed with `gst_message_unref()` (more about messages in
[Basic tutorial 2: GStreamer [Basic tutorial 2: GStreamer concepts][Basic tutorial 2: GStreamer
concepts](Basic+tutorial+2+GStreamer+concepts.markdown)). concepts]).
`gst_element_get_bus()` added a reference to the bus that must be freed `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 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 make sure it frees any resources it has allocated (More about states in
[Basic tutorial 3: Dynamic [Basic tutorial 3: Dynamic pipelines]). Finally, unreferencing the
pipelines](Basic+tutorial+3+Dynamic+pipelines.markdown)). pipeline will destroy it, and all its contents.
Finally, unreferencing the pipeline will destroy it, and all its
contents. _______________________________________________________________________________
## Conclusion ## Conclusion
@ -223,20 +227,35 @@ serves as an example of how powerful this framework is!
Let's recap a bit. Today we have learned: 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()`. `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()`. `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()`. using `gst_element_get_bus()` and `gst_bus_timed_pop_filtered()`.
The next tutorial will keep introducing more basic GStreamer elements, The next tutorial will keep introducing more basic GStreamer elements,
and show you how to build a pipeline manually. and show you how to build a pipeline manually.
It has been a pleasure having you here, and see you soon! 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

2
TODO.markdown
View file

@ -5,7 +5,6 @@ gstreamer.com content to hotdoc
Pages to review: Pages to review:
- Basic+tutorials.markdown - Basic+tutorials.markdown
- Basic+tutorial+1+Hello+world.markdown
- Basic+tutorial+2+GStreamer+concepts.markdown - Basic+tutorial+2+GStreamer+concepts.markdown
- Basic+tutorial+3+Dynamic+pipelines.markdown - Basic+tutorial+3+Dynamic+pipelines.markdown
- Basic+tutorial+4+Time+management.markdown - Basic+tutorial+4+Time+management.markdown
@ -74,6 +73,7 @@ Reviewed pages:
- Android+tutorial+2+A+running+pipeline.markdown - Android+tutorial+2+A+running+pipeline.markdown
- GStreamer+reference.markdown - GStreamer+reference.markdown
- Playback+tutorial+1+Playbin+usage.markdown - Playback+tutorial+1+Playbin+usage.markdown
- Basic+tutorial+1+Hello+world.markdown
For-later pages: 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] - Qt+tutorials.markdown [tpm: this should all be rewritten from scratch with qmlglsink; QtGStreamer is outdated and unmaintained, we should not promote it]