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