gstreamer/docs/manual/basics-helloworld.xml
Andy Wingo d2c3b2087d conversion to docbook-xml. i don't have to ask that this be testing, because not ionly is it perfect, but i'm sure yo...
Original commit message from CVS:
conversion to docbook-xml. i don't have to ask that this be testing, because
not ionly is it perfect, but i'm sure you folks will learn that on your own :-)
2001-12-15 23:13:04 +00:00

307 lines
9.9 KiB
XML

<chapter id="cha-hello">
<title>Your first application</title>
<para>
This chapter describes the most rudimentary aspects of a <application>GStreamer</application> application,
including initializing the libraries, creating elements, packing them into
a pipeline and playing, pause and stop the pipeline.
</para>
<sect1>
<title>Hello world</title>
<para>
We will create a simple first application. In fact it will be a complete
MP3 player, using standard <application>GStreamer</application> components. The player will read from
a file that is given as the first argument of the program.
</para>
<programlisting>
#include &lt;gst/gst.h&gt;
int
main (int argc, char *argv[])
{
GstElement *pipeline, *disksrc, *parse, *decoder, *audiosink;
gst_init(&amp;argc, &amp;argv);
if (argc != 2) {
g_print ("usage: &percnt;s &lt;filename&gt;\n", argv[0]);
exit (-1);
}
/* create a new pipeline to hold the elements */
pipeline = gst_pipeline_new ("pipeline");
/* create a disk reader */
disksrc = gst_elementfactory_make ("disksrc", "disk_source");
g_object_set (G_OBJECT (disksrc), "location", argv[1], NULL);
/* now it's time to get the parser */
parse = gst_elementfactory_make ("mp3parse", "parse");
decoder = gst_elementfactory_make ("mpg123", "decoder");
/* and an audio sink */
audiosink = gst_elementfactory_make ("osssink", "play_audio");
/* add objects to the main pipeline */
gst_bin_add (GST_BIN (pipeline), disksrc);
gst_bin_add (GST_BIN (pipeline), parse);
gst_bin_add (GST_BIN (pipeline), decoder);
gst_bin_add (GST_BIN (pipeline), audiosink);
/* connect src to sink */
gst_pad_connect (gst_element_get_pad (disksrc, "src"),
gst_element_get_pad (parse, "sink"));
gst_pad_connect (gst_element_get_pad (parse, "src"),
gst_element_get_pad (decoder, "sink"));
gst_pad_connect (gst_element_get_pad (decoder, "src"),
gst_element_get_pad (audiosink, "sink"));
/* start playing */
gst_element_set_state (pipeline, GST_STATE_PLAYING);
while (gst_bin_iterate (GST_BIN (pipeline)));
/* stop the pipeline */
gst_element_set_state (pipeline, GST_STATE_NULL);
/* we don't need a reference to these objects anymore */
gst_object_unref (GST_OBJECT (audiosink));
gst_object_unref (GST_OBJECT (parse));
gst_object_unref (GST_OBJECT (decoder));
gst_object_unref (GST_OBJECT (disksrc));
gst_object_unref (GST_OBJECT (pipeline));
exit (0);
}
</programlisting>
<para>
Let's go through this example step by step.
</para>
<para>
The first thing you have to do is to include the standard <application>GStreamer</application> headers and
initialize the framework.
</para>
<programlisting>
#include &lt;gst/gst.h&gt;
...
int
main (int argc, char *argv[])
{
...
gst_init(&amp;argc, &amp;argv);
...
</programlisting>
<para>
We are going to create 4 elements and one pipeline. Since all objects are
in fact elements, we can define them as:
</para>
<programlisting>
...
GstElement *pipeline, *disksrc, *parse, *decoder, *audiosink;
...
</programlisting>
<para>
Next, we are going to create an empty pipeline. As you have seen in the basic
introduction, this pipeline will hold and manage all the elements we are
going to stuff into it.
</para>
<programlisting>
/* create a new pipeline to hold the elements */
pipeline = gst_pipeline_new ("pipeline");
</programlisting>
<para>
We use the standard constructor for a pipeline: gst_pipeline_new ("name").
</para>
<para>
We then create a disk source element. The disk source element is able to
read from a file. We use the standard GObject property mechanism to set
a property of the element: the file to read from.
</para>
<programlisting>
/* create a disk reader */
disksrc = gst_elementfactory_make ("disksrc", "disk_source");
g_object_set (G_OBJECT (disksrc), "location", argv[1], NULL);
</programlisting>
<note>
<para>
You can check if the disksrc != NULL to verify the creation of the
disk source element.
</para>
</note>
<para>
We now create the MP3 decoder element. <application>GStreamer</application> requires you
to put a parser in front of the decoder. This parser will
cut the raw data from the disk source into MP3 frames
suitable for the decoder. In the advanced concepts chapter we will
see how this can be avoided.
</para>
<programlisting>
/* now it's time to get the parser */
parse = gst_elementfactory_make ("mp3parse", "parse");
decoder = gst_elementfactory_make ("mpg123", "decoder");
</programlisting>
<para>
gst_elementfactory_make() takes two arguments: a string that will
identify the element you need and a second argument: how you want
to name the element. The name of the element is something you can
choose yourself and might be used to retrieve the element from a
bin/pipeline.
</para>
<para>
Finally we create our audio sink element. This element will be able
to playback the audio using OSS.
</para>
<programlisting>
/* and an audio sink */
audiosink = gst_elementfactory_make ("audiosink", "play_audio");
</programlisting>
<para>
We then add the elements to the pipeline.
</para>
<programlisting>
/* add objects to the main pipeline */
gst_bin_add (GST_BIN (pipeline), disksrc);
gst_bin_add (GST_BIN (pipeline), parse);
gst_bin_add (GST_BIN (pipeline), decoder);
gst_bin_add (GST_BIN (pipeline), audiosink);
</programlisting>
<para>
We connect the different pads of the elements together like this:
</para>
<programlisting>
/* connect src to sink */
gst_pad_connect (gst_element_get_pad (disksrc, "src"),
gst_element_get_pad (parse, "sink"));
gst_pad_connect (gst_element_get_pad (parse, "src"),
gst_element_get_pad (decoder, "sink"));
gst_pad_connect (gst_element_get_pad (decoder, "src"),
gst_element_get_pad (audiosink, "sink"));
</programlisting>
<para>
We now have a created a complete pipeline. We can visualise the
pipeline as follows:
</para>
<figure float="1" id="sec-hello-img">
<title>The Hello world pipeline</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/hello-world.&magic;" format="&magic;" />
</imageobject>
</mediaobject>
</figure>
<para>
Everything is now set up to start the streaming. We use the following
statements to change the state of the pipeline:
</para>
<programlisting>
/* start playing */
gst_element_set_state (pipeline, GST_STATE_PLAYING);
</programlisting>
<note>
<para>
<application>GStreamer</application> will take care of the READY and PAUSED state for y
ou when going from NULL to PLAYING.
</para>
</note>
<para>
Since we do not use threads, nothing will happen yet. We manually have to
call gst_bin_iterate() to execute one iteration of the pipeline.
</para>
<programlisting>
while (gst_bin_iterate (GST_BIN (pipeline)));
</programlisting>
<para>
The gst_bin_iterate() function will return TRUE as long as something interesting
happended inside the pipeline. When the end-of-file has been reached the _iterate
function will return FALSE and we can end the loop.
</para>
<programlisting>
/* stop the pipeline */
gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (GST_OBJECT (audiosink));
gst_object_unref (GST_OBJECT (decoder));
gst_object_unref (GST_OBJECT (disksrc));
gst_object_unref (GST_OBJECT (pipeline));
exit (0);
</programlisting>
<note>
<para>
don't forget to set the state of the pipeline to NULL. This will free
all of the resources held by the elements.
</para>
</note>
</sect1>
<sect1>
<title>compiling helloworld.c</title>
<para>
To compile the helloworld example, use:
</para>
<programlisting>
gcc -Wall `gstreamer-config --cflags --libs` helloworld.c \
-o helloworld
</programlisting>
<para>
This uses the program gstreamer-config, which comes with <application>GStreamer</application>. This program "knows"
what compiler switches are needed to compile programs that use <application>GStreamer</application>.
gstreamer-config --cflags will output a list of include
directories for the compiler to look in, and gstreamer-config --libs will output the
list of libraries for the compiler to link with and the directories to find them
in.
</para>
<para>
You can run the example with (substitute helloworld.mp3 with you favorite MP3 file):
</para>
<programlisting>
./helloworld helloworld.mp3
</programlisting>
</sect1>
<sect1>
<title>conclusion</title>
<para>
This concludes our first example. As you see, setting up a pipeline
is very lowlevel but powerfull. You will later in this manual how
you can create a custom MP3 element with a more high level API.
</para>
<para>
It should be clear from the example that we can very easily replace the
disksrc element with an httpsrc, giving you instant network streaming.
An element could be build to handle icecast connections, for example.
</para>
<para>
We can also choose to use another type of sink instead of the audiosink.
We could use a disksink to write the raw samples to a file, for example.
It should also be clear that inserting filters, like a stereo effect,
into the pipeline is not that hard to do. The most important thing is
that you can reuse allready existing elements.
</para>
</sect1>
</chapter>