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 id="GST_DEBUG">
  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 <formalpara id="GST_DEBUG_NO_COLOR">
 169   <title><envar>GST_DEBUG_NO_COLOR</envar></title>
 170
 171   <para>
 172 Set this environment variable to any value ("1" typically) to switch off
 173 colouring in GST_DEBUG output. This has the same effect as specifying the
 174 <option>--gst-debug-no-color</option> command line option to well-behaved
 175 GStreamer applications (ie. those that pass command-line options correctly to
 176 GStreamer).
 177 This is particularly useful to reduce the size of debug output and also allows
 178 for the output to be compressed much better than with colours turned on.
 179   </para>
 180
 181 </formalpara>
 182
 183 <formalpara id="GST_DEBUG_DUMP_DOT_DIR">
 184   <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title>
 185
 186   <para>
 187 Set this environment variable to a path to turn on all
 188 #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls
 189 and have the dot files in that location.
 190   </para>
 191
 192 </formalpara>
 193
 194 <formalpara id="GST_REGISTRY_FORK">
 195   <title><envar>GST_REGISTRY_FORK</envar></title>
 196
 197   <para>
 198 Set this environment variable to "no" to prevent GStreamer from forking on
 199 startup in order to update the plugin registry. This is useful for debugging
 200 purposes, but should not be used under normal circumstances, since it means
 201 that plugins may be loaded into memory even if they are not needed by the
 202 application.
 203   </para>
 204
 205 </formalpara>
 206
 207 </refsect2>
 208
 209 </refsect1>
 210
 211 </refentry>