<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Your first application</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="GStreamer Application Development Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Building an application"
HREF="part-build-app.html"><LINK
REL="PREVIOUS"
TITLE="Building an application"
HREF="part-build-app.html"><LINK
REL="NEXT"
TITLE="Compiling helloworld.c"
HREF="section-hello-world-compile.html"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="application"
>GStreamer</SPAN
> Application Development Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="part-build-app.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="section-hello-world-compile.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="chapter-hello-world"
></A
>Chapter 19. Your first application</H1
><P
>
This chapter describes the most rudimentary aspects of a
<SPAN
CLASS="application"
>GStreamer</SPAN
> application, including initializing
the libraries, creating elements, packing them into a pipeline and playing,
pausing and stopping the pipeline.
</P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-hello-world"
>19.1. Hello world</A
></H1
><P
> We will create a simple first application, a complete MP3 player, using
standard <SPAN
CLASS="application"
>GStreamer</SPAN
> components. The player
will read from a file that is given as the first argument to the program.
</P
><PRE
CLASS="programlisting"
> /* example-begin helloworld.c */
#include <gst/gst.h>
int
main (int argc, char *argv[])
{
GstElement *pipeline, *filesrc, *decoder, *audiosink;
gst_init(&argc, &argv);
if (argc != 2) {
g_print ("usage: %s <mp3 filename>\n", argv[0]);
exit (-1);
}
/* create a new pipeline to hold the elements */
pipeline = gst_pipeline_new ("pipeline");
/* create a disk reader */
filesrc = gst_element_factory_make ("filesrc", "disk_source");
g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
/* now it's time to get the decoder */
decoder = gst_element_factory_make ("mad", "decoder");
/* and an audio sink */
audiosink = gst_element_factory_make ("osssink", "play_audio");
/* add objects to the main pipeline */
gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL);
/* link src to sink */
gst_element_link_many (filesrc, decoder, audiosink, NULL);
/* 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 (pipeline));
/* unreffing the pipeline unrefs the contained elements as well */
exit (0);
}
/* example-end helloworld.c */
</PRE
><P
> Let's go through this example step by step.
</P
><P
> The first thing you have to do is to include the standard
<SPAN
CLASS="application"
>GStreamer</SPAN
> headers and
initialize the framework.
</P
><PRE
CLASS="programlisting"
>
#include <gst/gst.h>
...
int
main (int argc, char *argv[])
{
...
gst_init(&argc, &argv);
...
</PRE
><P
> We are going to create three elements and one pipeline. Since all
elements share the same base type, <CODE
CLASS="classname"
>GstElement</CODE
>,
we can define them as:
</P
><PRE
CLASS="programlisting"
> ...
GstElement *pipeline, *filesrc, *decoder, *audiosink;
...
</PRE
><P
> 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 pack into it.
</P
><PRE
CLASS="programlisting"
> /* create a new pipeline to hold the elements */
pipeline = gst_pipeline_new ("pipeline");
</PRE
><P
> We use the standard constructor for a pipeline: gst_pipeline_new ().
</P
><P
> 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.
</P
><PRE
CLASS="programlisting"
> /* create a disk reader */
filesrc = gst_element_factory_make ("filesrc", "disk_source");
g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
</PRE
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> You can check if the filesrc != NULL to verify the creation of the
disk source element.
</P
></TD
></TR
></TABLE
></DIV
><P
> We now create the MP3 decoder element. This assumes that the 'mad' plugin
is installed on the system where this application is executed.
</P
><PRE
CLASS="programlisting"
> /* now it's time to get the decoder */
decoder = gst_element_factory_make ("mad", "decoder");
</PRE
><P
> gst_element_factory_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.
</P
><P
> Finally we create our audio sink element. This element will be able
to play back the audio using OSS.
</P
><PRE
CLASS="programlisting"
> /* and an audio sink */
audiosink = gst_element_factory_make ("audiosink", "play_audio");
</PRE
><P
> We then add the elements to the pipeline.
</P
><PRE
CLASS="programlisting"
> /* add objects to the main pipeline */
gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL);
</PRE
><P
> We link the different pads of the elements together like this:
</P
><PRE
CLASS="programlisting"
> /* link src to sink */
gst_element_link_many (filesrc, decoder, audiosink, NULL);
</PRE
><P
> We now have a created a complete pipeline. We can visualise the
pipeline as follows:
</P
><DIV
CLASS="figure"
><A
NAME="section-hello-img"
></A
><P
><B
>Figure 19-1. The "hello world" pipeline</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="images/hello-world.png"></P
></DIV
></DIV
><P
> Everything is now set up to start streaming. We use the following
statements to change the state of the pipeline:
</P
><PRE
CLASS="programlisting"
> /* start playing */
gst_element_set_state (pipeline, GST_STATE_PLAYING);
</PRE
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> <SPAN
CLASS="application"
>GStreamer</SPAN
> will take care of the READY and PAUSED state for
you when going from NULL to PLAYING.
</P
></TD
></TR
></TABLE
></DIV
><P
> Since we do not use threads, nothing will happen yet. We have to
call gst_bin_iterate() to execute one iteration of the pipeline.
</P
><PRE
CLASS="programlisting"
> while (gst_bin_iterate (GST_BIN (pipeline)));
</PRE
><P
> The gst_bin_iterate() function will return TRUE as long as something
interesting happened inside the pipeline. When the end-of-file has been
reached the _iterate function will return FALSE and we can end the loop.
</P
><PRE
CLASS="programlisting"
> /* stop the pipeline */
gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (GST_OBJECT (pipeline));
exit (0);
</PRE
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> Don't forget to set the state of the pipeline to NULL. This will free
all of the resources held by the elements.
</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="part-build-app.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="section-hello-world-compile.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Building an application</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-build-app.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Compiling helloworld.c</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
