+<?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>
</para>
<formalpara id="GST_PLUGIN_SYSTEM_PATH">
- <title><envar>GST_PLUGIN_SYSTEM_PATH</envar></title>
+ <title><envar>GST_PLUGIN_SYSTEM_PATH</envar>,
+ <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar></title>
<para>
<itemizedlist>
<listitem>
<para>
-plug-ins in the user's home directory. These are stored in a directory called
+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>.gstreamer-&GST_MAJORMINOR;</filename> directory in the user's
-home directory.
+<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>
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
</formalpara>
<formalpara id="GST_PLUGIN_PATH">
- <title><envar>GST_PLUGIN_PATH</envar></title>
+ <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>
+<formalpara id="GST_DEBUG">
<title><envar>GST_DEBUG</envar></title>
<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 5 (LOG).
+The level value ranges from 0 (nothing) to 9 (MEMDUMP).
<variablelist>
<varlistentry>
</varlistentry>
<varlistentry>
- <term>3 - <option>INFO</option></term>
+ <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
</varlistentry>
<varlistentry>
- <term>4 - <option>DEBUG</option></term>
+ <term>5 - <option>DEBUG</option></term>
<listitem>
<para>
Logs all debug messages. These are general debug messages for events
</varlistentry>
<varlistentry>
- <term>5 - <option>LOG</option></term>
+ <term>6 - <option>LOG</option></term>
<listitem>
<para>
Logs all log messages. These are messages for events
</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>
For example, setting <envar>GST_DEBUG</envar> to
-<option>GST_AUTOPLUG:5,GST_ELEMENT_*:3</option>, will cause the
+<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>
To get all possible debug output, set
<envar>GST_DEBUG</envar>
-to <option>*:5</option>
+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>
+
+</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>
projects / platform / upstream / gstreamer.git / blobdiff