|GStreamer 1.0 Core Reference Manual|
Running GStreamer Applications
Running GStreamer Applications — How to run and debug your GStreamer application
GStreamer inspects a few of environment variables in addition to standard
plug-ins in the user's home directory. These are stored in a directory called
plugins inside the
.gstreamer-1.0 directory in the user's
plug-ins installed system-wide. On this system, they are stored in
GStreamer will scan these paths for GStreamer plug-ins. These plug-ins will be loaded after the plug-ins in the GST_PLUGIN_PATH variable below. The paths are scanned in the given order. This allows a user to override system-installed plug-ins with his own versions. Setting this variable to an empty string will cause GStreamer not to scan any system paths at all for plug-ins. This can be useful if you're running uninstalled (for development purposes) or while running testsuites.
This environment variable can be set to a colon-separated list of paths.
GStreamer will scan these paths for GStreamer plug-ins. These plug-ins will
be loaded in addition to, and before, the plug-ins in the system paths.
If GStreamer has been configured with
this variable can be set to a list of debug options, which cause GStreamer
to print out different types of debugging information to stderr.
The variable takes a comma-separated list of "category_name:level" pairs
to set specific levels for the individual categories.
The level value ranges from 0 (nothing) to 9 (MEMDUMP).
Logs all fatal errors. These are errors that do not allow the core or elements to perform the requested action. The application can still recover if programmed to handle the conditions that triggered the error.
Logs all warnings. Typically these are non-fatal, but user-visible problems are expected to happen.
Logs all fixme messages. Fixme messages are messages that indicate that something in the executed code path is not fully implemented or handled yet. The purpose of this message is to make it easier to spot incomplete/unfinished pieces of code when reading the debug log.
Logs all informational messages. These are typically used for events in the system that only happen once, or are important and rare enough to be logged at this level.
Logs all debug messages. These are general debug messages for events that happen only a limited number of times during an object's lifetime; these include setup, teardown, change of parameters, ...
Logs all log messages. These are messages for events that happen repeatedly during an object's lifetime; these include streaming and steady-state conditions.
Logs all trace messages. These messages for events that happen repeatedly during an object's lifetime such as the ref/unref cycles.
Log all memory dump messages. Memory dump messages are used to log (small) chunks of data as memory dumps in the log. They will be displayed as hexdump with ASCII characters.
The category_name can contain "
*" as a wildcard.
For example, setting
GST_AUTOPLUG:6,GST_ELEMENT_*:4, will cause the
GST_AUTOPLUG category to be logged at full
LOG level, while all categories starting with
GST_ELEMENT_ will be logged at
To get all possible debug output, set
*:9. For debugging purposes a
log is usually the most useful, as it contains all important information, but
hides a lot of noise such as refs/unrefs. For bug reporting purposes, a
*:6 log is also what will be requested usually. It's often
also worth running with
*:3 to see if there are any
non-fatal errors or warnings that might be related to the problem at hand.
Set this environment variable to any value ("1" typically) to switch off
colouring in GST_DEBUG output. This has the same effect as specifying the
--gst-debug-no-color command line option to well-behaved
GStreamer applications (ie. those that pass command-line options correctly to
This is particularly useful to reduce the size of debug output and also allows
for the output to be compressed much better than with colours turned on.
This environment variable can be used to tweak the behaviour of the debugging
system. Currently the only options supported are "pretty-tags" and "full-tags".
In "pretty-tags" mode (the default), taglists in the debug log will be
serialized so that only the first few and last few bytes of a buffer-type tag
will be serialized into the log, to avoid dumping hundreds of lines of useless
output into the log in case of large image tags and the like.
Set this environment variable to "no" to prevent GStreamer from forking on
startup in order to update the plugin registry. This is useful for debugging
purposes, but should not be used under normal circumstances, since it means
that plugins may be loaded into memory even if they are not needed by the
Set this environment variable to "no" to prevent GStreamer from updating the
plugin registry. This is useful for embedded device which is not updating the
plugins frequently, it will save time when doing gst_init().
Enable memory allocation tracing. Most GStreamer objects have support for
tracing the number of unfreed objects and their memory pointers.
The variable takes a comma-separated list of tracing options to enable.
Counts all live objects and dumps an overview of the number of unfreed objects at program exit.
Keep track of the unfreed memory pointers and dump an overview of all unfreed memory at program exit. Together with a level 9 debug log this can be used to follow the lifecycle of leaked objects in order to track down where they are leaked. This can be useful for debugging memory leaks in situations where tools such as valgrind are not available, or not an option.
all to enable all tracing flags.
Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
such as gdb to create useful backtraces from Orc-generated code. Set
ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
generator is producing incorrect code (Quite a few important
GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
One can also combine flags like ORC_CODE=backup,debug.
Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
GStreamer programs abort when a critical warning such as an assertion failure
occurs. This is useful if you want to find out which part of the code caused
that warning to be triggered and under what circumstances. Simply set G_DEBUG
as mentioned above and run the program in gdb (or let it core dump). Then get
a stack trace in the usual way.
Useful GLib environment variable. Set G_SLICE=always-malloc when running
GStreamer programs in valgrind, or debugging memory leaks with other tools.
See the GLib API reference for more details.