manual-checklist-element.md

   1 ---
   2 title: Things to check when writing an application
   3 ...
   4
   5 # Things to check when writing an application
   6
   7 This chapter contains a fairly random selection of things that can be
   8 useful to keep in mind when writing GStreamer-based applications. It's
   9 up to you how much you're going to use the information provided here. We
  10 will shortly discuss how to debug pipeline problems using GStreamer
  11 applications. Also, we will touch upon how to acquire knowledge about
  12 plugins and elements and how to test simple pipelines before building
  13 applications around them.
  14
  15 ## Good programming habits
  16
  17   - Always add a `GstBus` handler to your pipeline. Always report errors
  18     in your application, and try to do something with warnings and
  19     information messages, too.
  20
  21   - Always check return values of GStreamer functions. Especially, check
  22     return values of `gst_element_link ()` and `gst_element_set_state
  23     ()`.
  24
  25   - Dereference return values of all functions returning a non-base
  26     type, such as `gst_element_get_pad ()`. Also, always free non-const
  27     string returns, such as `gst_object_get_name ()`.
  28
  29   - Always use your pipeline object to keep track of the current state
  30     of your pipeline. Don't keep private variables in your application.
  31     Also, don't update your user interface if a user presses the “play”
  32     button. Instead, listen for the “state-changed” message on the
  33     `GstBus` and only update the user interface whenever this message is
  34     received.
  35
  36   - Report all bugs that you find in GStreamer bugzilla at
  37     [http://bugzilla.gnome.org/](http://bugzilla.gnome.org).
  38
  39 ## Debugging
  40
  41 Applications can make use of the extensive GStreamer debugging system to
  42 debug pipeline problems. Elements will write output to this system to
  43 log what they're doing. It's not used for error reporting, but it is
  44 very useful for tracking what an element is doing exactly, which can
  45 come in handy when debugging application issues (such as failing seeks,
  46 out-of-sync media, etc.).
  47
  48 Most GStreamer-based applications accept the commandline option
  49 `--gst-debug=LIST` and related family members. The list consists of a
  50 comma-separated list of category/level pairs, which can set the
  51 debugging level for a specific debugging category. For example,
  52 `--gst-debug=oggdemux:5` would turn on debugging for the Ogg demuxer
  53 element. You can use wildcards as well. A debugging level of 0 will turn
  54 off all debugging, and a level of 9 will turn on all debugging.
  55 Intermediate values only turn on some debugging (based on message
  56 severity; 2, for example, will only display errors and warnings). Here's
  57 a list of all available options:
  58
  59   - `--gst-debug-help` will print available debug categories and exit.
  60
  61   - `--gst-debug-level=LEVEL` will set the default debug level (which
  62     can range from 0 (no output) to 9 (everything)).
  63
  64   - `--gst-debug=LIST` takes a comma-separated list of
  65     category\_name:level pairs to set specific levels for the individual
  66     categories. Example: `GST_AUTOPLUG:5,avidemux:3`. Alternatively, you
  67     can also set the `GST_DEBUG` environment variable, which has the
  68     same effect.
  69
  70   - `--gst-debug-no-color` will disable color debugging. You can also
  71     set the GST\_DEBUG\_NO\_COLOR environment variable to 1 if you want
  72     to disable colored debug output permanently. Note that if you are
  73     disabling color purely to avoid messing up your pager output, try
  74     using `less -R`.
  75
  76   - `--gst-debug-color-mode=MODE` will change debug log coloring mode.
  77     MODE can be one of the following: `on`, `off`, `auto`, `disable`,
  78     `unix`. You can also set the GST\_DEBUG\_COLOR\_MODE environment
  79     variable if you want to change colored debug output permanently.
  80     Note that if you are disabling color purely to avoid messing up your
  81     pager output, try using `less -R`.
  82
  83   - `--gst-debug-disable` disables debugging altogether.
  84
  85   - `--gst-plugin-spew` enables printout of errors while loading
  86     GStreamer plugins.
  87
  88 ## Conversion plugins
  89
  90 GStreamer contains a bunch of conversion plugins that most applications
  91 will find useful. Specifically, those are videoscalers (videoscale),
  92 colorspace convertors (videoconvert), audio format convertors and
  93 channel resamplers (audioconvert) and audio samplerate convertors
  94 (audioresample). Those convertors don't do anything when not required,
  95 they will act in passthrough mode. They will activate when the hardware
  96 doesn't support a specific request, though. All applications are
  97 recommended to use those elements.
  98
  99 ## Utility applications provided with GStreamer
 100
 101 GStreamer comes with a default set of command-line utilities that can
 102 help in application development. We will discuss only `gst-launch` and
 103 `gst-inspect` here.
 104
 105 ### `gst-launch`
 106
 107 `gst-launch` is a simple script-like commandline application that can be
 108 used to test pipelines. For example, the command `gst-launch
 109 audiotestsrc ! audioconvert !
 110 audio/x-raw,channels=2 ! alsasink` will run a pipeline which generates a
 111 sine-wave audio stream and plays it to your ALSA audio card.
 112 `gst-launch` also allows the use of threads (will be used automatically
 113 as required or as queue elements are inserted in the pipeline) and bins
 114 (using brackets, so “(” and “)”). You can use dots to imply padnames on
 115 elements, or even omit the padname to automatically select a pad. Using
 116 all this, the pipeline `gst-launch filesrc location=file.ogg ! oggdemux
 117 name=d
 118 d. ! queue ! theoradec ! videoconvert ! xvimagesink
 119 d. ! queue ! vorbisdec ! audioconvert ! audioresample ! alsasink
 120 ` will play an Ogg file containing a Theora video-stream and a Vorbis
 121 audio-stream. You can also use autopluggers such as decodebin on the
 122 commandline. See the manual page of `gst-launch` for more information.
 123
 124 ### `gst-inspect`
 125
 126 `gst-inspect` can be used to inspect all properties, signals, dynamic
 127 parameters and the object hierarchy of an element. This can be very
 128 useful to see which `GObject` properties or which signals (and using
 129 what arguments) an element supports. Run `gst-inspect fakesrc` to get an
 130 idea of what it does. See the manual page of `gst-inspect` for more
 131 information.
 132