2 title: Your first application
5 # Your first application
7 This chapter will summarize everything you've learned in the previous
8 chapters. It describes all aspects of a simple GStreamer application,
9 including initializing libraries, creating elements, packing elements
10 together in a pipeline and playing this pipeline. By doing all this, you
11 will be able to build a simple Ogg/Vorbis audio player.
15 We're going to create a simple first application, a simple Ogg/Vorbis
16 command-line audio player. For this, we will use only standard GStreamer
17 components. The player will read a file specified on the command-line.
20 We've learned, in [Initializing GStreamer](manual/building/init.md), that the
21 first thing to do in your application is to initialize GStreamer by
22 calling `gst_init ()`. Also, make sure that the application includes
23 `gst/gst.h` so all function names and objects are properly defined. Use
25 <gst/gst.h>` to do that.
27 Next, you'll want to create the different elements using
28 `gst_element_factory_make ()`. For an Ogg/Vorbis audio player, we'll
29 need a source element that reads files from a disk. GStreamer includes
30 this element under the name “filesrc”. Next, we'll need something to
31 parse the file and decode it into raw audio. GStreamer has two elements
32 for this: the first parses Ogg streams into elementary streams (video,
33 audio) and is called “oggdemux”. The second is a Vorbis audio decoder,
34 it's conveniently called “vorbisdec”. Since “oggdemux” creates dynamic
35 pads for each elementary stream, you'll need to set a “pad-added” event
36 handler on the “oggdemux” element, like you've learned in [Dynamic (or
37 sometimes) pads](manual/building/pads.md#dynamic-or-sometimes-pads), to link the
38 Ogg demuxer and the Vorbis decoder elements together. At last, we'll
39 also need an audio output element, we will use “autoaudiosink”, which
40 automatically detects your audio device.
42 The last thing left to do is to add all elements into a container
43 element, a `GstPipeline`, and wait until we've played the whole song.
44 We've previously learned how to add elements to a container bin in
45 [Bins](manual/building/bins.md), and we've learned about element states in
46 [Element States](manual/building/elements.md#element-states). We will also
47 attach a message handler to the pipeline bus so we can retrieve errors
48 and detect the end-of-stream.
50 Let's now add all the code together to get our very first audio player:
59 bus_call (GstBus *bus,
63 GMainLoop *loop = (GMainLoop *) data;
65 switch (GST_MESSAGE_TYPE (msg)) {
68 g_print ("End of stream\n");
69 g_main_loop_quit (loop);
72 case GST_MESSAGE_ERROR: {
76 gst_message_parse_error (msg, &error, &debug);
79 g_printerr ("Error: %s\n", error->message);
82 g_main_loop_quit (loop);
94 on_pad_added (GstElement *element,
99 GstElement *decoder = (GstElement *) data;
101 /* We can now link this pad with the vorbis-decoder sink pad */
102 g_print ("Dynamic pad created, linking demuxer/decoder\n");
104 sinkpad = gst_element_get_static_pad (decoder, "sink");
106 gst_pad_link (pad, sinkpad);
108 gst_object_unref (sinkpad);
119 GstElement *pipeline, *source, *demuxer, *decoder, *conv, *sink;
124 gst_init (&argc, &argv);
126 loop = g_main_loop_new (NULL, FALSE);
129 /* Check input arguments */
131 g_printerr ("Usage: %s <Ogg/Vorbis filename>\n", argv[0]);
136 /* Create gstreamer elements */
137 pipeline = gst_pipeline_new ("audio-player");
138 source = gst_element_factory_make ("filesrc", "file-source");
139 demuxer = gst_element_factory_make ("oggdemux", "ogg-demuxer");
140 decoder = gst_element_factory_make ("vorbisdec", "vorbis-decoder");
141 conv = gst_element_factory_make ("audioconvert", "converter");
142 sink = gst_element_factory_make ("autoaudiosink", "audio-output");
144 if (!pipeline || !source || !demuxer || !decoder || !conv || !sink) {
145 g_printerr ("One element could not be created. Exiting.\n");
149 /* Set up the pipeline */
151 /* we set the input filename to the source element */
152 g_object_set (G_OBJECT (source), "location", argv[1], NULL);
154 /* we add a message handler */
155 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
156 bus_watch_id = gst_bus_add_watch (bus, bus_call, loop);
157 gst_object_unref (bus);
159 /* we add all elements into the pipeline */
160 /* file-source | ogg-demuxer | vorbis-decoder | converter | alsa-output */
161 gst_bin_add_many (GST_BIN (pipeline),
162 source, demuxer, decoder, conv, sink, NULL);
164 /* we link the elements together */
165 /* file-source -> ogg-demuxer ~> vorbis-decoder -> converter -> alsa-output */
166 gst_element_link (source, demuxer);
167 gst_element_link_many (decoder, conv, sink, NULL);
168 g_signal_connect (demuxer, "pad-added", G_CALLBACK (on_pad_added), decoder);
170 /* note that the demuxer will be linked to the decoder dynamically.
171 The reason is that Ogg may contain various streams (for example
172 audio and video). The source pad(s) will be created at run time,
173 by the demuxer when it detects the amount and nature of streams.
174 Therefore we connect a callback function which will be executed
175 when the "pad-added" is emitted.*/
178 /* Set the pipeline to "playing" state*/
179 g_print ("Now playing: %s\n", argv[1]);
180 gst_element_set_state (pipeline, GST_STATE_PLAYING);
184 g_print ("Running...\n");
185 g_main_loop_run (loop);
188 /* Out of the main loop, clean up nicely */
189 g_print ("Returned, stopping playback\n");
190 gst_element_set_state (pipeline, GST_STATE_NULL);
192 g_print ("Deleting pipeline\n");
193 gst_object_unref (GST_OBJECT (pipeline));
194 g_source_remove (bus_watch_id);
195 g_main_loop_unref (loop);
203 We now have created a complete pipeline. We can visualise the pipeline
206 ![The "hello world" pipeline](images/hello-world.png "fig:")
208 ## Compiling and Running helloworld.c
210 To compile the helloworld example, use: `gcc -Wall
211 helloworld.c -o helloworld
212 $(pkg-config --cflags --libs gstreamer-1.0)`. GStreamer makes use of
213 `pkg-config` to get compiler and linker flags needed to compile this
216 If you're running a non-standard installation (ie. you've installed
217 GStreamer from source yourself instead of using pre-built packages),
218 make sure the `PKG_CONFIG_PATH` environment variable is set to the
219 correct location (`$libdir/pkgconfig`).
221 In the unlikely case that you are using an uninstalled GStreamer setup
222 (ie. gst-uninstalled), you will need to use libtool to build the hello
223 world program, like this: `libtool --mode=link gcc -Wall
224 helloworld.c -o helloworld
225 $(pkg-config --cflags --libs gstreamer-1.0)`.
227 You can run this example application with `./helloworld
228 file.ogg`. Substitute `file.ogg` with your favourite Ogg/Vorbis file.
232 This concludes our first example. As you see, setting up a pipeline is
233 very low-level but powerful. You will see later in this manual how you
234 can create a more powerful media player with even less effort using
235 higher-level interfaces. We will discuss all that in [Higher-level
236 interfaces for GStreamer applications](manual/advanced/index.md). We will
237 first, however, go more in-depth into more advanced GStreamer internals.
239 It should be clear from the example that we can very easily replace the
240 “filesrc” element with some other element that reads data from a
241 network, or some other data source element that is better integrated
242 with your desktop environment. Also, you can use other decoders and
243 parsers/demuxers to support other media types. You can use another audio
244 sink if you're not running Linux, but Mac OS X, Windows or FreeBSD, or
245 you can instead use a filesink to write audio files to disk instead of
246 playing them back. By using an audio card source, you can even do audio
247 capture instead of playback. All this shows the reusability of GStreamer
248 elements, which is its greatest advantage.