1 <chapter id="chapter-helloworld">
2 <title>Your first application</title>
4 This chapter will summarize everything you've learned in the previous
5 chapters. It describes all aspects of a simple &GStreamer; application,
6 including initializing libraries, creating elements, packing elements
7 together in a pipeline and playing this pipeline. By doing all this,
8 you will be able to build a simple Ogg/Vorbis audio player.
11 <sect1 id="section-helloworld">
12 <title>Hello world</title>
14 We're going to create a simple first application, a simple Ogg/Vorbis
15 command-line audio player. For this, we will use only standard
16 &GStreamer; components. The player will read a file specified on
17 the command-line. Let's get started!
20 We've learned, in <xref linkend="chapter-init"/>, that the first thing
21 to do in your application is to initialize &GStreamer; by calling
22 <function>gst_init ()</function>. Also, make sure that the application
23 includes <filename>gst/gst.h</filename> so all function names and
24 objects are properly defined. Use <function>#include
25 <gst/gst.h></function> to do that.
28 Next, you'll want to create the different elements using
29 <function>gst_element_factory_make ()</function>. For an Ogg/Vorbis
30 audio player, we'll need a source element that reads files from a
31 disk. &GStreamer; includes this element under the name
32 <quote>filesrc</quote>. Next, we'll need something to parse the
33 file and decode it into raw audio. &GStreamer; has two elements
34 for this: the first parses Ogg streams into elementary streams (video,
35 audio) and is called <quote>oggdemux</quote>. The second is a Vorbis
36 audio decoder, it's conveniently called <quote>vorbisdec</quote>.
37 Since <quote>oggdemux</quote> creates dynamic pads for each elementary
38 stream, you'll need to set a <quote>pad-added</quote> event handler
39 on the <quote>oggdemux</quote> element, like you've learned in
40 <xref linkend="section-pads-dynamic"/>, to link the Ogg demuxer and
41 the Vorbis decoder elements together. At last, we'll also need an
42 audio output element, we will use <quote>autoaudiosink</quote>, which
43 automatically detects your audio device.
46 The last thing left to do is to add all elements into a container
47 element, a <classname>GstPipeline</classname>, and iterate this
48 pipeline until we've played the whole song. We've previously
49 learned how to add elements to a container bin in <xref
50 linkend="chapter-bins"/>, and we've learned about element states
51 in <xref linkend="section-elements-states"/>. We will also attach
52 a message handler to the pipeline bus so we can retrieve errors
53 and detect the end-of-stream.
56 Let's now add all the code together to get our very first audio
60 <!-- example-begin helloworld.c -->
61 #include <gst/gst.h>
62 #include <glib.h>
66 bus_call (GstBus *bus,
70 GMainLoop *loop = (GMainLoop *) data;
72 switch (GST_MESSAGE_TYPE (msg)) {
75 g_print ("End of stream\n");
76 g_main_loop_quit (loop);
79 case GST_MESSAGE_ERROR: {
83 gst_message_parse_error (msg, &error, &debug);
86 g_printerr ("Error: %s\n", error->message);
89 g_main_loop_quit (loop);
101 on_pad_added (GstElement *element,
106 GstElement *decoder = (GstElement *) data;
108 /* We can now link this pad with the vorbis-decoder sink pad */
109 g_print ("Dynamic pad created, linking demuxer/decoder\n");
111 sinkpad = gst_element_get_static_pad (decoder, "sink");
113 gst_pad_link (pad, sinkpad);
115 gst_object_unref (sinkpad);
126 GstElement *pipeline, *source, *demuxer, *decoder, *conv, *sink;
130 gst_init (&argc, &argv);
132 loop = g_main_loop_new (NULL, FALSE);
135 /* Check input arguments */
137 g_printerr ("Usage: %s <Ogg/Vorbis filename>\n", argv[0]);
142 /* Create gstreamer elements */
143 pipeline = gst_pipeline_new ("audio-player");
144 source = gst_element_factory_make ("filesrc", "file-source");
145 demuxer = gst_element_factory_make ("oggdemux", "ogg-demuxer");
146 decoder = gst_element_factory_make ("vorbisdec", "vorbis-decoder");
147 conv = gst_element_factory_make ("audioconvert", "converter");
148 sink = gst_element_factory_make ("autoaudiosink", "audio-output");
150 if (!pipeline || !source || !demuxer || !decoder || !conv || !sink) {
151 g_printerr ("One element could not be created. Exiting.\n");
155 /* Set up the pipeline */
157 /* we set the input filename to the source element */
158 g_object_set (G_OBJECT (source), "location", argv[1], NULL);
160 /* we add a message handler */
161 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
162 gst_bus_add_watch (bus, bus_call, loop);
163 gst_object_unref (bus);
165 /* we add all elements into the pipeline */
166 /* file-source | ogg-demuxer | vorbis-decoder | converter | alsa-output */
167 gst_bin_add_many (GST_BIN (pipeline),
168 source, demuxer, decoder, conv, sink, NULL);
170 /* we link the elements together */
171 /* file-source -> ogg-demuxer ~> vorbis-decoder -> converter -> alsa-output */
172 gst_element_link (source, demuxer);
173 gst_element_link_many (decoder, conv, sink, NULL);
174 g_signal_connect (demuxer, "pad-added", G_CALLBACK (on_pad_added), decoder);
176 /* note that the demuxer will be linked to the decoder dynamically.
177 The reason is that Ogg may contain various streams (for example
178 audio and video). The source pad(s) will be created at run time,
179 by the demuxer when it detects the amount and nature of streams.
180 Therefore we connect a callback function which will be executed
181 when the "pad-added" is emitted.*/
184 /* Set the pipeline to "playing" state*/
185 g_print ("Now playing: %s\n", argv[1]);
186 gst_element_set_state (pipeline, GST_STATE_PLAYING);
190 g_print ("Running...\n");
191 g_main_loop_run (loop);
194 /* Out of the main loop, clean up nicely */
195 g_print ("Returned, stopping playback\n");
196 gst_element_set_state (pipeline, GST_STATE_NULL);
198 g_print ("Deleting pipeline\n");
199 gst_object_unref (GST_OBJECT (pipeline));
203 <!-- example-end helloworld.c -->
206 We now have created a complete pipeline. We can visualise the
210 <figure float="1" id="section-hello-img">
211 <title>The "hello world" pipeline</title>
214 <imagedata scale="75" fileref="images/hello-world.ℑ" format="&IMAGE;" />
221 <sect1 id="section-helloworld-compilerun">
222 <title>Compiling and Running helloworld.c</title>
224 To compile the helloworld example, use: <command>gcc -Wall
225 $(pkg-config --cflags --libs gstreamer-&GST_MAJORMINOR;)
226 helloworld.c -o helloworld</command>. &GStreamer; makes use of
227 <command>pkg-config</command> to get compiler and linker flags
228 needed to compile this application. If you're running a
229 non-standard installation, make sure the
230 <classname>PKG_CONFIG_PATH</classname> environment variable is
231 set to the correct location (<filename>$libdir/pkgconfig</filename>).
232 application against the uninstalled location.
235 You can run this example application with <command>./helloworld
236 file.ogg</command>. Substitute <filename>file.ogg</filename>
237 with your favourite Ogg/Vorbis file.
241 <sect1 id="section-hello-world-conclusion">
242 <title>Conclusion</title>
244 This concludes our first example. As you see, setting up a pipeline
245 is very low-level but powerful. You will see later in this manual how
246 you can create a more powerful media player with even less effort
247 using higher-level interfaces. We will discuss all that in <xref
248 linkend="part-highlevel"/>. We will first, however, go more in-depth
249 into more advanced &GStreamer; internals.
252 It should be clear from the example that we can very easily replace
253 the <quote>filesrc</quote> element with some other element that
254 reads data from a network, or some other data source element that
255 is better integrated with your desktop environment. Also, you can
256 use other decoders and parsers/demuxers to support other media types. You
257 can use another audio sink if you're not running Linux, but Mac OS X,
258 Windows or FreeBSD, or you can instead use a filesink to write audio
259 files to disk instead of playing them back. By using an audio card
260 source, you can even do audio capture instead of playback. All this
261 shows the reusability of &GStreamer; elements, which is its greatest