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