Running GStreamer Applications

Running GStreamer Applications — How to run and debug your GStreamer application

Running and debugging GStreamer Applications

Environment variables

GStreamer inspects a few of environment variables in addition to standard variables like LANG, PATH or HOME.

GST_PLUGIN_SYSTEM_PATH This environment variable can be set to a colon-separated list of paths. If this variable is not set, GStreamer will fill in this list for you with

  • plug-ins in the user's home directory. These are stored in a directory called plugins inside the .gstreamer-0.10 directory in the user's home directory.

  • plug-ins installed system-wide. On this system, they are stored in /usr/local/lib/gstreamer-0.10.

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.

GST_PLUGIN_PATH 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.

GST_DEBUG If GStreamer has been configured with --enable-gst-debug=yes, 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 5 (LOG).

1 - ERROR

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.

2 - WARNING

Logs all warnings. Typically these are non-fatal, but user-visible problems are expected to happen.

3 - INFO

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.

4 - DEBUG

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, ...

5 - LOG

Logs all log messages. These are messages for events that happen repeatedly during an object's lifetime; these include streaming and steady-state conditions.

The category_name can contain "*" as a wildcard. For example, setting GST_DEBUG to GST_AUTOPLUG:5,GST_ELEMENT_*:3, will cause the GST_AUTOPLUG category to be logged at full LOG level, while all categories starting with GST_ELEMENT_ will be logged at INFO level. To get all possible debug output, set GST_DEBUG to *:5

GST_DEBUG_NO_COLOR 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 GStreamer). 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.

GST_DEBUG_OPTIONS 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.

GST_DEBUG_DUMP_DOT_DIR Set this environment variable to a path to turn on all #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls and have the dot files in that location.

GST_REGISTRY_FORK 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 application.

GST_REGISTRY_UPDATE 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().

ORC_CODE 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.

G_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.

G_SLICE 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.