markdown/manual/appendix/programs.md

   1 ---
   2 title: Programs
   3 ...
   4
   5 # Programs
   6
   7 ## `gst-launch`
   8
   9 This is a tool that will construct pipelines based on a command-line
  10 syntax.
  11
  12 A simple commandline looks like:
  13
  14 ```
  15 gst-launch filesrc location=hello.mp3 ! mad ! audioresample ! osssink
  16
  17 ```
  18
  19 A more complex pipeline looks like:
  20
  21 ```
  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 ! videoconvert ! xvimagesink
  25
  26 ```
  27
  28 You can also use the parser in you own code. GStreamer provides a
  29 function gst\_parse\_launch () that you can use to construct a pipeline.
  30 The following program lets you create an MP3 pipeline using the
  31 gst\_parse\_launch () function:
  32
  33 ``` c
  34 #include <gst/gst.h>
  35
  36 int
  37 main (int argc, char *argv[])
  38 {
  39   GstElement *pipeline;
  40   GstElement *filesrc;
  41   GstMessage *msg;
  42   GstBus *bus;
  43   GError *error = NULL;
  44
  45   gst_init (&argc, &argv);
  46
  47   if (argc != 2) {
  48     g_print ("usage: %s <filename>\n", argv[0]);
  49     return -1;
  50   }
  51
  52   pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &error);
  53   if (!pipeline) {
  54     g_print ("Parse error: %s\n", error->message);
  55     exit (1);
  56   }
  57
  58   filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
  59   g_object_set (filesrc, "location", argv[1], NULL);
  60   g_object_unref (filesrc);
  61
  62   gst_element_set_state (pipeline, GST_STATE_PLAYING);
  63
  64   bus = gst_element_get_bus (pipeline);
  65
  66   /* wait until we either get an EOS or an ERROR message. Note that in a real
  67    * program you would probably not use gst_bus_poll(), but rather set up an
  68    * async signal watch on the bus and run a main loop and connect to the
  69    * bus's signals to catch certain messages or all messages */
  70   msg = gst_bus_poll (bus, GST_MESSAGE_EOS | GST_MESSAGE_ERROR, -1);
  71
  72   switch (GST_MESSAGE_TYPE (msg)) {
  73     case GST_MESSAGE_EOS: {
  74       g_print ("EOS\n");
  75       break;
  76     }
  77     case GST_MESSAGE_ERROR: {
  78       GError *err = NULL; /* error to show to users                 */
  79       gchar *dbg = NULL;  /* additional debug string for developers */
  80
  81       gst_message_parse_error (msg, &err, &dbg);
  82       if (err) {
  83         g_printerr ("ERROR: %s\n", err->message);
  84         g_error_free (err);
  85       }
  86       if (dbg) {
  87         g_printerr ("[Debug details: %s]\n", dbg);
  88         g_free (dbg);
  89       }
  90     }
  91     default:
  92       g_printerr ("Unexpected message of type %d", GST_MESSAGE_TYPE (msg));
  93       break;
  94   }
  95   gst_message_unref (msg);
  96
  97   gst_element_set_state (pipeline, GST_STATE_NULL);
  98   gst_object_unref (pipeline);
  99   gst_object_unref (bus);
 100
 101   return 0;
 102 }
 103
 104 ```
 105
 106 Note how we can retrieve the filesrc element from the constructed bin
 107 using the element name.
 108
 109 ### Grammar Reference
 110
 111 The `gst-launch` syntax is processed by a flex/bison parser. This
 112 section is intended to provide a full specification of the grammar; any
 113 deviations from this specification is considered a bug.
 114
 115 #### Elements
 116
 117 ```
 118           ... mad ...
 119
 120 ```
 121
 122 A bare identifier (a string beginning with a letter and containing only
 123 letters, numbers, dashes, underscores, percent signs, or colons) will
 124 create an element from a given element factory. In this example, an
 125 instance of the "mad" MP3 decoding plugin will be created.
 126
 127 #### Links
 128
 129 ```
 130           ... !sink ...
 131
 132 ```
 133
 134 An exclamation point, optionally having a qualified pad name (an the
 135 name of the pad, optionally preceded by the name of the element) on both
 136 sides, will link two pads. If the source pad is not specified, a source
 137 pad from the immediately preceding element will be automatically chosen.
 138 If the sink pad is not specified, a sink pad from the next element to be
 139 constructed will be chosen. An attempt will be made to find compatible
 140 pads. Pad names may be preceded by an element name, as in
 141 `my_element_name.sink_pad`.
 142
 143 #### Properties
 144
 145 ```
 146           ... location="http://gstreamer.net" ...
 147
 148 ```
 149
 150 The name of a property, optionally qualified with an element name, and a
 151 value, separated by an equals sign, will set a property on an element.
 152 If the element is not specified, the previous element is assumed.
 153 Strings can optionally be enclosed in quotation marks. Characters in
 154 strings may be escaped with the backtick (`\`). If the right-hand side
 155 is all digits, it is considered to be an integer. If it is all digits
 156 and a decimal point, it is a double. If it is "true", "false", "TRUE",
 157 or "FALSE" it is considered to be boolean. Otherwise, it is parsed as a
 158 string. The type of the property is determined later on in the parsing,
 159 and the value is converted to the target type. This conversion is not
 160 guaranteed to work, it relies on the g\_value\_convert routines. No
 161 error message will be displayed on an invalid conversion, due to
 162 limitations in the value convert API.
 163
 164 #### Bins, Threads, and Pipelines
 165
 166 ```
 167           ( ... )
 168
 169 ```
 170
 171 A pipeline description between parentheses is placed into a bin. The
 172 open paren may be preceded by a type name, as in `jackbin.( ... )` to
 173 make a bin of a specified type. Square brackets make pipelines, and
 174 curly braces make threads. The default toplevel bin type is a pipeline,
 175 although putting the whole description within parentheses or braces can
 176 override this default.
 177
 178 ## `gst-inspect`
 179
 180 This is a tool to query a plugin or an element about its properties.
 181
 182 To query the information about the element mad, you would specify:
 183
 184 ```
 185 gst-inspect mad
 186
 187 ```
 188
 189 Below is the output of a query for the osssink element:
 190
 191 ```
 192
 193 Factory Details:
 194   Rank:         secondary (128)
 195   Long-name:            Audio Sink (OSS)
 196   Klass:                Sink/Audio
 197   Description:          Output to a sound card via OSS
 198   Author:               Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be>
 199
 200 Plugin Details:
 201   Name:                 ossaudio
 202   Description:          OSS (Open Sound System) support for GStreamer
 203   Filename:             /home/wim/gst/head/gst-plugins-good/sys/oss/.libs/libgstossaudio.so
 204   Version:              1.0.0.1
 205   License:              LGPL
 206   Source module:        gst-plugins-good
 207   Source release date:  2012-09-25 12:52 (UTC)
 208   Binary package:       GStreamer Good Plug-ins git
 209   Origin URL:           Unknown package origin
 210
 211 GObject
 212  +----GInitiallyUnowned
 213        +----GstObject
 214              +----GstElement
 215                    +----GstBaseSink
 216                          +----GstAudioBaseSink
 217                                +----GstAudioSink
 218                                      +----GstOssSink
 219
 220 Pad Templates:
 221   SINK template: 'sink'
 222     Availability: Always
 223     Capabilities:
 224       audio/x-raw
 225                  format: { S16LE, U16LE, S8, U8 }
 226                  layout: interleaved
 227                    rate: [ 1, 2147483647 ]
 228                channels: 1
 229       audio/x-raw
 230                  format: { S16LE, U16LE, S8, U8 }
 231                  layout: interleaved
 232                    rate: [ 1, 2147483647 ]
 233                channels: 2
 234            channel-mask: 0x0000000000000003
 235
 236
 237 Element Flags:
 238   no flags set
 239
 240 Element Implementation:
 241   Has change_state() function: gst_audio_base_sink_change_state
 242
 243 Clocking Interaction:
 244   element is supposed to provide a clock but returned NULL
 245
 246 Element has no indexing capabilities.
 247 Element has no URI handling capabilities.
 248
 249 Pads:
 250   SINK: 'sink'
 251     Implementation:
 252       Has chainfunc(): gst_base_sink_chain
 253       Has custom eventfunc(): gst_base_sink_event
 254       Has custom queryfunc(): gst_base_sink_sink_query
 255       Has custom iterintlinkfunc(): gst_pad_iterate_internal_links_default
 256     Pad Template: 'sink'
 257
 258 Element Properties:
 259   name                : The name of the object
 260                         flags: readable, writable
 261                         String. Default: "osssink0"
 262   parent              : The parent of the object
 263                         flags: readable, writable
 264                         Object of type "GstObject"
 265   sync                : Sync on the clock
 266                         flags: readable, writable
 267                         Boolean. Default: true
 268   max-lateness        : Maximum number of nanoseconds that a buffer can be late before it is dropped (-1 unlimited)
 269                         flags: readable, writable
 270                         Integer64. Range: -1 - 9223372036854775807 Default: -1
 271   qos                 : Generate Quality-of-Service events upstream
 272                         flags: readable, writable
 273                         Boolean. Default: false
 274   async               : Go asynchronously to PAUSED
 275                         flags: readable, writable
 276                         Boolean. Default: true
 277   ts-offset           : Timestamp offset in nanoseconds
 278                         flags: readable, writable
 279                         Integer64. Range: -9223372036854775808 - 9223372036854775807 Default: 0
 280   enable-last-sample  : Enable the last-sample property
 281                         flags: readable, writable
 282                         Boolean. Default: false
 283   last-sample         : The last sample received in the sink
 284                         flags: readable
 285                         Boxed pointer of type "GstSample"
 286   blocksize           : Size in bytes to pull per buffer (0 = default)
 287                         flags: readable, writable
 288                         Unsigned Integer. Range: 0 - 4294967295 Default: 4096
 289   render-delay        : Additional render delay of the sink in nanoseconds
 290                         flags: readable, writable
 291                         Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
 292   throttle-time       : The time to keep between rendered buffers
 293                         flags: readable, writable
 294                         Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
 295   buffer-time         : Size of audio buffer in microseconds, this is the minimum latency that the sink reports
 296                         flags: readable, writable
 297                         Integer64. Range: 1 - 9223372036854775807 Default: 200000
 298   latency-time        : The minimum amount of data to write in each iteration in microseconds
 299                         flags: readable, writable
 300                         Integer64. Range: 1 - 9223372036854775807 Default: 10000
 301   provide-clock       : Provide a clock to be used as the global pipeline clock
 302                         flags: readable, writable
 303                         Boolean. Default: true
 304   slave-method        : Algorithm to use to match the rate of the masterclock
 305                         flags: readable, writable
 306                         Enum "GstAudioBaseSinkSlaveMethod" Default: 1, "skew"
 307                            (0): resample         - GST_AUDIO_BASE_SINK_SLAVE_RESAMPLE
 308                            (1): skew             - GST_AUDIO_BASE_SINK_SLAVE_SKEW
 309                            (2): none             - GST_AUDIO_BASE_SINK_SLAVE_NONE
 310   can-activate-pull   : Allow pull-based scheduling
 311                         flags: readable, writable
 312                         Boolean. Default: false
 313   alignment-threshold : Timestamp alignment threshold in nanoseconds
 314                         flags: readable, writable
 315                         Unsigned Integer64. Range: 1 - 18446744073709551614 Default: 40000000
 316   drift-tolerance     : Tolerance for clock drift in microseconds
 317                         flags: readable, writable
 318                         Integer64. Range: 1 - 9223372036854775807 Default: 40000
 319   discont-wait        : Window of time in nanoseconds to wait before creating a discontinuity
 320                         flags: readable, writable
 321                         Unsigned Integer64. Range: 0 - 18446744073709551614 Default: 1000000000
 322   device              : OSS device (usually /dev/dspN)
 323                         flags: readable, writable
 324                         String. Default: "/dev/dsp"
 325
 326
 327 ```
 328
 329 To query the information about a plugin, you would do:
 330
 331 ```
 332 gst-inspect gstelements
 333
 334 ```