docs/manual/appendix-programs.xml

<chapter id="cha-programs">
  <title>Programs</title>
  <para> 
  </para>

  <sect1>
    <title><command>gst-register</command></title>
    <para> 
      <command>gst-register</command> is used to rebuild the database of plugins.
      It is used after a new plugin has been added to the system. The plugin database
      can be found, by default, in <filename>/etc/gstreamer/reg.xml</filename>.
    </para>
  </sect1>

  <sect1>
    <title><command>gst-launch</command></title>
    <para> 
      This is a tool that will construct pipelines based on a command-line
      syntax. FIXME: need a more extensive grammar reference
    </para> 
    <para> 
      A simple commandline looks like:

    <screen>
gst-launch filesrc location=hello.mp3 ! mad ! osssink
    </screen>

      A more complex pipeline looks like:

    <screen>
gst-launch filesrc location=redpill.vob ! mpegdemux name=demux \
 demux.audio_00! { ac3parse ! a52dec ! osssink } \
 demux.video_00! { mpeg2dec ! xvideosink }
    </screen>

    </para>
    <para>
      You can also use the the parser in you own code. <application>GStreamer</application>
      provides a function gst_parse_launch () that you can use to construt a pipeline. 
      The following programs lets you create an mp3 pipeline using the gst_parse_launch () 
      function:
    </para>
    <programlisting>
#include &lt;gst/gst.h&gt;

int
main (int argc, char *argv[])
{
  GstElement *pipeline;
  GstElement *filesrc;
  GError *error = NULL;

  gst_init (&amp;argc, &amp;argv);

  if (argc != 2) {
    g_print ("usage: &percnt;s &lt;filename&gt;\n", argv[0]);
    return -1;
  }

  pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &amp;error);
  if (!pipeline) {
    g_print ("Parse error: &percnt;s\n", error->message);
    exit (1);
  }
  
  filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
  g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);

  gst_element_set_state (pipeline, GST_STATE_PLAYING);

  while (gst_bin_iterate (GST_BIN (pipeline)));

  gst_element_set_state (pipeline, GST_STATE_NULL);

  return 0;
}
    </programlisting>
    <para>
      Note how we can retrieve the filesrc element from the constructed bin using the
      element name.
    </para>
  </sect1>

  <sect1>
    <title><command>gst-inspect</command></title>
    <para> 
      This is a tool to query a plugin or an element about its properties.
    </para> 
    <para> 
      To query the information about the element mad, you would specify:
    </para> 

    <screen>
gst-inspect mad
    </screen>

    <para> 
      Below is the output of a query for the osssink element:
    </para> 

    <screen>
Factory Details:
  Long name:	Audio Sink (OSS)
  Class:	Sink/Audio
  Description:	Output to a sound card via OSS
  Version:	0.3.3.1
  Author(s):	Erik Walthinsen &lt;omega@cse.ogi.edu&gt;, Wim Taymans &lt;wim.taymans@chello.be&gt;
  Copyright:	(C) 1999

GObject
 +----GstObject
       +----GstElement
             +----GstOssSink

Pad Templates:
  SINK template: 'sink'
    Availability: Always
    Capabilities:
      'osssink_sink':
        MIME type: 'audio/raw':
        format: String: int
        endianness: Integer: 1234
        width: List:
          Integer: 8
          Integer: 16
        depth: List:
          Integer: 8
          Integer: 16
        channels: Integer range: 1 - 2
        law: Integer: 0
        signed: List:
          Boolean: FALSE
          Boolean: TRUE
        rate: Integer range: 1000 - 48000


Element Flags:
  GST_ELEMENT_THREADSUGGESTED

Element Implementation:
  No loopfunc(), must be chain-based or not configured yet
  Has change_state() function: gst_osssink_change_state
  Has custom save_thyself() function: gst_element_save_thyself
  Has custom restore_thyself() function: gst_element_restore_thyself

Clocking Interaction:
  element requires a clock
  element provides a clock: GstOssClock

Pads:
  SINK: 'sink'
    Implementation:
      Has chainfunc(): 0x40056fc0
    Pad Template: 'sink'

Element Arguments:
  name                                    : String (Default "element")
  device                                  : String (Default "/dev/dsp")
  mute                                    : Boolean (Default false)
  format                                  : Integer (Default 16)
  channels                                : Enum "GstAudiosinkChannels" (default 1)
    (0): 	Silence
    (1): 	Mono
    (2): 	Stereo
  frequency                               : Integer (Default 11025)
  fragment                                : Integer (Default 6)
  buffer-size                             : Integer (Default 4096)

Element Signals:
  "handoff" :	 void user_function (GstOssSink* object, 
    				gpointer user_data);
    </screen>

    <para> 
      To query the information about a plugin, you would do:
    </para> 

    <screen>
gst-inspect gstelements
    </screen>
  </sect1>
  <sect1>
    <title><command>gst-play</command></title>
    <para> 
      A sample media player.
    </para>
  </sect1>

</chapter>