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

2024-12-30 12:10:37 +00:00 · 2016-05-27 14:44:08 -04:00 · 2016-05-27 14:44:08 -04:00 · 36731c755f
commit 36731c755f
parent 3fbdccaaeb
2 changed files with 83 additions and 64 deletions
--- 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 <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!

-> ![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
--- 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]