docs/gst/running.xml

   1 <refentry id="gst-running" revision="08 Oct 2005">
   2 <refmeta>
   3 <refentrytitle>Running GStreamer Applications</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GStreamer Core</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Running GStreamer Applications</refname>
  10 <refpurpose>
  11 How to run and debug your GStreamer application
  12 </refpurpose>
  13 </refnamediv>
  14
  15 <refsect1>
  16 <title>Running and debugging GStreamer Applications</title>
  17
  18 <refsect2>
  19 <title>Environment variables</title>
  20
  21 <para>
  22 GStreamer inspects a few of environment variables in addition to standard
  23 variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
  24 </para>
  25
  26 <formalpara id="GST_PLUGIN_SYSTEM_PATH">
  27   <title><envar>GST_PLUGIN_SYSTEM_PATH</envar></title>
  28
  29   <para>
  30
  31 This environment variable can be set to a colon-separated list of paths.
  32 If this variable is not set, GStreamer will fill in this list for you
  33 with
  34 <itemizedlist>
  35   <listitem>
  36     <para>
  37 plug-ins in the user's home directory.  These are stored in a directory called
  38 <filename>plugins</filename> inside the
  39 <filename>.gstreamer-&GST_MAJORMINOR;</filename> directory in the user's
  40 home directory.
  41     </para>
  42   </listitem>
  43   <listitem>
  44     <para>
  45 plug-ins installed system-wide.  On this system, they are stored in
  46 <filename>&GST_PLUGINS_DIR;</filename>.
  47     </para>
  48
  49 </listitem>
  50 </itemizedlist>
  51    </para>
  52
  53     <para>
  54 GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
  55 be loaded after the plug-ins in the GST_PLUGIN_PATH variable below.
  56
  57 The paths are scanned in the given order.  This allows a user to override
  58 system-installed plug-ins with his own versions.
  59    </para>
  60
  61     <para>
  62 Setting this variable to an empty string will cause GStreamer not to scan any
  63 system paths at all for plug-ins.  This can be useful if you're running
  64 uninstalled (for development purposes) or while running testsuites.
  65    </para>
  66
  67 </formalpara>
  68
  69 <formalpara id="GST_PLUGIN_PATH">
  70   <title><envar>GST_PLUGIN_PATH</envar></title>
  71
  72   <para>
  73 This environment variable can be set to a colon-separated list of paths.
  74 GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
  75 be loaded in addition to, and before, the plug-ins in the system paths.
  76   </para>
  77
  78 </formalpara>
  79
  80 <formalpara>
  81   <title><envar>GST_DEBUG</envar></title>
  82
  83   <para>
  84 If GStreamer has been configured with <option>--enable-gst-debug=yes</option>,
  85 this variable can be set to a list of debug options, which cause GStreamer
  86 to print out different types of debugging information to stderr.
  87   </para>
  88   <para>
  89 The variable takes a comma-separated list of "category_name:level" pairs
  90 to set specific levels for the individual categories.
  91 The level value ranges from 0 (nothing) to 5 (LOG).
  92     <variablelist>
  93
  94       <varlistentry>
  95         <term>1 - <option>ERROR</option></term>
  96         <listitem>
  97 <para>
  98 Logs all fatal errors.  These are errors that do not allow the core or elements
  99 to perform the requested action.  The application can still recover if
 100 programmed to handle the conditions that triggered the error.
 101 </para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term>2 - <option>WARNING</option></term>
 107         <listitem>
 108 <para>
 109 Logs all warnings.  Typically these are non-fatal, but user-visible problems
 110 are expected to happen.
 111 </para>
 112         </listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term>3 - <option>INFO</option></term>
 117         <listitem>
 118 <para>
 119 Logs all informational messages.  These are typically used for events in
 120 the system that only happen once, or are important and rare enough to be
 121 logged at this level.
 122 </para>
 123         </listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term>4 - <option>DEBUG</option></term>
 128         <listitem>
 129 <para>
 130 Logs all debug messages.  These are general debug messages for events
 131 that happen only a limited number of times during an object's lifetime;
 132 these include setup, teardown, change of parameters, ...
 133 </para>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term>5 - <option>LOG</option></term>
 139         <listitem>
 140 <para>
 141 Logs all log messages.  These are messages for events
 142 that happen repeatedly during an object's lifetime;
 143 these include streaming and steady-state conditions.
 144 </para>
 145         </listitem>
 146       </varlistentry>
 147     </variablelist>
 148
 149  The category_name can contain "<option>*"</option> as a wildcard.
 150   </para>
 151
 152   <para>
 153 For example, setting <envar>GST_DEBUG</envar> to
 154 <option>GST_AUTOPLUG:5,GST_ELEMENT_*:3</option>, will cause the
 155 <option>GST_AUTOPLUG</option> category to be logged at full
 156 <option>LOG</option> level, while all categories starting with
 157 <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
 158   </para>
 159
 160   <para>
 161 To get all possible debug output, set
 162 <envar>GST_DEBUG</envar>
 163 to <option>*:5</option>
 164   </para>
 165
 166 </formalpara>
 167
 168 </refsect2>
 169
 170 </refsect1>
 171
 172 </refentry>