From 36731c755fc860bd260e230f8426a59592bcde22 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Fri, 27 May 2016 14:44:08 -0400 Subject: [PATCH] Basic+tutorial+1+Hello+world.markdown: cleanup --- Basic+tutorial+1+Hello+world.markdown | 145 +++++++++++++++----------- TODO.markdown | 2 +- 2 files changed, 83 insertions(+), 64 deletions(-) diff --git a/Basic+tutorial+1+Hello+world.markdown b/Basic+tutorial+1+Hello+world.markdown index 9e1562e1b7..fc64167989 100644 --- a/Basic+tutorial+1+Hello+world.markdown +++ b/Basic+tutorial+1+Hello+world.markdown @@ -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 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! -> ![Information](images/icons/emoticons/information.png) -> 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 diff --git a/TODO.markdown b/TODO.markdown index b56b20f872..ea5c8bb8b8 100644 --- a/TODO.markdown +++ b/TODO.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]