</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_API_VERSION;</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 id="GST_DEBUG">
<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>
<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> command line option to well-behaved
-GStreamer applications (ie. those that pass command-line options correctly to
-GStreamer).
+<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>
#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>
+<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>
</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