| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Running GStreamer Applications: GStreamer 1.0 Core Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GStreamer 1.0 Core Reference Manual"> |
| <link rel="up" href="gstreamer.html" title="GStreamer Overview"> |
| <link rel="prev" href="gst-building.html" title="Building GStreamer and GStreamer Applications"> |
| <link rel="next" href="libgstreamer.html" title="GStreamer Core Library"> |
| <meta name="generator" content="GTK-Doc V1.25 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="gstreamer.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="gst-building.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="libgstreamer.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry"> |
| <a name="gst-running"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle">Running GStreamer Applications</span></h2> |
| <p>Running GStreamer Applications — |
| How to run and debug your GStreamer application |
| </p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="id-1.2.6.3"></a><h2>Running and debugging GStreamer Applications</h2> |
| <div class="refsect2"> |
| <a name="id-1.2.6.3.2"></a><h3>Environment variables</h3> |
| <p> |
| GStreamer inspects a few of environment variables in addition to standard |
| variables like <code class="envar">LANG</code>, <code class="envar">PATH</code> or <code class="envar">HOME</code>. |
| </p> |
| <p><a name="GST_PLUGIN_SYSTEM_PATH"></a><b><code class="envar">GST_PLUGIN_SYSTEM_PATH</code>, |
| <code class="envar">GST_PLUGIN_SYSTEM_PATH_1_0</code>. </b> |
| |
| 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 |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p> |
| 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 |
| <code class="filename">plugins</code> inside the |
| <code class="filename">.local/share/gstreamer-1.0</code> directory in |
| the user's home directory by default, though this search path may change if |
| the XDG_DATA_HOME environment variable is set. |
| </p></li> |
| <li class="listitem"><p> |
| plug-ins installed system-wide. On this system, they are stored in |
| <code class="filename">/usr/local/lib/gstreamer-1.0</code>. |
| </p></li> |
| </ul></div> |
| <p> |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| </p> |
| <p><a name="GST_PLUGIN_PATH"></a><b><code class="envar">GST_PLUGIN_PATH</code>, <code class="envar">GST_PLUGIN_PATH_1_0</code>. </b> |
| 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. |
| |
| 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. |
| </p> |
| <p><a name="GST_DEBUG"></a><b><code class="envar">GST_DEBUG</code>. </b> |
| If GStreamer has been configured with <code class="option">--enable-gst-debug=yes</code>, |
| this variable can be set to a list of debug options, which cause GStreamer |
| to print out different types of debugging information to stderr. |
| |
| 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). |
| </p> |
| <div class="variablelist"><table border="0" class="variablelist"> |
| <colgroup> |
| <col align="left" valign="top"> |
| <col> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td><p><span class="term">1 - <code class="option">ERROR</code></span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">2 - <code class="option">WARNING</code></span></p></td> |
| <td><p> |
| Logs all warnings. Typically these are non-fatal, but user-visible problems |
| are expected to happen. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">3 - <code class="option">FIXME</code></span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">4 - <code class="option">INFO</code></span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">5 - <code class="option">DEBUG</code></span></p></td> |
| <td><p> |
| 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, ... |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">6 - <code class="option">LOG</code></span></p></td> |
| <td><p> |
| Logs all log messages. These are messages for events |
| that happen repeatedly during an object's lifetime; |
| these include streaming and steady-state conditions. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">7 - <code class="option">TRACE</code></span></p></td> |
| <td><p> |
| Logs all trace messages. These messages for events |
| that happen repeatedly during an object's lifetime such as the |
| ref/unref cycles. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">9 - <code class="option">MEMDUMP</code></span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p> |
| |
| The category_name can contain "<code class="option">*"</code> as a wildcard. |
| |
| For example, setting <code class="envar">GST_DEBUG</code> to |
| <code class="option">GST_AUTOPLUG:6,GST_ELEMENT_*:4</code>, will cause the |
| <code class="option">GST_AUTOPLUG</code> category to be logged at full |
| <code class="option">LOG</code> level, while all categories starting with |
| <code class="option">GST_ELEMENT_</code> will be logged at <code class="option">INFO</code> level. |
| |
| To get all possible debug output, set |
| <code class="envar">GST_DEBUG</code> |
| to <code class="option">*:9</code>. For debugging purposes a <code class="option">*:6</code> 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 |
| <code class="option">*:6</code> log is also what will be requested usually. It's often |
| also worth running with <code class="option">*:3</code> to see if there are any |
| non-fatal errors or warnings that might be related to the problem at hand. |
| |
| Since GStreamer 1.2 it is also possible to specify debug levels by name, |
| e.g. GST_DEBUG=*:WARNING,*audio*:LOG |
| </p> |
| <p><a name="GST_DEBUG_NO_COLOR"></a><b><code class="envar">GST_DEBUG_NO_COLOR</code>. </b> |
| 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 |
| <code class="option">--gst-debug-no-color</code> or |
| <code class="option">--gst-debug-color-mode</code>=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. |
| |
| Has the same effect as setting GST_DEBUG_COLOR_MODE environment variable to |
| "off". |
| </p> |
| <p><a name="GST_DEBUG_COLOR_MODE"></a><b><code class="envar">GST_DEBUG_COLOR_MODE</code>. </b> |
| Set this environment variable to change log colouring in GST_DEBUG output. |
| Possible values: |
| </p> |
| <div class="variablelist"><table border="0" class="variablelist"> |
| <colgroup> |
| <col align="left" valign="top"> |
| <col> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td><p><span class="term"><code class="option">on</code></span></p></td> |
| <td><p> |
| Enables debug log output coloring. Uses default coloring method for current |
| platform. This is the default. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">off</code></span></p></td> |
| <td> |
| <p> |
| Disables debug log output coloring. This has the same effect as specifying the |
| <code class="option">--gst-debug-color-mode</code>=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. |
| </p> |
| <p> |
| Has the same effect as setting GST_DEBUG_NO_COLOR environment variable to |
| any value. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">auto</code></span></p></td> |
| <td><p> |
| Same as <code class="option">on</code>. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">disable</code></span></p></td> |
| <td><p> |
| Same as <code class="option">off</code>. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">unix</code></span></p></td> |
| <td><p> |
| 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 |
| <code class="option">--gst-debug-color-mode</code>=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. |
| </p></td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p> |
| </p> |
| <p><a name="GST_DEBUG_OPTIONS"></a><b><code class="envar">GST_DEBUG_OPTIONS</code>. </b> |
| 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. |
| </p> |
| <p><a name="GST_DEBUG_DUMP_DOT_DIR"></a><b><code class="envar">GST_DEBUG_DUMP_DOT_DIR</code>. </b> |
| 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. |
| |
| 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-1.0 is one such application. |
| |
| These .dot files can then be turned into images using the 'dot' utility |
| from the graphviz set of tools, like this: |
| <span class="command"><strong>dot foo.dot -Tsvg -o foo.svg</strong></span> or |
| <span class="command"><strong>dot foo.dot -Tpng -o foo.png</strong></span> or |
| <span class="command"><strong>dot foo.dot -Tjpg -o foo.jpg</strong></span>. |
| |
| There is also a utility called <span class="command"><strong>xdot</strong></span> which allows you to |
| view the dot file directly without converting it first. |
| </p> |
| <p><a name="GST_REGISTRY"></a><b><code class="envar">GST_REGISTRY</code>, <code class="envar">GST_REGISTRY_1_0</code>. </b> |
| 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. |
| </p> |
| <p><a name="GST_REGISTRY_FORK"></a><b><code class="envar">GST_REGISTRY_FORK</code>. </b> |
| 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. |
| </p> |
| <p><a name="GST_REGISTRY_UPDATE"></a><b><code class="envar">GST_REGISTRY_UPDATE</code>. </b> |
| 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(). |
| </p> |
| <p><a name="GST_TRACE"></a><b><code class="envar">GST_TRACE</code>. </b> |
| Enable memory allocation tracing. Most GStreamer objects have support for |
| tracing the number of unfreed objects and their memory pointers. |
| |
| The variable takes a comma-separated list of tracing options to enable. |
| </p> |
| <div class="variablelist"><table border="0" class="variablelist"> |
| <colgroup> |
| <col align="left" valign="top"> |
| <col> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td><p><span class="term">live</span></p></td> |
| <td><p> |
| Counts all live objects and dumps an overview of the number of unfreed |
| objects at program exit. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">mem-live</span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p> |
| |
| Use <code class="option">all</code> to enable all tracing flags. |
| </p> |
| <p><a name="GST_DEBUG_FILE"></a><b><code class="envar">GST_DEBUG_FILE</code>. </b> |
| 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. |
| </p> |
| <p><a name="ORC_CODE"></a><b><code class="envar">ORC_CODE</code>. </b> |
| 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. |
| </p> |
| <p><a name="G_DEBUG"></a><b><code class="envar">G_DEBUG</code>. </b> |
| 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. |
| </p> |
| <p><a name="G_SLICE"></a><b><code class="envar">G_SLICE</code>. </b> |
| 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. |
| </p> |
| <p><a name="GST_TAG_ENCODING"></a><b><code class="envar">GST_TAG_ENCODING</code>. </b> |
| 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). |
| </p> |
| <p><a name="GST_TAG_ID3_ENCODING"></a><b><code class="envar">GST_TAG_ID3_ENCODING</code>. </b> |
| 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). |
| </p> |
| <p><a name="GST_TAG_ID3V1_ENCODING"></a><b><code class="envar">GST_TAG_ID3V1_ENCODING</code>. </b> |
| Try this character encoding first for ID3v1 tag-related strings where the |
| encoding does not look like UTF-8. |
| </p> |
| <p><a name="GST_GL_WINDOW"></a><b><code class="envar">GST_GL_WINDOW</code>. </b> |
| Influences the window system to use by the GStreamer OpenGL library. |
| Common values are 'x11', 'wayland', 'win32' or 'cocoa'. |
| </p> |
| <p><a name="GST_GL_PLATFORM"></a><b><code class="envar">GST_GL_PLATFORM</code>. </b> |
| Influences the OpenGL platform to use by the GStreamer OpenGL library. |
| Common values are 'egl', 'glx', 'wgl' or 'cgl'. |
| </p> |
| <p><a name="GST_GL_API"></a><b><code class="envar">GST_GL_API</code>. </b> |
| Influences the OpenGL API requested by the OpenGL platform. |
| Common values are 'opengl' or 'gles2'. |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25</div> |
| </body> |
| </html> |