subprojects/gst-devtools/docs/gst-validate-environment-variables.md

   1 ---
   2 title: Environment variables
   3 short-description: Environment variables influencing runtime behaviour
   4 ...
   5
   6 # GstValidate Environment Variables
   7
   8 The runtime behaviour of GstValidate applications can be influenced by a
   9 number of environment variables.
  10
  11 **GST_VALIDATE.**
  12
  13 This environment variable can be set to a list of debug options, which
  14 cause GstValidate to print out different types of test result
  15 information and consider differently the level of the reported issues.
  16
  17 * `fatal-criticals`: Causes GstValidate to consider only critical issues as import enough
  18   to consider the test failed (default behaviour)
  19 * `fatal-warnings`: Causes GstValidate to consider warning, and critical issues as
  20   import enough to consider the test failed
  21 * `fatal-issues`: Causes GstValidate to consider issue, warning, and critical issues
  22   as import enough to consider the test failed
  23 * `print-issues`: Causes GstValidate to print issue, warning and critical issues in
  24   the final reports (default behaviour)
  25 * `print-warnings`: Causes GstValidate to only print warning and critical issues in the
  26   final reports
  27 * `print-criticals`: Causes GstValidate to only print critical issues in the final
  28   reports
  29
  30 **GST_VALIDATE_FILE.**
  31
  32 Set this variable to a colon-separated list of paths to redirect all
  33 GstValidate messages to this file. If left unset, debug messages are
  34 output to standard error.
  35
  36 You can use the special names `stdout` and `stderr` to use those output.
  37
  38 **GST_VALIDATE_APPS_DIR.**
  39
  40 Set this variable to a colon separated list of paths. The validate test
  41 runner will execute all `.py` scripts found within the directories.
  42 By default GstValidate will look for test applications in the folders:
  43 * subprojects/gst-examples/webrtc/check/validate/apps
  44 * subprojects/gst-editing-services/tests/validate
  45
  46 **GST_VALIDATE_PLUGIN_PATH.**
  47
  48 Set this variable to a colon-separated list of paths. GstValidate will
  49 scan these paths for GstPlugin files and add them to the GstRegistry.
  50 By default GstValidate will look for plugins in the user data directory
  51 specified in the [XDG standard]:
  52 `.local/share/gstreamer-GST_API_VERSION/plugins` and the
  53 system wide user data directory:
  54 `/usr/lib/gstreamer-GST_API_VERSION/validate`
  55
  56 **GST_VALIDATE_SCENARIOS_PATH.**
  57
  58 Set this variable to a colon-separated list of paths. GstValidate will
  59 scan these paths for GstValidate scenario files. By default GstValidate
  60 will look for scenarios in the user data directory as specified in the
  61 [XDG standard]:
  62 `.local/share/gstreamer-GST_API_VERSION/validate/scenarios` and the
  63 system wide user data directory:
  64 `/usr/lib/gstreamer-GST_API_VERSION/validate/scenarios`
  65
  66 **GST_VALIDATE_CONFIG.**
  67
  68 Set this variable to a colon-separated list of paths to GstValidate
  69 config files or directly as a string in the GstCaps serialization
  70 format. The config file has a format similar to the scenario file. The
  71 name of the configuration corresponds to the name of the plugin the
  72 configuration applies to.
  73
  74 The special name "core" is used to configure GstValidate core
  75 functionalities (monitors, scenarios, etc...).
  76
  77 If you want to make sure to set a property on a element of a type (for
  78 example to disable QoS on all sinks) you can do:
  79
  80 ```
  81 core, action=set-property, target-element-klass=Sink
  82 ```
  83
  84 If you want the GstPipeline to get dumped when an issue of a certain
  85 level (and higher) happens, you can do:
  86
  87 ```
  88 core, action=dot-pipeline, report-level=issue
  89 ```
  90
  91 Note that you will still need to set GST_DEBUG_DUMP_DOT_DIR.
  92
  93 For more examples you can look at the ssim GstValidate plugin
  94 documentation to see how to configure that plugin.
  95
  96 You can also check that a src pad is pushing buffers at a minimum
  97 frequency. For example to check if v4l2src is producing at least 60 frames
  98 per second you can do:
  99
 100 ``` yaml
 101     core,min-buffer-frequency=60,target-element-factory-name=v4l2src
 102 ```
 103
 104 This config accepts the following fields:
 105 -   `min-buffer-frequency`: the expected minimum rate, in buffers per
 106     second, at which buffers are pushed on the pad
 107
 108 -   `target-element-{factory-name,name,klass}`: the factory-name, object
 109     name or class of the element to check
 110
 111 -   `name`: (optional) only check the frequency if the src pad has this
 112     name
 113
 114 -   `buffer-frequency-start`: (optional) if defined, validate will
 115     ignore the frequency of the pad during the time specified in this
 116     field, in ns. This can be useful when testing live pipelines where
 117     configuring and setting up elements can take some time slowing down
 118     the first buffers until the pipeline reaches its cruising speed.
 119 **GST_VALIDATE_OVERRIDE.**
 120
 121 Set this variable to a colon-separated list of dynamically linkable
 122 files that GstValidate will scan looking for overrides. By default
 123 GstValidate will look for scenarios in the user data directory as
 124 specified in the [XDG standard]:
 125 `.local/share/gstreamer-GST_API_VERSION/validate/scenarios` and the
 126 system wide user data directory:
 127 `/usr/lib/gstreamer-GST_API_VERSION/validate/scenarios`
 128
 129 **GST_VALIDATE_SCENARIO_WAIT_MULITPLIER.**
 130
 131 A decimal number to set as a multiplier for the wait actions. For
 132 example if you set `GST_VALIDATE_SCENARIO_WAIT_MULITPLIER=0.5`, for a
 133 wait action that has a duration of 2.0 the waiting time will only be of
 134 1.0 second. If set to 0, wait action will be ignored.
 135
 136 **GST_VALIDATE_REPORTING_DETAILS.**
 137
 138 The reporting level can be set through the
 139 GST_VALIDATE_REPORTING_DETAILS environment variable, as a
 140 comma-separated list of (optional) object categories / names and levels.
 141 Omit the object category / name to set the global level.
 142
 143 Examples:
 144
 145 ```
 146 GST_VALIDATE_REPORTING_DETAILS=synthetic,h264parse:all
 147 GST_VALIDATE_REPORTING_DETAILS=none,h264parse::sink_0:synthetic
 148 ```
 149
 150 Levels being:
 151
 152 * `none`: No debugging level specified or desired. Used to deactivate
 153   debugging output.
 154 * `synthetic`: Summary of the issues found, with no details.
 155 * `subchain`: If set as the default level, similar issues can be reported multiple
 156   times for different subchains. If set as the level for a particular
 157   object (`my_object:subchain`), validate will report the issues where
 158   the object is the first to report an issue for a subchain.
 159 * `monitor`: If set as the default level, all the distinct issues for all the
 160   monitors will be reported. If set as the level for a particular
 161   object, all the distinct issues for this object will be reported.
 162   Note that if the same issue happens twice on the same object, up
 163   until this level that issue is only reported once.
 164 * `all`: All the issues will be reported, even those that repeat themselves
 165   inside the same object. This can be **very** verbose if set
 166   globally.
 167
 168 Setting the reporting level allows to control the way issues are
 169 reported when calling [gst_validate_runner_printf()](gst_validate_runner_printf).
 170
 171   [XDG standard]: http://www.freedesktop.org/wiki/Software/xdg-user-dirs/