docs/manual/appendix-programs.xml

   1 <chapter id="chapter-programs">
   2   <title>Programs</title>
   3   <para>
   4   </para>
   5
   6   <sect1 id="section-programs-gst-register">
   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 id="section-programs-gst-launch">
  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 to play a mp3 audio file 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         <xref linkend="section-programs-gst-launch-more-examples"/> lists more gst-launch commandlines.
  37
  38     </para>
  39     <para>
  40       You can also use the parser in you own
  41       code. <application>GStreamer</application> provides a function
  42       gst_parse_launch () that you can use to construct a pipeline.
  43       The following program lets you create an MP3 pipeline using the
  44       gst_parse_launch () function:
  45     </para>
  46     <programlisting>
  47 #include &lt;gst/gst.h&gt;
  48
  49 int
  50 main (int argc, char *argv[])
  51 {
  52   GstElement *pipeline;
  53   GstElement *filesrc;
  54   GError *error = NULL;
  55
  56   gst_init (&amp;argc, &amp;argv);
  57
  58   if (argc != 2) {
  59     g_print ("usage: %s &lt;filename&gt;\n", argv[0]);
  60     return -1;
  61   }
  62
  63   pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &amp;error);
  64   if (!pipeline) {
  65     g_print ("Parse error: %s\n", error->message);
  66     exit (1);
  67   }
  68
  69   filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
  70   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
  71
  72   gst_element_set_state (pipeline, GST_STATE_PLAYING);
  73
  74   while (gst_bin_iterate (GST_BIN (pipeline)));
  75
  76   gst_element_set_state (pipeline, GST_STATE_NULL);
  77
  78   return 0;
  79 }
  80     </programlisting>
  81     <para>
  82       Note how we can retrieve the filesrc element from the constructed bin using the
  83       element name.
  84     </para>
  85     <sect2>
  86       <title>Grammar Reference</title>
  87       <para>
  88         The <command>gst-launch</command> syntax is processed by a flex/bison parser. This section
  89         is intended to provide a full specification of the grammar; any deviations from this
  90         specification is considered a bug.
  91       </para>
  92       <sect3>
  93         <title>Elements</title>
  94         <screen>
  95           ... mad ...
  96         </screen>
  97         <para>
  98           A bare identifier (a string beginning with a letter and containing
  99           only letters, numbers, dashes, underscores, percent signs, or colons)
 100           will create an element from a given element factory. In this example,
 101           an instance of the "mad" MP3 decoding plugin will be created.
 102         </para>
 103       </sect3>
 104       <sect3>
 105         <title>Links</title>
 106         <screen>
 107           ... !sink ...
 108         </screen>
 109         <para>
 110           An exclamation point, optionally having a qualified pad name (an the name of the pad,
 111           optionally preceded by the name of the element) on both sides, will link two pads. If
 112           the source pad is not specified, a source pad from the immediately preceding element
 113           will be automatically chosen. If the sink pad is not specified, a sink pad from the next
 114           element to be constructed will be chosen. An attempt will be made to find compatible
 115           pads. Pad names may be preceded by an element name, as in
 116           <computeroutput>my_element_name.sink_pad</computeroutput>.
 117         </para>
 118       </sect3>
 119       <sect3>
 120         <title>Properties</title>
 121         <screen>
 122           ... location="http://gstreamer.net" ...
 123         </screen>
 124         <para>
 125           The name of a property, optionally qualified with an element name, and a value,
 126           separated by an equals sign, will set a property on an element. If the element is not
 127           specified, the previous element is assumed. Strings can optionally be enclosed in
 128           quotation marks. Characters in strings may be escaped with the backtick
 129           (<literal>\</literal>). If the right-hand side is all digits, it is considered to be an
 130           integer. If it is all digits and a decimal point, it is a double. If it is "true",
 131           "false", "TRUE", or "FALSE" it is considered to be boolean. Otherwise, it is parsed as a
 132           string. The type of the property is determined later on in the parsing, and the value is
 133           converted to the target type. This conversion is not guaranteed to work, it relies on
 134           the g_value_convert routines. No error message will be displayed on an invalid
 135           conversion, due to limitations in the value convert API.
 136         </para>
 137                 <para>
 138           The list of properties an element supports can be found out using
 139           <userinput>gst-inspect elemnt-name</userinput>.
 140                 </para>
 141       </sect3>
 142       <sect3>
 143         <title>Bins, Threads, and Pipelines</title>
 144         <screen>
 145           ( ... )
 146         </screen>
 147         <para>
 148           A pipeline description between parentheses is placed into a bin. The open paren may be
 149           preceded by a type name, as in <computeroutput>jackbin.( ... )</computeroutput> to make
 150           a bin of a specified type. Square brackets '[ ]' make pipelines, and curly braces '{ }' make
 151           threads. The default toplevel bin type is a pipeline, although putting the whole
 152           description within parentheses or braces can override this default.
 153         </para>
 154       </sect3>
 155     </sect2>
 156     <sect2 id="section-programs-gst-launch-more-examples">
 157       <title>More Examples</title>
 158       <para>
 159         This chapter collects some more complex pipelines. The examples are split into several lines,
 160         so make sure to include the trailing backslashes.
 161                 When modifying the pipelines and seeking for the right element to insert, a grep of the gst-inspect
 162                 output often gives a starting point:
 163                 <screen>
 164 gst-inspect | grep "avi"
 165                 </screen>
 166                 Another way is to do:
 167                 <screen>
 168 gst-launch filesrc location=video.avi ! decodebin name=d ! xvimagesink d. ! { queue ! alsasink } -v
 169                 </screen>
 170                 and look on the output, which plugins it chooses.
 171       </para>
 172       <para>
 173         Play a remote mp3 audio file:
 174         <screen>
 175 gst-launch gnomevfssrc location=http://www.server.org/hello.mp3 ! mad ! alsasink
 176         </screen>
 177       </para>
 178       <para>
 179         Play a local mp3 audio file with visualisation:
 180         <screen>
 181 gst-launch filesrc location=Hello.mp3 ! mad ! tee name=t ! \
 182   { queue ! osssink } \
 183   { t. ! queue ! synaesthesia ! ffmpegcolorspace ! xvimagesink }
 184         </screen>
 185       </para>
 186      <para>
 187         Play a local ogg audio file:
 188         <screen>
 189 gst-launch filesrc location=file.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioscale ! alsasink
 190         </screen>
 191       </para>
 192       <para>
 193         Play a local ogg video file:
 194         <screen>
 195 gst-launch filesrc location=file.ogg ! oggdemux name=demux \
 196   { demux. ! queue ! theoradec ! ffmpegcolorspace ! videoscale ! xvimagesink } \
 197   { demux. ! queue ! vorbisdec ! audioconvert ! audioscale ! alsasink }
 198         </screen>
 199       </para>
 200       <para>
 201         Play a local avi video file:
 202        <screen>
 203 gst-launch filesrc location=video.avi ! mpegdemux name=demux \
 204   demux.audio_00! { queue ! ac3parse ! a52dec ! osssink } \
 205   demux.video_00! { queue ! mpeg2dec ! xvideosink }
 206         </screen>
 207       </para>
 208       <para>
 209         Transcoding an audio file from one format into another:
 210        <screen>
 211 gst-launch filesrc location=file.ogg ! oggdemux ! vorbisdec ! audioconvert ! flacenc ! filesink location=file.flac
 212        </screen>
 213        <screen>
 214 gst-launch filesrc location=file.mp3 ! id3demus ! mad ! audioconvert ! rawvorbisenc ! oggmux ! filesink location=file.ogg
 215         </screen>
 216       </para>
 217       <para>
 218         Transcoding an dvd video into a ogg video:
 219        <screen>
 220 gst-launch-0.8 oggmux name=mux ! filesink location=/tmp/file.ogg \
 221   { dvdreadsrc location=/dev/cdrom ! dvddemux name=demux.audio_00 ! \
 222     { queue ! a52dec ! audioconvert ! rawvorbisenc ! queue ! mux. } \
 223     { demux.video_00 ! queue ! mpeg2dec ! ffcolorspace ! videoscale ! video/x-raw-yuv,width=384,height=288 ! tee name=t ! \
 224       { queue ! theoraenc ! queue ! mux. } \
 225     } \
 226   } \
 227   { t. ! queue ! ffcolorspace ! ximagesink }
 228         </screen>
 229       </para>
 230
 231         </sect2>
 232   </sect1>
 233
 234   <sect1 id="section-programs-gst-inspect">
 235     <title><command>gst-inspect</command></title>
 236     <para>
 237       This is a tool to query a plugin or an element about its properties.
 238     </para>
 239     <para>
 240       To query the information about the element mad, you would specify:
 241     </para>
 242
 243     <screen>
 244 gst-inspect mad
 245     </screen>
 246
 247     <para>
 248       Below is the output of a query for the osssink element:
 249     </para>
 250
 251     <screen>
 252 Factory Details:
 253   Long name:    Audio Sink (OSS)
 254   Class:        Sink/Audio
 255   Description:  Output to a sound card via OSS
 256   Version:      0.3.3.1
 257   Author(s):    Erik Walthinsen &lt;omega@cse.ogi.edu&gt;, Wim Taymans &lt;wim.taymans@chello.be&gt;
 258   Copyright:    (C) 1999
 259
 260 GObject
 261  +----GstObject
 262        +----GstElement
 263              +----GstOssSink
 264
 265 Pad Templates:
 266   SINK template: 'sink'
 267     Availability: Always
 268     Capabilities:
 269       'osssink_sink':
 270         MIME type: 'audio/raw':
 271         format: String: int
 272         endianness: Integer: 1234
 273         width: List:
 274           Integer: 8
 275           Integer: 16
 276         depth: List:
 277           Integer: 8
 278           Integer: 16
 279         channels: Integer range: 1 - 2
 280         law: Integer: 0
 281         signed: List:
 282           Boolean: FALSE
 283           Boolean: TRUE
 284         rate: Integer range: 1000 - 48000
 285
 286
 287 Element Flags:
 288   GST_ELEMENT_THREADSUGGESTED
 289
 290 Element Implementation:
 291   No loopfunc(), must be chain-based or not configured yet
 292   Has change_state() function: gst_osssink_change_state
 293   Has custom save_thyself() function: gst_element_save_thyself
 294   Has custom restore_thyself() function: gst_element_restore_thyself
 295
 296 Clocking Interaction:
 297   element requires a clock
 298   element provides a clock: GstOssClock
 299
 300 Pads:
 301   SINK: 'sink'
 302     Implementation:
 303       Has chainfunc(): 0x40056fc0
 304     Pad Template: 'sink'
 305
 306 Element Arguments:
 307   name                                    : String (Default "element")
 308   device                                  : String (Default "/dev/dsp")
 309   mute                                    : Boolean (Default false)
 310   format                                  : Integer (Default 16)
 311   channels                                : Enum "GstAudiosinkChannels" (default 1)
 312     (0):        Silence
 313     (1):        Mono
 314     (2):        Stereo
 315   frequency                               : Integer (Default 11025)
 316   fragment                                : Integer (Default 6)
 317   buffer-size                             : Integer (Default 4096)
 318
 319 Element Signals:
 320   "handoff" :    void user_function (GstOssSink* object,
 321                                 gpointer user_data);
 322     </screen>
 323
 324     <para>
 325       To query the information about a plugin, you would do:
 326     </para>
 327
 328     <screen>
 329 gst-inspect gstelements
 330     </screen>
 331   </sect1>
 332
 333 </chapter>