2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY % version-entities SYSTEM "version.entities">
6 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
8 <refentry id="gst-running" revision="08 Oct 2005">
10 <refentrytitle>Running GStreamer Applications</refentrytitle>
11 <manvolnum>3</manvolnum>
12 <refmiscinfo>GStreamer Core</refmiscinfo>
16 <refname>Running GStreamer Applications</refname>
18 How to run and debug your GStreamer application
23 <title>Running and debugging GStreamer Applications</title>
26 <title>Environment variables</title>
29 GStreamer inspects a few of environment variables in addition to standard
30 variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
33 <formalpara id="GST_PLUGIN_SYSTEM_PATH">
34 <title><envar>GST_PLUGIN_SYSTEM_PATH</envar></title>
38 This environment variable can be set to a colon-separated list of paths.
39 If this variable is not set, GStreamer will fill in this list for you
44 plug-ins in the user's home directory. These are stored in a directory called
45 <filename>plugins</filename> inside the
46 <filename>.gstreamer-&GST_MAJORMINOR;</filename> directory in the user's
52 plug-ins installed system-wide. On this system, they are stored in
53 <filename>&GST_PLUGINS_DIR;</filename>.
61 GStreamer will scan these paths for GStreamer plug-ins. These plug-ins will
62 be loaded after the plug-ins in the GST_PLUGIN_PATH variable below.
64 The paths are scanned in the given order. This allows a user to override
65 system-installed plug-ins with his own versions.
69 Setting this variable to an empty string will cause GStreamer not to scan any
70 system paths at all for plug-ins. This can be useful if you're running
71 uninstalled (for development purposes) or while running testsuites.
76 <formalpara id="GST_PLUGIN_PATH">
77 <title><envar>GST_PLUGIN_PATH</envar></title>
80 This environment variable can be set to a colon-separated list of paths.
81 GStreamer will scan these paths for GStreamer plug-ins. These plug-ins will
82 be loaded in addition to, and before, the plug-ins in the system paths.
87 <formalpara id="GST_DEBUG">
88 <title><envar>GST_DEBUG</envar></title>
91 If GStreamer has been configured with <option>--enable-gst-debug=yes</option>,
92 this variable can be set to a list of debug options, which cause GStreamer
93 to print out different types of debugging information to stderr.
96 The variable takes a comma-separated list of "category_name:level" pairs
97 to set specific levels for the individual categories.
98 The level value ranges from 0 (nothing) to 5 (LOG).
102 <term>1 - <option>ERROR</option></term>
105 Logs all fatal errors. These are errors that do not allow the core or elements
106 to perform the requested action. The application can still recover if
107 programmed to handle the conditions that triggered the error.
113 <term>2 - <option>WARNING</option></term>
116 Logs all warnings. Typically these are non-fatal, but user-visible problems
117 are expected to happen.
123 <term>3 - <option>INFO</option></term>
126 Logs all informational messages. These are typically used for events in
127 the system that only happen once, or are important and rare enough to be
128 logged at this level.
134 <term>4 - <option>DEBUG</option></term>
137 Logs all debug messages. These are general debug messages for events
138 that happen only a limited number of times during an object's lifetime;
139 these include setup, teardown, change of parameters, ...
145 <term>5 - <option>LOG</option></term>
148 Logs all log messages. These are messages for events
149 that happen repeatedly during an object's lifetime;
150 these include streaming and steady-state conditions.
156 The category_name can contain "<option>*"</option> as a wildcard.
160 For example, setting <envar>GST_DEBUG</envar> to
161 <option>GST_AUTOPLUG:5,GST_ELEMENT_*:3</option>, will cause the
162 <option>GST_AUTOPLUG</option> category to be logged at full
163 <option>LOG</option> level, while all categories starting with
164 <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
168 To get all possible debug output, set
169 <envar>GST_DEBUG</envar>
170 to <option>*:5</option>
175 <formalpara id="GST_DEBUG_NO_COLOR">
176 <title><envar>GST_DEBUG_NO_COLOR</envar></title>
179 Set this environment variable to any value ("1" typically) to switch off
180 colouring in GST_DEBUG output. This has the same effect as specifying the
181 <option>--gst-debug-no-color</option> command line option to well-behaved
182 GStreamer applications (ie. those that pass command-line options correctly to
184 This is particularly useful to reduce the size of debug output and also allows
185 for the output to be compressed much better than with colours turned on.
190 <formalpara id="GST_DEBUG_DUMP_DOT_DIR">
191 <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title>
194 Set this environment variable to a path to turn on all
195 #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls
196 and have the dot files in that location.
201 <formalpara id="GST_REGISTRY_FORK">
202 <title><envar>GST_REGISTRY_FORK</envar></title>
205 Set this environment variable to "no" to prevent GStreamer from forking on
206 startup in order to update the plugin registry. This is useful for debugging
207 purposes, but should not be used under normal circumstances, since it means
208 that plugins may be loaded into memory even if they are not needed by the
214 <formalpara id="GST_REGISTRY_UPDATE">
215 <title><envar>GST_REGISTRY_UPDATE</envar></title>
218 Set this environment variable to "no" to prevent GStreamer from updating the
219 plugin registry. This is useful for embedded device which is not updating the
220 plugins frequently, it will save time when doing gst_init().