docs/manual/programs.xml

   1 <chapter id="cha-programs">
   2   <title>Programs</title>
   3   <para>
   4   </para>
   5
   6   <sect1>
   7     <title><command>gst-register</command></title>
   8     <para>
   9       <command>gst-register</command> is used to rebuild the database of plugins.
  10       It is used after a new plugin has been added to the system. The plugin database
  11       can be found, by default, in <filename>/etc/gstreamer/reg.xml</filename>.
  12     </para>
  13   </sect1>
  14
  15   <sect1>
  16     <title><command>gst-launch</command></title>
  17     <para>
  18       This is a tool that will construct pipelines based on a command-line
  19       syntax.
  20     </para>
  21     <para>
  22       A simple commandline looks like:
  23
  24     <screen>
  25 gst-launch filesrc location=hello.mp3 ! mad ! osssink
  26     </screen>
  27
  28       A more complex pipeline looks like:
  29
  30     <screen>
  31 gst-launch filesrc location=redpill.vob ! mpegdemux name=demux \
  32  demux.audio_00! { ac3parse ! a52dec ! osssink } \
  33  demux.video_00! { mpeg2dec ! xvideosink }
  34     </screen>
  35
  36     </para>
  37     <para>
  38       You can also use the parser in you own
  39       code. <application>GStreamer</application> provides a function
  40       gst_parse_launch () that you can use to construct a pipeline.
  41       The following program lets you create an MP3 pipeline using the
  42       gst_parse_launch () function:
  43     </para>
  44     <programlisting>
  45 #include &lt;gst/gst.h&gt;
  46
  47 int
  48 main (int argc, char *argv[])
  49 {
  50   GstElement *pipeline;
  51   GstElement *filesrc;
  52   GError *error = NULL;
  53
  54   gst_init (&amp;argc, &amp;argv);
  55
  56   if (argc != 2) {
  57     g_print ("usage: %s &lt;filename&gt;\n", argv[0]);
  58     return -1;
  59   }
  60
  61   pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &amp;error);
  62   if (!pipeline) {
  63     g_print ("Parse error: %s\n", error->message);
  64     exit (1);
  65   }
  66
  67   filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
  68   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
  69
  70   gst_element_set_state (pipeline, GST_STATE_PLAYING);
  71
  72   while (gst_bin_iterate (GST_BIN (pipeline)));
  73
  74   gst_element_set_state (pipeline, GST_STATE_NULL);
  75
  76   return 0;
  77 }
  78     </programlisting>
  79     <para>
  80       Note how we can retrieve the filesrc element from the constructed bin using the
  81       element name.
  82     </para>
  83     <sect2>
  84       <title>Grammar Reference</title>
  85       <para>
  86         The <command>gst-launch</command> syntax is processed by a flex/bison parser. This section
  87         is intended to provide a full specification of the grammar; any deviations from this
  88         specification is considered a bug.
  89       </para>
  90       <sect3>
  91         <title>Elements</title>
  92         <screen>
  93           ... mad ...
  94         </screen>
  95         <para>
  96           A bare identifier (a string beginning with a letter and containing
  97           only letters, numbers, dashes, underscores, percent signs, or colons)
  98           will create an element from a given element factory. In this example,
  99           an instance of the "mad" MP3 decoding plugin will be created.
 100         </para>
 101       </sect3>
 102       <sect3>
 103         <title>Links</title>
 104         <screen>
 105           ... !sink ...
 106         </screen>
 107         <para>
 108           An exclamation point, optionally having a qualified pad name (an the name of the pad,
 109           optionally preceded by the name of the element) on both sides, will link two pads. If
 110           the source pad is not specified, a source pad from the immediately preceding element
 111           will be automatically chosen. If the sink pad is not specified, a sink pad from the next
 112           element to be constructed will be chosen. An attempt will be made to find compatible
 113           pads. Pad names may be preceded by an element name, as in
 114           <computeroutput>my_element_name.sink_pad</computeroutput>.
 115         </para>
 116       </sect3>
 117       <sect3>
 118         <title>Properties</title>
 119         <screen>
 120           ... location="http://gstreamer.net" ...
 121         </screen>
 122         <para>
 123           The name of a property, optionally qualified with an element name, and a value,
 124           separated by an equals sign, will set a property on an element. If the element is not
 125           specified, the previous element is assumed. Strings can optionally be enclosed in
 126           quotation marks. Characters in strings may be escaped with the backtick
 127           (<literal>\</literal>). If the right-hand side is all digits, it is considered to be an
 128           integer. If it is all digits and a decimal point, it is a double. If it is "true",
 129           "false", "TRUE", or "FALSE" it is considered to be boolean. Otherwise, it is parsed as a
 130           string. The type of the property is determined later on in the parsing, and the value is
 131           converted to the target type. This conversion is not guaranteed to work, it relies on
 132           the g_value_convert routines. No error message will be displayed on an invalid
 133           conversion, due to limitations in the value convert API.
 134         </para>
 135       </sect3>
 136       <sect3>
 137         <title>Bins, Threads, and Pipelines</title>
 138         <screen>
 139           ( ... )
 140         </screen>
 141         <para>
 142           A pipeline description between parentheses is placed into a bin. The open paren may be
 143           preceded by a type name, as in <computeroutput>jackbin.( ... )</computeroutput> to make
 144           a bin of a specified type. Square brackets make pipelines, and curly braces make
 145           threads. The default toplevel bin type is a pipeline, although putting the whole
 146           description within parentheses or braces can override this default.
 147         </para>
 148       </sect3>
 149     </sect2>
 150   </sect1>
 151
 152   <sect1>
 153     <title><command>gst-inspect</command></title>
 154     <para>
 155       This is a tool to query a plugin or an element about its properties.
 156     </para>
 157     <para>
 158       To query the information about the element mad, you would specify:
 159     </para>
 160
 161     <screen>
 162 gst-inspect mad
 163     </screen>
 164
 165     <para>
 166       Below is the output of a query for the osssink element:
 167     </para>
 168
 169     <screen>
 170 Factory Details:
 171   Long name:    Audio Sink (OSS)
 172   Class:        Sink/Audio
 173   Description:  Output to a sound card via OSS
 174   Version:      0.3.3.1
 175   Author(s):    Erik Walthinsen &lt;omega@cse.ogi.edu&gt;, Wim Taymans &lt;wim.taymans@chello.be&gt;
 176   Copyright:    (C) 1999
 177
 178 GObject
 179  +----GstObject
 180        +----GstElement
 181              +----GstOssSink
 182
 183 Pad Templates:
 184   SINK template: 'sink'
 185     Availability: Always
 186     Capabilities:
 187       'osssink_sink':
 188         MIME type: 'audio/raw':
 189         format: String: int
 190         endianness: Integer: 1234
 191         width: List:
 192           Integer: 8
 193           Integer: 16
 194         depth: List:
 195           Integer: 8
 196           Integer: 16
 197         channels: Integer range: 1 - 2
 198         law: Integer: 0
 199         signed: List:
 200           Boolean: FALSE
 201           Boolean: TRUE
 202         rate: Integer range: 1000 - 48000
 203
 204
 205 Element Flags:
 206   GST_ELEMENT_THREADSUGGESTED
 207
 208 Element Implementation:
 209   No loopfunc(), must be chain-based or not configured yet
 210   Has change_state() function: gst_osssink_change_state
 211   Has custom save_thyself() function: gst_element_save_thyself
 212   Has custom restore_thyself() function: gst_element_restore_thyself
 213
 214 Clocking Interaction:
 215   element requires a clock
 216   element provides a clock: GstOssClock
 217
 218 Pads:
 219   SINK: 'sink'
 220     Implementation:
 221       Has chainfunc(): 0x40056fc0
 222     Pad Template: 'sink'
 223
 224 Element Arguments:
 225   name                                    : String (Default "element")
 226   device                                  : String (Default "/dev/dsp")
 227   mute                                    : Boolean (Default false)
 228   format                                  : Integer (Default 16)
 229   channels                                : Enum "GstAudiosinkChannels" (default 1)
 230     (0):        Silence
 231     (1):        Mono
 232     (2):        Stereo
 233   frequency                               : Integer (Default 11025)
 234   fragment                                : Integer (Default 6)
 235   buffer-size                             : Integer (Default 4096)
 236
 237 Element Signals:
 238   "handoff" :    void user_function (GstOssSink* object,
 239                                 gpointer user_data);
 240     </screen>
 241
 242     <para>
 243       To query the information about a plugin, you would do:
 244     </para>
 245
 246     <screen>
 247 gst-inspect gstelements
 248     </screen>
 249   </sect1>
 250   <sect1>
 251     <title><command>gst-play</command></title>
 252     <para>
 253       A sample media player.
 254     </para>
 255   </sect1>
 256
 257 </chapter>