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>,
35 <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar></title>
39 This environment variable can be set to a colon-separated list of paths.
40 If this variable is not set, GStreamer will fill in this list for you
45 plug-ins in the user's home directory, or rather the user's "data home"
46 directory according to the xdg base dir specification. Usually this will be
48 <filename>plugins</filename> inside the
49 <filename>.local/share/.gstreamer-&GST_API_VERSION;</filename> directory in
50 the user's home directory by default, though this search path may change if
51 the XDG_DATA_HOME environment variable is set.
56 plug-ins installed system-wide. On this system, they are stored in
57 <filename>&GST_PLUGINS_DIR;</filename>.
65 GStreamer will scan these paths for GStreamer plug-ins. These plug-ins will
66 be loaded after the plug-ins in the GST_PLUGIN_PATH variable below.
68 The paths are scanned in the given order. This allows a user to override
69 system-installed plug-ins with his own versions.
72 The GST_PLUGIN_SYSTEM_PATH_1_0 variant is useful if both the old GStreamer 0.10
73 version and the new GStreamer 1.0 version need to be pointed to new plugin
74 paths. The latter will use the _1_0 variant over the non-versioned one if
79 Setting this variable to an empty string will cause GStreamer not to scan any
80 system paths at all for plug-ins. This can be useful if you're running
81 uninstalled (for development purposes) or while running testsuites.
86 <formalpara id="GST_PLUGIN_PATH">
87 <title><envar>GST_PLUGIN_PATH</envar>, <envar>GST_PLUGIN_PATH_1_0</envar></title>
90 This environment variable can be set to a colon-separated list of paths.
91 GStreamer will scan these paths for GStreamer plug-ins. These plug-ins will
92 be loaded in addition to, and before, the plug-ins in the system paths.
95 The GST_PLUGIN_PATH_1_0 variant is useful if both the old GStreamer 0.10
96 version and the new GStreamer 1.0 version need to be pointed to new plugin
97 paths. The latter will use the _1_0 variant over the non-versioned one if
102 <formalpara id="GST_DEBUG">
103 <title><envar>GST_DEBUG</envar></title>
106 If GStreamer has been configured with <option>--enable-gst-debug=yes</option>,
107 this variable can be set to a list of debug options, which cause GStreamer
108 to print out different types of debugging information to stderr.
111 The variable takes a comma-separated list of "category_name:level" pairs
112 to set specific levels for the individual categories.
113 The level value ranges from 0 (nothing) to 9 (MEMDUMP).
117 <term>1 - <option>ERROR</option></term>
120 Logs all fatal errors. These are errors that do not allow the core or elements
121 to perform the requested action. The application can still recover if
122 programmed to handle the conditions that triggered the error.
128 <term>2 - <option>WARNING</option></term>
131 Logs all warnings. Typically these are non-fatal, but user-visible problems
132 are expected to happen.
138 <term>3 - <option>FIXME</option></term>
141 Logs all fixme messages. Fixme messages are messages that indicate that something
142 in the executed code path is not fully implemented or handled yet. The purpose
143 of this message is to make it easier to spot incomplete/unfinished pieces of
144 code when reading the debug log.
150 <term>4 - <option>INFO</option></term>
153 Logs all informational messages. These are typically used for events in
154 the system that only happen once, or are important and rare enough to be
155 logged at this level.
161 <term>5 - <option>DEBUG</option></term>
164 Logs all debug messages. These are general debug messages for events
165 that happen only a limited number of times during an object's lifetime;
166 these include setup, teardown, change of parameters, ...
172 <term>6 - <option>LOG</option></term>
175 Logs all log messages. These are messages for events
176 that happen repeatedly during an object's lifetime;
177 these include streaming and steady-state conditions.
183 <term>7 - <option>TRACE</option></term>
186 Logs all trace messages. These messages for events
187 that happen repeatedly during an object's lifetime such as the
194 <term>9 - <option>MEMDUMP</option></term>
197 Log all memory dump messages. Memory dump messages are used to log
198 (small) chunks of data as memory dumps in the log. They will be displayed
199 as hexdump with ASCII characters.
205 The category_name can contain "<option>*"</option> as a wildcard.
209 For example, setting <envar>GST_DEBUG</envar> to
210 <option>GST_AUTOPLUG:6,GST_ELEMENT_*:4</option>, will cause the
211 <option>GST_AUTOPLUG</option> category to be logged at full
212 <option>LOG</option> level, while all categories starting with
213 <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
217 To get all possible debug output, set
218 <envar>GST_DEBUG</envar>
219 to <option>*:9</option>. For debugging purposes a <option>*:6</option> debug
220 log is usually the most useful, as it contains all important information, but
221 hides a lot of noise such as refs/unrefs. For bug reporting purposes, a
222 <option>*:6</option> log is also what will be requested usually. It's often
223 also worth running with <option>*:3</option> to see if there are any
224 non-fatal errors or warnings that might be related to the problem at hand.
228 Since GStreamer 1.2 it is also possible to specify debug levels by name,
229 e.g. GST_DEBUG=*:WARNING,*audio*:LOG
234 <formalpara id="GST_DEBUG_NO_COLOR">
235 <title><envar>GST_DEBUG_NO_COLOR</envar></title>
238 Set this environment variable to any value ("1" typically) to switch off
239 colouring in GST_DEBUG output. This has the same effect as specifying the
240 <option>--gst-debug-no-color</option> or
241 <option>--gst-debug-color-mode</option>=off command line option to
242 well-behaved GStreamer applications (ie. those that pass command-line
243 options correctly to GStreamer).
244 This is particularly useful to reduce the size of debug output and also allows
245 for the output to be compressed much better than with colours turned on.
248 Has the same effect as setting GST_DEBUG_COLOR_MODE environment variable to
254 <formalpara id="GST_DEBUG_COLOR_MODE">
255 <title><envar>GST_DEBUG_COLOR_MODE</envar></title>
258 Set this environment variable to change log colouring in GST_DEBUG output.
263 <term><option>on</option></term>
266 Enables debug log output coloring. Uses default coloring method for current
267 platform. This is the default.
273 <term><option>off</option></term>
276 Disables debug log output coloring. This has the same effect as specifying the
277 <option>--gst-debug-color-mode</option>=off command line option to
278 well-behaved GStreamer applications (ie. those that pass command-line
279 options correctly to GStreamer).
280 This is particularly useful to reduce the size of debug output and also allows
281 for the output to be compressed much better than with colours turned on.
284 Has the same effect as setting GST_DEBUG_NO_COLOR environment variable to
291 <term><option>auto</option></term>
294 Same as <option>on</option>.
300 <term><option>disable</option></term>
303 Same as <option>off</option>.
309 <term><option>unix</option></term>
312 Enables debug log output coloring and forces the use of UNIX termial codes
313 for coloring, even if this method is not normally used on current platform.
314 This has the same effect as specifying the
315 <option>--gst-debug-color-mode</option>=unix command line option to
316 well-behaved GStreamer applications (ie. those that pass command-line options
317 correctly to GStreamer).
318 This is particularly useful to dump debug output into a file on non-UNIX
319 platforms to be sent to developers who have viewers that support UNIX terminal
330 <formalpara id="GST_DEBUG_OPTIONS">
331 <title><envar>GST_DEBUG_OPTIONS</envar></title>
334 This environment variable can be used to tweak the behaviour of the debugging
335 system. Currently the only options supported are "pretty-tags" and "full-tags".
336 In "pretty-tags" mode (the default), taglists in the debug log will be
337 serialized so that only the first few and last few bytes of a buffer-type tag
338 will be serialized into the log, to avoid dumping hundreds of lines of useless
339 output into the log in case of large image tags and the like.
344 <formalpara id="GST_DEBUG_DUMP_DOT_DIR">
345 <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title>
348 Set this environment variable to a path to turn on all
349 #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls
350 and have the dot files in that location.
353 This will only work if the application in question makes these calls in
354 strategic places (like when the pipeline state changes or an error occurs).
355 gst-launch-&GST_API_VERSION; is one such application.
358 These .dot files can then be turned into images using the 'dot' utility
359 from the graphviz set of tools, like this:
360 <command>dot foo.dot -Tsvg -o foo.svg</command> or
361 <command>dot foo.dot -Tpng -o foo.png</command> or
362 <command>dot foo.dot -Tjpg -o foo.jpg</command>.
367 <formalpara id="GST_REGISTRY">
368 <title><envar>GST_REGISTRY</envar>, <envar>GST_REGISTRY_1_0</envar></title>
371 Set this environment variable to make GStreamer use a different file for the
372 plugin cache / registry than the default one. This is useful when operating
373 in a separate environment which should not affect the default cache in the
374 user's home directory.
379 <formalpara id="GST_REGISTRY_FORK">
380 <title><envar>GST_REGISTRY_FORK</envar></title>
383 Set this environment variable to "no" to prevent GStreamer from forking on
384 startup in order to update the plugin registry. This is useful for debugging
385 purposes, but should not be used under normal circumstances, since it means
386 that plugins may be loaded into memory even if they are not needed by the
392 <formalpara id="GST_REGISTRY_UPDATE">
393 <title><envar>GST_REGISTRY_UPDATE</envar></title>
396 Set this environment variable to "no" to prevent GStreamer from updating the
397 plugin registry. This is useful for embedded device which is not updating the
398 plugins frequently, it will save time when doing gst_init().
403 <formalpara id="GST_TRACE">
404 <title><envar>GST_TRACE</envar></title>
407 Enable memory allocation tracing. Most GStreamer objects have support for
408 tracing the number of unfreed objects and their memory pointers.
411 The variable takes a comma-separated list of tracing options to enable.
418 Counts all live objects and dumps an overview of the number of unfreed
419 objects at program exit.
425 <term>mem-live</term>
428 Keep track of the unfreed memory pointers and dump an overview of all unfreed
429 memory at program exit. Together with a level 9 debug log this can be used to
430 follow the lifecycle of leaked objects in order to track down where they are
431 leaked. This can be useful for debugging memory leaks in situations where
432 tools such as valgrind are not available, or not an option.
438 Use <option>all</option> to enable all tracing flags.
442 <formalpara id="GST_DEBUG_FILE">
443 <title><envar>GST_DEBUG_FILE</envar></title>
446 Set this variable to a file path to redirect all GStreamer debug
447 messages to this file. If left unset, debug messages with be output
448 unto the standard error.
453 <formalpara id="ORC_CODE">
454 <title><envar>ORC_CODE</envar></title>
457 Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
458 such as gdb to create useful backtraces from Orc-generated code. Set
459 ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
460 generator is producing incorrect code (Quite a few important
461 GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
462 One can also combine flags like ORC_CODE=backup,debug.
467 <formalpara id="G_DEBUG">
468 <title><envar>G_DEBUG</envar></title>
471 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
472 GStreamer programs abort when a critical warning such as an assertion failure
473 occurs. This is useful if you want to find out which part of the code caused
474 that warning to be triggered and under what circumstances. Simply set G_DEBUG
475 as mentioned above and run the program in gdb (or let it core dump). Then get
476 a stack trace in the usual way.
481 <formalpara id="G_SLICE">
482 <title><envar>G_SLICE</envar></title>
485 Useful GLib environment variable. Set G_SLICE=always-malloc when running
486 GStreamer programs in valgrind, or debugging memory leaks with other tools.
487 See the GLib API reference for more details.
492 <formalpara id="GST_TAG_ENCODING">
493 <title><envar>GST_TAG_ENCODING</envar></title>
495 Try this character encoding first for tag-related strings where the encoding
496 is not defined and which are not UTF-8 already. By defaul the current locale
497 will be tried (if not UTF-8).
501 <formalpara id="GST_TAG_ID3_ENCODING">
502 <title><envar>GST_TAG_ID3_ENCODING</envar></title>
504 Try this character encoding first for ID3 tag-related strings where the
505 encoding is not defined and which are not UTF-8 already. By defaul the current
506 locale will be tried (if not UTF-8).
510 <formalpara id="GST_TAG_ID3V1_ENCODING">
511 <title><envar>GST_TAG_ID3V1_ENCODING</envar></title>
513 Try this character encoding first for ID3v1 tag-related strings where the
514 encoding does not look like UTF-8.