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

   1 ---
   2 short-description: Tool to test GStreamer components
   3 ...
   4
   5 # gst-validate
   6
   7 `gst-validate` is the simplest `gst-launch`-like pipeline launcher
   8 running inside GstValidate monitoring infrastructure. Monitors are added
   9 to it to identify issues in the used elements. At the end it will print
  10 a report with some information about all the issues encountered during
  11 its run. To view issues as they are detected, set the environment
  12 variable `GST_DEBUG=validate:2`{.shell} and they will get printed in the
  13 GStreamer debug log. You can basically run any [GstPipeline](GstPipeline) pipeline
  14 using this tool. If you are not familiar with `gst-launch` syntax,
  15 please refer to `gst-launch`'s documentation.
  16
  17 Simple playback pipeline:
  18
  19     gst-validate-1.0 playbin uri=file:///path/to/some/media/file
  20
  21 Transcoding pipeline:
  22
  23     gst-validate-1.0 filesrc location=/media/file/location ! qtdemux name=d ! queue \
  24             ! x264enc ! h264parse ! mpegtsmux name=m ! progressreport \
  25             ! filesink location=/root/test.ts d. ! queue ! faac ! m.
  26
  27 It will list each issue that has been encountered during the execution
  28 of the specified pipeline in a human readable report like:
  29
  30     issue : buffer is out of the segment range Detected on theoradec0.srcpad at 0:00:00.096556426
  31
  32     Details : buffer is out of segment and shouldn't be pushed. Timestamp: 0:00:25.000 - duration: 0:00:00.040 Range: 0:00:00.000 - 0:00:04.520
  33     Description : buffer being pushed is out of the current segment's start-stop  range. Meaning it is going to be discarded downstream without any use
  34
  35 The return code of the process will be 18 in case a `CRITICAL` issue has
  36 been found.
  37
  38 # Invocation
  39
  40 `gst-validate` takes a mandatory description of the pipeline to launch,
  41 similar to `gst-launch`, and some extra options.
  42
  43 ## Options
  44
  45 * `--set-scenario`: Let you set a scenario, it can be a full path to a scenario file or
  46   the name of the scenario (name of the file without the `.scenario`
  47   extension).
  48 * `-l`, `--list-scenarios`:   List the avalaible scenarios that can be run.
  49 * `--scenarios-defs-output-file`: The output file to store scenarios details. Implies
  50   `--list-scenario`.
  51 * `-t`, `--inspect-action-type`: Inspect the avalaible action types with which to write scenarios if
  52   no parameter passed, it will list all avalaible action types
  53   otherwize will print the full description of the wanted types.
  54 * `--set-media-info`: Set a media\_info XML file descriptor to share information about the
  55   media file that will be reproduced.
  56 * `--set-configs`: Let you set a config scenario. The scenario needs to be set as
  57   `config`. You can specify a list of scenarios separated by "`:`". It
  58   will override the GST\_VALIDATE\_SCENARIO environment variable.