| <?xml version="1.0"?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" |
| "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ |
| <!ENTITY % version-entities SYSTEM "version.entities"> |
| %version-entities; |
| <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> |
| ]> |
| <refentry id="gst-running" revision="08 Oct 2005"> |
| <refmeta> |
| <refentrytitle>Running GStreamer Applications</refentrytitle> |
| <manvolnum>3</manvolnum> |
| <refmiscinfo>GStreamer Core</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>Running GStreamer Applications</refname> |
| <refpurpose> |
| How to run and debug your GStreamer application |
| </refpurpose> |
| </refnamediv> |
| |
| <refsect1> |
| <title>Running and debugging GStreamer Applications</title> |
| |
| <refsect2> |
| <title>Environment variables</title> |
| |
| <para> |
| GStreamer inspects a few of environment variables in addition to standard |
| variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>. |
| </para> |
| |
| <formalpara id="GST_PLUGIN_SYSTEM_PATH"> |
| <title><envar>GST_PLUGIN_SYSTEM_PATH</envar>, |
| <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar></title> |
| |
| <para> |
| |
| 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 |
| <itemizedlist> |
| <listitem> |
| <para> |
| plug-ins in the user's home directory, or rather the user's "data home" |
| directory according to the xdg base dir specification. Usually this will be |
| a directory called |
| <filename>plugins</filename> inside the |
| <filename>.local/share/gstreamer-&GST_API_VERSION;</filename> directory in |
| the user's home directory by default, though this search path may change if |
| the XDG_DATA_HOME environment variable is set. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| plug-ins installed system-wide. On this system, they are stored in |
| <filename>&GST_PLUGINS_DIR;</filename>. |
| </para> |
| |
| </listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| The GST_PLUGIN_SYSTEM_PATH_1_0 variant is useful if both the old GStreamer 0.10 |
| version and the new GStreamer 1.0 version need to be pointed to new plugin |
| paths. The latter will use the _1_0 variant over the non-versioned one if |
| it is set. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_PLUGIN_PATH"> |
| <title><envar>GST_PLUGIN_PATH</envar>, <envar>GST_PLUGIN_PATH_1_0</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| The GST_PLUGIN_PATH_1_0 variant is useful if both the old GStreamer 0.10 |
| version and the new GStreamer 1.0 version need to be pointed to new plugin |
| paths. The latter will use the _1_0 variant over the non-versioned one if |
| it is set. |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_DEBUG"> |
| <title><envar>GST_DEBUG</envar></title> |
| |
| <para> |
| If GStreamer has been configured with <option>--enable-gst-debug=yes</option>, |
| this variable can be set to a list of debug options, which cause GStreamer |
| to print out different types of debugging information to stderr. |
| </para> |
| <para> |
| 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). |
| <variablelist> |
| |
| <varlistentry> |
| <term>1 - <option>ERROR</option></term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>2 - <option>WARNING</option></term> |
| <listitem> |
| <para> |
| Logs all warnings. Typically these are non-fatal, but user-visible problems |
| are expected to happen. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>3 - <option>FIXME</option></term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>4 - <option>INFO</option></term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>5 - <option>DEBUG</option></term> |
| <listitem> |
| <para> |
| 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, ... |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>6 - <option>LOG</option></term> |
| <listitem> |
| <para> |
| Logs all log messages. These are messages for events |
| that happen repeatedly during an object's lifetime; |
| these include streaming and steady-state conditions. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>7 - <option>TRACE</option></term> |
| <listitem> |
| <para> |
| Logs all trace messages. These messages for events |
| that happen repeatedly during an object's lifetime such as the |
| ref/unref cycles. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>9 - <option>MEMDUMP</option></term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| The category_name can contain "<option>*"</option> as a wildcard. |
| </para> |
| |
| <para> |
| For example, setting <envar>GST_DEBUG</envar> to |
| <option>GST_AUTOPLUG:6,GST_ELEMENT_*:4</option>, will cause the |
| <option>GST_AUTOPLUG</option> category to be logged at full |
| <option>LOG</option> level, while all categories starting with |
| <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level. |
| </para> |
| |
| <para> |
| To get all possible debug output, set |
| <envar>GST_DEBUG</envar> |
| to <option>*:9</option>. For debugging purposes a <option>*:6</option> debug |
| 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 |
| <option>*:6</option> log is also what will be requested usually. It's often |
| also worth running with <option>*:3</option> to see if there are any |
| non-fatal errors or warnings that might be related to the problem at hand. |
| </para> |
| |
| <para> |
| Since GStreamer 1.2 it is also possible to specify debug levels by name, |
| e.g. GST_DEBUG=*:WARNING,*audio*:LOG |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_DEBUG_NO_COLOR"> |
| <title><envar>GST_DEBUG_NO_COLOR</envar></title> |
| |
| <para> |
| 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 |
| <option>--gst-debug-no-color</option> or |
| <option>--gst-debug-color-mode</option>=off 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. |
| </para> |
| <para> |
| Has the same effect as setting GST_DEBUG_COLOR_MODE environment variable to |
| "off". |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_DEBUG_COLOR_MODE"> |
| <title><envar>GST_DEBUG_COLOR_MODE</envar></title> |
| |
| <para> |
| Set this environment variable to change log colouring in GST_DEBUG output. |
| Possible values: |
| <variablelist> |
| |
| <varlistentry> |
| <term><option>on</option></term> |
| <listitem> |
| <para> |
| Enables debug log output coloring. Uses default coloring method for current |
| platform. This is the default. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>off</option></term> |
| <listitem> |
| <para> |
| Disables debug log output coloring. This has the same effect as specifying the |
| <option>--gst-debug-color-mode</option>=off 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. |
| </para> |
| <para> |
| Has the same effect as setting GST_DEBUG_NO_COLOR environment variable to |
| any value. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>auto</option></term> |
| <listitem> |
| <para> |
| Same as <option>on</option>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>disable</option></term> |
| <listitem> |
| <para> |
| Same as <option>off</option>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>unix</option></term> |
| <listitem> |
| <para> |
| Enables debug log output coloring and forces the use of UNIX termial codes |
| for coloring, even if this method is not normally used on current platform. |
| This has the same effect as specifying the |
| <option>--gst-debug-color-mode</option>=unix command line option to |
| well-behaved GStreamer applications (ie. those that pass command-line options |
| correctly to GStreamer). |
| This is particularly useful to dump debug output into a file on non-UNIX |
| platforms to be sent to developers who have viewers that support UNIX terminal |
| codes. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_DEBUG_OPTIONS"> |
| <title><envar>GST_DEBUG_OPTIONS</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_DEBUG_DUMP_DOT_DIR"> |
| <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| This will only work if the application in question makes these calls in |
| strategic places (like when the pipeline state changes or an error occurs). |
| gst-launch-&GST_API_VERSION; is one such application. |
| </para> |
| <para> |
| These .dot files can then be turned into images using the 'dot' utility |
| from the graphviz set of tools, like this: |
| <command>dot foo.dot -Tsvg -o foo.svg</command> or |
| <command>dot foo.dot -Tpng -o foo.png</command> or |
| <command>dot foo.dot -Tjpg -o foo.jpg</command>. |
| </para> |
| <para> |
| There is also a utility called <command>xdot</command> which allows you to |
| view the dot file directly without converting it first. |
| </para> |
| |
| |
| </formalpara> |
| |
| <formalpara id="GST_REGISTRY"> |
| <title><envar>GST_REGISTRY</envar>, <envar>GST_REGISTRY_1_0</envar></title> |
| |
| <para> |
| Set this environment variable to make GStreamer use a different file for the |
| plugin cache / registry than the default one. This is useful when operating |
| in a separate environment which should not affect the default cache in the |
| user's home directory. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_REGISTRY_FORK"> |
| <title><envar>GST_REGISTRY_FORK</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_REGISTRY_UPDATE"> |
| <title><envar>GST_REGISTRY_UPDATE</envar></title> |
| |
| <para> |
| 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(). |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_TRACE"> |
| <title><envar>GST_TRACE</envar></title> |
| |
| <para> |
| Enable memory allocation tracing. Most GStreamer objects have support for |
| tracing the number of unfreed objects and their memory pointers. |
| </para> |
| <para> |
| The variable takes a comma-separated list of tracing options to enable. |
| <variablelist> |
| |
| <varlistentry> |
| <term>live</term> |
| <listitem> |
| <para> |
| Counts all live objects and dumps an overview of the number of unfreed |
| objects at program exit. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>mem-live</term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| Use <option>all</option> to enable all tracing flags. |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_DEBUG_FILE"> |
| <title><envar>GST_DEBUG_FILE</envar></title> |
| |
| <para> |
| Set this variable to a file path to redirect all GStreamer debug |
| messages to this file. If left unset, debug messages with be output |
| unto the standard error. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="ORC_CODE"> |
| <title><envar>ORC_CODE</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="G_DEBUG"> |
| <title><envar>G_DEBUG</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="G_SLICE"> |
| <title><envar>G_SLICE</envar></title> |
| |
| <para> |
| 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. |
| </para> |
| |
| </formalpara> |
| |
| <formalpara id="GST_TAG_ENCODING"> |
| <title><envar>GST_TAG_ENCODING</envar></title> |
| <para> |
| Try this character encoding first for tag-related strings where the encoding |
| is not defined and which are not UTF-8 already. By default the current locale |
| will be tried (if not UTF-8). |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_TAG_ID3_ENCODING"> |
| <title><envar>GST_TAG_ID3_ENCODING</envar></title> |
| <para> |
| Try this character encoding first for ID3 tag-related strings where the |
| encoding is not defined and which are not UTF-8 already. By default the current |
| locale will be tried (if not UTF-8). |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_TAG_ID3V1_ENCODING"> |
| <title><envar>GST_TAG_ID3V1_ENCODING</envar></title> |
| <para> |
| Try this character encoding first for ID3v1 tag-related strings where the |
| encoding does not look like UTF-8. |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_GL_WINDOW"> |
| <title><envar>GST_GL_WINDOW</envar></title> |
| <para> |
| Influences the window system to use by the GStreamer OpenGL library. |
| Common values are 'x11', 'wayland', 'win32' or 'cocoa'. |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_GL_PLATFORM"> |
| <title><envar>GST_GL_PLATFORM</envar></title> |
| <para> |
| Influences the OpenGL platform to use by the GStreamer OpenGL library. |
| Common values are 'egl', 'glx', 'wgl' or 'cgl'. |
| </para> |
| </formalpara> |
| |
| <formalpara id="GST_GL_API"> |
| <title><envar>GST_GL_API</envar></title> |
| <para> |
| Influences the OpenGL API requested by the OpenGL platform. |
| Common values are 'opengl' or 'gles2'. |
| </para> |
| </formalpara> |
| |
| </refsect2> |
| |
| </refsect1> |
| |
| </refentry> |