docs/manual/appendix-checklist.xml

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