"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [

%version-entities;

]>

<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 (or

semicolon-separated list on Windows).

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 (or a

semicolon-separated list on Windows).

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>

When gst-launch-&GST_API_VERSION; changes state through NULL to PLAYING

and back to NULL, a dot file is generated on each state change. To have

gst-launch-&GST_API_VERSION; write a snapshot of the pipeline state, send

a SIGHUP to the gst-launch-&GST_API_VERSION; process.

  </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>