gstreamer/docs/manual/basics-helloworld.xml
Stefan Kost 14da85cf94 docs/manual/basics-helloworld.xml: Add a cast in example to fix compile warning
Original commit message from CVS:
* docs/manual/basics-helloworld.xml:
Add a cast in example to fix compile warning
2006-10-18 19:43:46 +00:00

240 lines
8.7 KiB
XML

<chapter id="chapter-helloworld">
<title>Your first application</title>
<para>
This chapter will summarize everything you've learned in the previous
chapters. It describes all aspects of a simple &GStreamer; application,
including initializing libraries, creating elements, packing elements
together in a pipeline and playing this pipeline. By doing all this,
you will be able to build a simple Ogg/Vorbis audio player.
</para>
<sect1 id="section-helloworld">
<title>Hello world</title>
<para>
We're going to create a simple first application, a simple Ogg/Vorbis
command-line audio player. For this, we will use only standard
&GStreamer; components. The player will read a file specified on
the command-line. Let's get started!
</para>
<para>
We've learned, in <xref linkend="chapter-init"/>, that the first thing
to do in your application is to initialize &GStreamer; by calling
<function>gst_init ()</function>. Also, make sure that the application
includes <filename>gst/gst.h</filename> so all function names and
objects are properly defined. Use <function>#include
&lt;gst/gst.h&gt;</function> to do that.
</para>
<para>
Next, you'll want to create the different elements using
<function>gst_element_factory_make ()</function>. For an Ogg/Vorbis
audio player, we'll need a source element that reads files from a
disk. &GStreamer; includes this element under the name
<quote>filesrc</quote>. Next, we'll need something to parse the
file and decoder it into raw audio. &GStreamer; has two elements
for this: the first parses Ogg streams into elementary streams (video,
audio) and is called <quote>oggdemux</quote>. The second is a Vorbis
audio decoder, it's conveniently called <quote>vorbisdec</quote>.
Since <quote>oggdemux</quote> creates dynamic pads for each elementary
stream, you'll need to set a <quote>pad-added</quote> event handler
on the <quote>oggdemux</quote> element, like you've learned in
<xref linkend="section-pads-dynamic"/>, to link the Ogg parser and
the Vorbis decoder elements together. At last, we'll also need an
audio output element, we will use <quote>alsasink</quote>, which
outputs sound to an ALSA audio device.
</para>
<para>
The last thing left to do is to add all elements into a container
element, a <classname>GstPipeline</classname>, and iterate this
pipeline until we've played the whole song. We've previously
learned how to add elements to a container bin in <xref
linkend="chapter-bins"/>, and we've learned about element states
in <xref linkend="section-elements-states"/>. We will also attach
a message handler to the pipeline bus so we can retrieve errors
and detect the end-of-stream.
</para>
<para>
Let's now add all the code together to get our very first audio
player:
</para>
<programlisting>
<!-- example-begin helloworld.c -->
#include &lt;gst/gst.h&gt;
/*
* Global objects are usually a bad thing. For the purpose of this
* example, we will use them, however.
*/
GstElement *pipeline, *source, *parser, *decoder, *conv, *sink;
static gboolean
bus_call (GstBus *bus,
GstMessage *msg,
gpointer data)
{
GMainLoop *loop = (GMainLoop *) data;
switch (GST_MESSAGE_TYPE (msg)) {
case GST_MESSAGE_EOS:
g_print ("End-of-stream\n");
g_main_loop_quit (loop);
break;
case GST_MESSAGE_ERROR: {
gchar *debug;
GError *err;
gst_message_parse_error (msg, &amp;err, &amp;debug);
g_free (debug);
g_print ("Error: %s\n", err->message);
g_error_free (err);
g_main_loop_quit (loop);
break;
}
default:
break;
}
return TRUE;
}
static void
new_pad (GstElement *element,
GstPad *pad,
gpointer data)
{
GstPad *sinkpad;
/* We can now link this pad with the audio decoder */
g_print ("Dynamic pad created, linking parser/decoder\n");
sinkpad = gst_element_get_pad (decoder, "sink");
gst_pad_link (pad, sinkpad);
gst_object_unref (sinkpad);
}
int
main (int argc,
char *argv[])
{
GMainLoop *loop;
GstBus *bus;
/* initialize GStreamer */
gst_init (&amp;argc, &amp;argv);
loop = g_main_loop_new (NULL, FALSE);
/* check input arguments */
if (argc != 2) {
g_print ("Usage: %s &lt;Ogg/Vorbis filename&gt;\n", argv[0]);
return -1;
}
/* create elements */
pipeline = gst_pipeline_new ("audio-player");
source = gst_element_factory_make ("filesrc", "file-source");
parser = gst_element_factory_make ("oggdemux", "ogg-parser");
decoder = gst_element_factory_make ("vorbisdec", "vorbis-decoder");
conv = gst_element_factory_make ("audioconvert", "converter");
sink = gst_element_factory_make ("alsasink", "alsa-output");
if (!pipeline || !source || !parser || !decoder || !conv || !sink) {
g_print ("One element could not be created\n");
return -1;
}
/* set filename property on the file source. Also add a message
* handler. */
g_object_set (G_OBJECT (source), "location", argv[1], NULL);
bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
gst_bus_add_watch (bus, bus_call, loop);
gst_object_unref (bus);
/* put all elements in a bin */
gst_bin_add_many (GST_BIN (pipeline),
source, parser, decoder, conv, sink, NULL);
/* link together - note that we cannot link the parser and
* decoder yet, becuse the parser uses dynamic pads. For that,
* we set a pad-added signal handler. */
gst_element_link (source, parser);
gst_element_link_many (decoder, conv, sink, NULL);
g_signal_connect (parser, "pad-added", G_CALLBACK (new_pad), NULL);
/* Now set to playing and iterate. */
g_print ("Setting to PLAYING\n");
gst_element_set_state (pipeline, GST_STATE_PLAYING);
g_print ("Running\n");
g_main_loop_run (loop);
/* clean up nicely */
g_print ("Returned, stopping playback\n");
gst_element_set_state (pipeline, GST_STATE_NULL);
g_print ("Deleting pipeline\n");
gst_object_unref (GST_OBJECT (pipeline));
return 0;
}
<!-- example-end helloworld.c -->
</programlisting>
<!-- FIXME: this image needs updating -->
<para>
We now have created a complete pipeline. We can visualise the
pipeline as follows:
</para>
<figure float="1" id="section-hello-img">
<title>The "hello world" pipeline</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/hello-world.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
</sect1>
<sect1 id="section-helloworld-compilerun">
<title>Compiling and Running helloworld.c</title>
<para>
To compile the helloworld example, use: <command>gcc -Wall
$(pkg-config --cflags --libs gstreamer-&GST_MAJORMINOR;)
helloworld.c -o helloworld</command>. &GStreamer; makes use of
<command>pkg-config</command> to get compiler and linker flags
needed to compile this application. If you're running a
non-standard installation, make sure the
<classname>PKG_CONFIG_PATH</classname> environment variable is
set to the correct location (<filename>$libdir/pkgconfig</filename>).
application against the uninstalled location.
</para>
<para>
You can run this example application with <command>./helloworld
file.ogg</command>. Substitute <filename>file.ogg</filename>
with your favourite Ogg/Vorbis file.
</para>
</sect1>
<sect1 id="section-hello-world-conclusion">
<title>Conclusion</title>
<para>
This concludes our first example. As you see, setting up a pipeline
is very low-level but powerful. You will see later in this manual how
you can create a more powerful media player with even less effort
using higher-level interfaces. We will discuss all that in <xref
linkend="part-highlevel"/>. We will first, however, go more in-depth
into more advanced &GStreamer; internals.
</para>
<para>
It should be clear from the example that we can very easily replace
the <quote>filesrc</quote> element with some other element that
reads data from a network, or some other data source element that
is better integrated with your desktop environment. Also, you can
use other decoders and parsers to support other media types. You
can use another audio sink if you're not running Linux, but Mac OS X,
Windows or FreeBSD, or you can instead use a filesink to write audio
files to disk instead of playing them back. By using an audio card
source, you can even do audio capture instead of playback. All this
shows the reusability of &GStreamer; elements, which is its greatest
advantage.
</para>
</sect1>
</chapter>