mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-24 10:41:04 +00:00
551 lines
17 KiB
XML
551 lines
17 KiB
XML
<?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>
|