1 <chapter id="cha-hello">
2 <title>Your first application</title>
4 This chapter describes the most rudimentary aspects of a
5 <application>GStreamer</application> application, including initializing
6 the libraries, creating elements, packing them into a pipeline and playing,
7 pausing and stopping the pipeline.
11 <title>Hello world</title>
13 We will create a simple first application, a complete MP3 player, using
14 standard <application>GStreamer</application> components. The player
15 will read from a file that is given as the first argument to the program.
19 /* example-begin helloworld.c */
20 #include <gst/gst.h>
23 main (int argc, char *argv[])
25 GstElement *pipeline, *filesrc, *decoder, *audiosink;
27 gst_init(&argc, &argv);
30 g_print ("usage: %s <mp3 filename>\n", argv[0]);
34 /* create a new pipeline to hold the elements */
35 pipeline = gst_pipeline_new ("pipeline");
37 /* create a disk reader */
38 filesrc = gst_element_factory_make ("filesrc", "disk_source");
39 g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
41 /* now it's time to get the decoder */
42 decoder = gst_element_factory_make ("mad", "decoder");
44 /* and an audio sink */
45 audiosink = gst_element_factory_make ("osssink", "play_audio");
47 /* add objects to the main pipeline */
48 gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL);
50 /* link src to sink */
51 gst_element_link_many (filesrc, decoder, audiosink, NULL);
54 gst_element_set_state (pipeline, GST_STATE_PLAYING);
56 while (gst_bin_iterate (GST_BIN (pipeline)));
58 /* stop the pipeline */
59 gst_element_set_state (pipeline, GST_STATE_NULL);
61 /* we don't need a reference to these objects anymore */
62 gst_object_unref (GST_OBJECT (pipeline));
63 /* unreffing the pipeline unrefs the contained elements as well */
67 /* example-end helloworld.c */
71 Let's go through this example step by step.
75 The first thing you have to do is to include the standard
76 <application>GStreamer</application> headers and
77 initialize the framework.
81 #include <gst/gst.h>
86 main (int argc, char *argv[])
89 gst_init(&argc, &argv);
95 We are going to create three elements and one pipeline. Since all
96 elements share the same base type, <classname>GstElement</classname>,
97 we can define them as:
101 GstElement *pipeline, *filesrc, *decoder, *audiosink;
106 Next, we are going to create an empty pipeline. As you have seen in
107 the basic introduction, this pipeline will hold and manage all the
108 elements we are going to pack into it.
111 /* create a new pipeline to hold the elements */
112 pipeline = gst_pipeline_new ("pipeline");
115 We use the standard constructor for a pipeline: gst_pipeline_new ().
119 We then create a disk source element. The disk source element is able to
120 read from a file. We use the standard GObject property mechanism to set
121 a property of the element: the file to read from.
124 /* create a disk reader */
125 filesrc = gst_element_factory_make ("filesrc", "disk_source");
126 g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
130 You can check if the filesrc != NULL to verify the creation of the
136 We now create the MP3 decoder element. This assumes that the 'mad' plugin
137 is installed on the system where this application is executed.
140 /* now it's time to get the decoder */
141 decoder = gst_element_factory_make ("mad", "decoder");
144 gst_element_factory_make() takes two arguments: a string that will
145 identify the element you need and a second argument: how you want
146 to name the element. The name of the element is something you can
147 choose yourself and might be used to retrieve the element from a
152 Finally we create our audio sink element. This element will be able
153 to play back the audio using OSS.
156 /* and an audio sink */
157 audiosink = gst_element_factory_make ("audiosink", "play_audio");
161 We then add the elements to the pipeline.
164 /* add objects to the main pipeline */
165 gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL);
169 We link the different pads of the elements together like this:
172 /* link src to sink */
173 gst_element_link_many (filesrc, decoder, audiosink, NULL);
177 We now have a created a complete pipeline. We can visualise the
180 <figure float="1" id="sec-hello-img">
181 <title>The Hello world pipeline</title>
184 <imagedata fileref="images/hello-world.ℑ" format="&IMAGE;" />
191 Everything is now set up to start the streaming. We use the following
192 statements to change the state of the pipeline:
196 gst_element_set_state (pipeline, GST_STATE_PLAYING);
201 <application>GStreamer</application> will take care of the READY and PAUSED state for
202 you when going from NULL to PLAYING.
207 Since we do not use threads, nothing will happen yet. We have to
208 call gst_bin_iterate() to execute one iteration of the pipeline.
211 while (gst_bin_iterate (GST_BIN (pipeline)));
214 The gst_bin_iterate() function will return TRUE as long as something
215 interesting happened inside the pipeline. When the end-of-file has been
216 reached the _iterate function will return FALSE and we can end the loop.
219 /* stop the pipeline */
220 gst_element_set_state (pipeline, GST_STATE_NULL);
222 gst_object_unref (GST_OBJECT (pipeline));
228 Don't forget to set the state of the pipeline to NULL. This will free
229 all of the resources held by the elements.
236 <title>Compiling helloworld.c</title>
238 To compile the helloworld example, use:
241 gcc -Wall `pkg-config gstreamer-0.7 --cflags --libs` helloworld.c \
245 We use pkg-config to get the compiler flags needed to compile
246 this application. Make sure to have your PKG_CONFIG_PATH environment
247 variable set to the correct location if you are building this
248 application against the uninstalled location.
251 You can run the example with
252 (substitute helloworld.mp3 with you favorite MP3 file):
255 ./helloworld helloworld.mp3
260 <title>Conclusion</title>
262 This concludes our first example. As you see, setting up a pipeline
263 is very low-level but powerful. You will see later in this manual how
264 you can create a custom MP3 element with a higher-level API.
267 It should be clear from the example that we can very easily replace the
268 filesrc element with an httpsrc element, giving you instant network
269 streaming. An element could be built to handle icecast connections,
273 We can also choose to use another type of sink instead of the audiosink.
274 We could use a disksink to write the raw samples to a file, for example.
275 It should also be clear that inserting filters, like a stereo effect,
276 into the pipeline is not that hard to do. The most important thing is
277 that you can reuse already existing elements.