validate/docs/validate-usage.txt

   1 === The GstValidate CLI Tools
   2
   3 The commands here assume that you have installed gst-validate. If this
   4 is not the case, go into the gst-validate directory and call the tools
   5 directly with the path tools/<tool-executable>
   6
   7 1- gst-validate-1.0: It is the simplest tool and is used to run a gst
   8 launch style pipeline. Monitors are added to it to identify issues in the
   9 used elements. At the end a report will be printed, this report will
  10 contain information about all issues that were encountered while running
  11 gst-validate. To view issues as they are created, set the environment
  12 variable GST_DEBUG=validate:2 and it will be printed as gstreamer
  13 debugging. You can basically run any GstPipeline pipeline using it.
  14 If you are not familiar with gst-launch syntax, please refer to
  15 gst-launch's documentation.
  16
  17 Examples:
  18
  19     # Simple playback pipeline
  20     gst-validate-1.0 playbin uri=file:///path/to/some/media/file
  21
  22     # Transcoding pipeline
  23     gst-validate-1.0 filesrc location=/root/Videos/big_buck_bunny_1080p_h264.mov ! \
  24           qtdemux name=d ! queue ! x264enc ! h264parse ! mpegtsmux name=m ! progressreport ! filesink location=/root/test.ts \
  25           d. ! queue ! faac ! m.
  26
  27 You can also activate what we call "scenarios" which will execute
  28 actions on the pipeline. Those actions can be for example, "set pipeline
  29 to pause", "seek to N with rate=x" etc, using the following syntax:
  30
  31     gst-validate-1.0 playbin uri=file:///path/to/some/media/file --set-scenario=seek_forward
  32
  33 You can list all available scenarios using:
  34
  35     gst-validate-transcoding-1.0 --list-scenarios
  36
  37 Scenarios are simple text files describing a list of actions, you can find the
  38 source scenario files in validate/data/
  39
  40 You can find more information about scenarios on the GstValidateScenario documentation: http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-validate/html/GstValidateScenario.html
  41
  42 You can find more information about the various action types available to be executed with:
  43
  44     gst-validate-1.0 -t <optional-action-type>
  45
  46 or:
  47
  48     gst-validate-transcoding-1.0 -t <optional-action-type>
  49
  50   2- gst-validate-transcoding-1.0: Transcodes input-uri to output-uri,
  51 using the given encoding profile. The pipeline will be monitored for
  52 possible issues detection using the gst-validate lib, at the end of
  53 execution, a report containing information about all found issues will
  54 be printed.
  55
  56 Example:
  57
  58     # Will transcode file://path/to/some/media/file  to H264/AAC into mp4
  59     gst-validate-transcoding-1.0 -o 'video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=4' \
  60           file://path/to/some/media/file file:///path/to/destination_h264_aac.qt
  61
  62 The same scenarios can be activated on gst-validate-transcoding-1.0 as
  63 with gst-validate-1.0
  64
  65   3- gst-validate-media-check-1.0: Analyzes a media file and writes the
  66 results to stdout or a file. It can also compare the results found with
  67 another results file for identifying regressions. The monitoring lib
  68 from gst-validate will be enabled during the tests to identify issues
  69 with the GStreamer elements involved with the media file's container and
  70 codec types. It will actually do a series of checks over the media file.
  71
  72 Example:
  73
  74     # Will check various media properties from the file
  75     gst-validate-media-check-1.0 file://path/to/some/media/file
  76
  77 === LD_PRELOAD / Testing with exiting application
  78
  79 If you want to test an already existing application without modifying it. Just
  80 use:
  81
  82 LD_PRELOAD=path/to/libgstvalidatepreload.so yourapp ...
  83
  84 gst-validate will try to replace GstPipeline creating functions and configure
  85 monitors automatically for you, reports will be printed to stderr when
  86 they are found. You can also use GST_DEBUG to view the issues that were found
  87
  88 NOTES: The exit code will be "18" in case a critical issue has
  89 been seen while running any of those tools.
  90