docs/gst/running.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 <!ENTITY % version-entities SYSTEM "version.entities">
   5 %version-entities;
   6 <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
   7 ]>
   8 <refentry id="gst-running" revision="08 Oct 2005">
   9 <refmeta>
  10 <refentrytitle>Running GStreamer Applications</refentrytitle>
  11 <manvolnum>3</manvolnum>
  12 <refmiscinfo>GStreamer Core</refmiscinfo>
  13 </refmeta>
  14
  15 <refnamediv>
  16 <refname>Running GStreamer Applications</refname>
  17 <refpurpose>
  18 How to run and debug your GStreamer application
  19 </refpurpose>
  20 </refnamediv>
  21
  22 <refsect1>
  23 <title>Running and debugging GStreamer Applications</title>
  24
  25 <refsect2>
  26 <title>Environment variables</title>
  27
  28 <para>
  29 GStreamer inspects a few of environment variables in addition to standard
  30 variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
  31 </para>
  32
  33 <formalpara id="GST_PLUGIN_SYSTEM_PATH">
  34   <title><envar>GST_PLUGIN_SYSTEM_PATH</envar>,
  35          <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar></title>
  36
  37   <para>
  38
  39 This environment variable can be set to a colon-separated list of paths.
  40 If this variable is not set, GStreamer will fill in this list for you
  41 with
  42 <itemizedlist>
  43   <listitem>
  44     <para>
  45 plug-ins in the user's home directory, or rather the user's "data home"
  46 directory according to the xdg base dir specification. Usually this will be
  47 a directory called
  48 <filename>plugins</filename> inside the
  49 <filename>.local/share/gstreamer-&GST_API_VERSION;</filename> directory in
  50 the user's home directory by default, though this search path may change if
  51 the XDG_DATA_HOME environment variable is set.
  52     </para>
  53   </listitem>
  54   <listitem>
  55     <para>
  56 plug-ins installed system-wide.  On this system, they are stored in
  57 <filename>&GST_PLUGINS_DIR;</filename>.
  58     </para>
  59
  60 </listitem>
  61 </itemizedlist>
  62    </para>
  63
  64     <para>
  65 GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
  66 be loaded after the plug-ins in the GST_PLUGIN_PATH variable below.
  67
  68 The paths are scanned in the given order.  This allows a user to override
  69 system-installed plug-ins with his own versions.
  70    </para>
  71   <para>
  72 The GST_PLUGIN_SYSTEM_PATH_1_0 variant is useful if both the old GStreamer 0.10
  73 version and the new GStreamer 1.0 version need to be pointed to new plugin
  74 paths. The latter will use the _1_0 variant over the non-versioned one if
  75 it is set.
  76   </para>
  77
  78     <para>
  79 Setting this variable to an empty string will cause GStreamer not to scan any
  80 system paths at all for plug-ins.  This can be useful if you're running
  81 uninstalled (for development purposes) or while running testsuites.
  82    </para>
  83
  84 </formalpara>
  85
  86 <formalpara id="GST_PLUGIN_PATH">
  87   <title><envar>GST_PLUGIN_PATH</envar>, <envar>GST_PLUGIN_PATH_1_0</envar></title>
  88
  89   <para>
  90 This environment variable can be set to a colon-separated list of paths.
  91 GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
  92 be loaded in addition to, and before, the plug-ins in the system paths.
  93   </para>
  94   <para>
  95 The GST_PLUGIN_PATH_1_0 variant is useful if both the old GStreamer 0.10
  96 version and the new GStreamer 1.0 version need to be pointed to new plugin
  97 paths. The latter will use the _1_0 variant over the non-versioned one if
  98 it is set.
  99   </para>
 100 </formalpara>
 101
 102 <formalpara id="GST_DEBUG">
 103   <title><envar>GST_DEBUG</envar></title>
 104
 105   <para>
 106 If GStreamer has been configured with <option>--enable-gst-debug=yes</option>,
 107 this variable can be set to a list of debug options, which cause GStreamer
 108 to print out different types of debugging information to stderr.
 109   </para>
 110   <para>
 111 The variable takes a comma-separated list of "category_name:level" pairs
 112 to set specific levels for the individual categories.
 113 The level value ranges from 0 (nothing) to 9 (MEMDUMP).
 114     <variablelist>
 115
 116       <varlistentry>
 117         <term>1 - <option>ERROR</option></term>
 118         <listitem>
 119 <para>
 120 Logs all fatal errors.  These are errors that do not allow the core or elements
 121 to perform the requested action.  The application can still recover if
 122 programmed to handle the conditions that triggered the error.
 123 </para>
 124         </listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term>2 - <option>WARNING</option></term>
 129         <listitem>
 130 <para>
 131 Logs all warnings.  Typically these are non-fatal, but user-visible problems
 132 are expected to happen.
 133 </para>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term>3 - <option>FIXME</option></term>
 139         <listitem>
 140 <para>
 141 Logs all fixme messages. Fixme messages are messages that indicate that something
 142 in the executed code path is not fully implemented or handled yet.  The purpose
 143 of this message is to make it easier to spot incomplete/unfinished pieces of
 144 code when reading the debug log.
 145 </para>
 146         </listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term>4 - <option>INFO</option></term>
 151         <listitem>
 152 <para>
 153 Logs all informational messages.  These are typically used for events in
 154 the system that only happen once, or are important and rare enough to be
 155 logged at this level.
 156 </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term>5 - <option>DEBUG</option></term>
 162         <listitem>
 163 <para>
 164 Logs all debug messages.  These are general debug messages for events
 165 that happen only a limited number of times during an object's lifetime;
 166 these include setup, teardown, change of parameters, ...
 167 </para>
 168         </listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term>6 - <option>LOG</option></term>
 173         <listitem>
 174 <para>
 175 Logs all log messages.  These are messages for events
 176 that happen repeatedly during an object's lifetime;
 177 these include streaming and steady-state conditions.
 178 </para>
 179         </listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term>7 - <option>TRACE</option></term>
 184         <listitem>
 185 <para>
 186 Logs all trace messages.  These messages for events
 187 that happen repeatedly during an object's lifetime such as the
 188 ref/unref cycles.
 189 </para>
 190         </listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term>9 - <option>MEMDUMP</option></term>
 195         <listitem>
 196 <para>
 197 Log all memory dump messages. Memory dump messages are used to log
 198 (small) chunks of data as memory dumps in the log. They will be displayed
 199 as hexdump with ASCII characters.
 200 </para>
 201         </listitem>
 202       </varlistentry>
 203     </variablelist>
 204
 205  The category_name can contain "<option>*"</option> as a wildcard.
 206   </para>
 207
 208   <para>
 209 For example, setting <envar>GST_DEBUG</envar> to
 210 <option>GST_AUTOPLUG:6,GST_ELEMENT_*:4</option>, will cause the
 211 <option>GST_AUTOPLUG</option> category to be logged at full
 212 <option>LOG</option> level, while all categories starting with
 213 <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
 214   </para>
 215
 216   <para>
 217 To get all possible debug output, set
 218 <envar>GST_DEBUG</envar>
 219 to <option>*:9</option>. For debugging purposes a <option>*:6</option> debug
 220 log is usually the most useful, as it contains all important information, but
 221 hides a lot of noise such as refs/unrefs. For bug reporting purposes, a
 222 <option>*:6</option> log is also what will be requested usually. It's often
 223 also worth running with <option>*:3</option> to see if there are any
 224 non-fatal errors or warnings that might be related to the problem at hand.
 225   </para>
 226
 227   <para>
 228 Since GStreamer 1.2 it is also possible to specify debug levels by name,
 229 e.g. GST_DEBUG=*:WARNING,*audio*:LOG
 230   </para>
 231
 232 </formalpara>
 233
 234 <formalpara id="GST_DEBUG_NO_COLOR">
 235   <title><envar>GST_DEBUG_NO_COLOR</envar></title>
 236
 237   <para>
 238 Set this environment variable to any value ("1" typically) to switch off
 239 colouring in GST_DEBUG output. This has the same effect as specifying the
 240 <option>--gst-debug-no-color</option> or
 241 <option>--gst-debug-color-mode</option>=off command line option to
 242 well-behaved GStreamer applications (ie. those that pass command-line
 243 options correctly to GStreamer).
 244 This is particularly useful to reduce the size of debug output and also allows
 245 for the output to be compressed much better than with colours turned on.
 246   </para>
 247   <para>
 248 Has the same effect as setting GST_DEBUG_COLOR_MODE environment variable to
 249 "off".
 250   </para>
 251
 252 </formalpara>
 253
 254 <formalpara id="GST_DEBUG_COLOR_MODE">
 255   <title><envar>GST_DEBUG_COLOR_MODE</envar></title>
 256
 257   <para>
 258 Set this environment variable to change log colouring in GST_DEBUG output.
 259 Possible values:
 260     <variablelist>
 261
 262       <varlistentry>
 263         <term><option>on</option></term>
 264         <listitem>
 265           <para>
 266 Enables debug log output coloring. Uses default coloring method for current
 267 platform. This is the default.
 268           </para>
 269         </listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><option>off</option></term>
 274         <listitem>
 275           <para>
 276 Disables debug log output coloring. This has the same effect as specifying the
 277 <option>--gst-debug-color-mode</option>=off command line option to
 278 well-behaved GStreamer applications (ie. those that pass command-line
 279 options correctly to GStreamer).
 280 This is particularly useful to reduce the size of debug output and also allows
 281 for the output to be compressed much better than with colours turned on.
 282           </para>
 283           <para>
 284 Has the same effect as setting GST_DEBUG_NO_COLOR environment variable to
 285 any value.
 286           </para>
 287         </listitem>
 288       </varlistentry>
 289
 290       <varlistentry>
 291         <term><option>auto</option></term>
 292         <listitem>
 293           <para>
 294 Same as <option>on</option>.
 295           </para>
 296         </listitem>
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term><option>disable</option></term>
 301         <listitem>
 302           <para>
 303 Same as <option>off</option>.
 304           </para>
 305         </listitem>
 306       </varlistentry>
 307
 308       <varlistentry>
 309         <term><option>unix</option></term>
 310         <listitem>
 311           <para>
 312 Enables debug log output coloring and forces the use of UNIX termial codes
 313 for coloring, even if this method is not normally used on current platform.
 314 This has the same effect as specifying the
 315 <option>--gst-debug-color-mode</option>=unix command line option to
 316 well-behaved GStreamer applications (ie. those that pass command-line options
 317 correctly to GStreamer).
 318 This is particularly useful to dump debug output into a file on non-UNIX
 319 platforms to be sent to developers who have viewers that support UNIX terminal
 320 codes.
 321           </para>
 322         </listitem>
 323       </varlistentry>
 324
 325     </variablelist>
 326   </para>
 327
 328 </formalpara>
 329
 330 <formalpara id="GST_DEBUG_OPTIONS">
 331   <title><envar>GST_DEBUG_OPTIONS</envar></title>
 332
 333   <para>
 334 This environment variable can be used to tweak the behaviour of the debugging
 335 system. Currently the only options supported are "pretty-tags" and "full-tags".
 336 In "pretty-tags" mode (the default), taglists in the debug log will be
 337 serialized so that only the first few and last few bytes of a buffer-type tag
 338 will be serialized into the log, to avoid dumping hundreds of lines of useless
 339 output into the log in case of large image tags and the like.
 340   </para>
 341
 342 </formalpara>
 343
 344 <formalpara id="GST_DEBUG_DUMP_DOT_DIR">
 345   <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title>
 346
 347   <para>
 348 Set this environment variable to a path to turn on all
 349 #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls
 350 and have the dot files in that location.
 351   </para>
 352   <para>
 353 This will only work if the application in question makes these calls in
 354 strategic places (like when the pipeline state changes or an error occurs).
 355 gst-launch-&GST_API_VERSION; is one such application.
 356   </para>
 357   <para>
 358 These .dot files can then be turned into images using the 'dot' utility
 359 from the graphviz set of tools, like this:
 360   <command>dot foo.dot -Tsvg -o foo.svg</command> or
 361   <command>dot foo.dot -Tpng -o foo.png</command> or
 362   <command>dot foo.dot -Tjpg -o foo.jpg</command>.
 363   </para>
 364   <para>
 365 There is also a utility called <command>xdot</command> which allows you to
 366 view the dot file directly without converting it first.
 367   </para>
 368
 369
 370 </formalpara>
 371
 372 <formalpara id="GST_REGISTRY">
 373   <title><envar>GST_REGISTRY</envar>, <envar>GST_REGISTRY_1_0</envar></title>
 374
 375   <para>
 376 Set this environment variable to make GStreamer use a different file for the
 377 plugin cache / registry than the default one. This is useful when operating
 378 in a separate environment which should not affect the default cache in the
 379 user's home directory.
 380   </para>
 381
 382 </formalpara>
 383
 384 <formalpara id="GST_REGISTRY_FORK">
 385   <title><envar>GST_REGISTRY_FORK</envar></title>
 386
 387   <para>
 388 Set this environment variable to "no" to prevent GStreamer from forking on
 389 startup in order to update the plugin registry. This is useful for debugging
 390 purposes, but should not be used under normal circumstances, since it means
 391 that plugins may be loaded into memory even if they are not needed by the
 392 application.
 393   </para>
 394
 395 </formalpara>
 396
 397 <formalpara id="GST_REGISTRY_UPDATE">
 398   <title><envar>GST_REGISTRY_UPDATE</envar></title>
 399
 400   <para>
 401 Set this environment variable to "no" to prevent GStreamer from updating the
 402 plugin registry. This is useful for embedded device which is not updating the
 403 plugins frequently, it will save time when doing gst_init().
 404   </para>
 405
 406 </formalpara>
 407
 408 <formalpara id="GST_TRACE">
 409   <title><envar>GST_TRACE</envar></title>
 410
 411   <para>
 412     Enable memory allocation tracing. Most GStreamer objects have support for
 413     tracing the number of unfreed objects and their memory pointers.
 414   </para>
 415   <para>
 416 The variable takes a comma-separated list of tracing options to enable.
 417     <variablelist>
 418
 419       <varlistentry>
 420         <term>live</term>
 421         <listitem>
 422 <para>
 423   Counts all live objects and dumps an overview of the number of unfreed
 424   objects at program exit.
 425 </para>
 426         </listitem>
 427       </varlistentry>
 428
 429       <varlistentry>
 430         <term>mem-live</term>
 431         <listitem>
 432 <para>
 433   Keep track of the unfreed memory pointers and dump an overview of all unfreed
 434   memory at program exit. Together with a level 9 debug log this can be used to
 435   follow the lifecycle of leaked objects in order to track down where they are
 436   leaked. This can be useful for debugging memory leaks in situations where
 437   tools such as valgrind are not available, or not an option.
 438 </para>
 439         </listitem>
 440       </varlistentry>
 441     </variablelist>
 442
 443  Use <option>all</option> to enable all tracing flags.
 444   </para>
 445 </formalpara>
 446
 447 <formalpara id="GST_DEBUG_FILE">
 448   <title><envar>GST_DEBUG_FILE</envar></title>
 449
 450   <para>
 451   Set this variable to a file path to redirect all GStreamer debug
 452   messages to this file. If left unset, debug messages with be output
 453   unto the standard error.
 454   </para>
 455
 456 </formalpara>
 457
 458 <formalpara id="ORC_CODE">
 459   <title><envar>ORC_CODE</envar></title>
 460
 461   <para>
 462 Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
 463 such as gdb to create useful backtraces from Orc-generated code.  Set
 464 ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
 465 generator is producing incorrect code (Quite a few important
 466 GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
 467 One can also combine flags like ORC_CODE=backup,debug.
 468   </para>
 469
 470 </formalpara>
 471
 472 <formalpara id="G_DEBUG">
 473   <title><envar>G_DEBUG</envar></title>
 474
 475   <para>
 476 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
 477 GStreamer programs abort when a critical warning such as an assertion failure
 478 occurs. This is useful if you want to find out which part of the code caused
 479 that warning to be triggered and under what circumstances. Simply set G_DEBUG
 480 as mentioned above and run the program in gdb (or let it core dump). Then get
 481 a stack trace in the usual way.
 482   </para>
 483
 484 </formalpara>
 485
 486 <formalpara id="G_SLICE">
 487   <title><envar>G_SLICE</envar></title>
 488
 489   <para>
 490 Useful GLib environment variable. Set G_SLICE=always-malloc when running
 491 GStreamer programs in valgrind, or debugging memory leaks with other tools.
 492 See the GLib API reference for more details.
 493   </para>
 494
 495 </formalpara>
 496
 497 <formalpara id="GST_TAG_ENCODING">
 498   <title><envar>GST_TAG_ENCODING</envar></title>
 499   <para>
 500 Try this character encoding first for tag-related strings where the encoding
 501 is not defined and which are not UTF-8 already. By default the current locale
 502 will be tried (if not UTF-8).
 503   </para>
 504 </formalpara>
 505
 506 <formalpara id="GST_TAG_ID3_ENCODING">
 507   <title><envar>GST_TAG_ID3_ENCODING</envar></title>
 508   <para>
 509 Try this character encoding first for ID3 tag-related strings where the
 510 encoding is not defined and which are not UTF-8 already. By default the current
 511 locale will be tried (if not UTF-8).
 512   </para>
 513 </formalpara>
 514
 515 <formalpara id="GST_TAG_ID3V1_ENCODING">
 516   <title><envar>GST_TAG_ID3V1_ENCODING</envar></title>
 517   <para>
 518 Try this character encoding first for ID3v1 tag-related strings where the
 519 encoding does not look like UTF-8.
 520   </para>
 521 </formalpara>
 522
 523 <formalpara id="GST_GL_WINDOW">
 524   <title><envar>GST_GL_WINDOW</envar></title>
 525   <para>
 526 Influences the window system to use by the GStreamer OpenGL library.
 527 Common values are 'x11', 'wayland', 'win32' or 'cocoa'.
 528   </para>
 529 </formalpara>
 530
 531 <formalpara id="GST_GL_PLATFORM">
 532   <title><envar>GST_GL_PLATFORM</envar></title>
 533   <para>
 534 Influences the OpenGL platform to use by the GStreamer OpenGL library.
 535 Common values are 'egl', 'glx', 'wgl' or 'cgl'.
 536   </para>
 537 </formalpara>
 538
 539 <formalpara id="GST_GL_API">
 540   <title><envar>GST_GL_API</envar></title>
 541   <para>
 542 Influences the OpenGL API requested by the OpenGL platform.
 543 Common values are 'opengl' or 'gles2'.
 544   </para>
 545 </formalpara>
 546
 547 </refsect2>
 548
 549 </refsect1>
 550
 551 </refentry>