gstreamer/validate/docs/validate-usage.txt
Thibault Saunier 7e1249f089 runner: Use "18" as exit code in case of error
It is a random number, but it will in most cases give people a hint
that gst-validate reported a critical issue, and thus set the return
code, only by looking at it

Also make use of gst_validate_runner_print() in
gst-validate-transcoding.c as we were copy pasting that method there.
2013-10-05 13:36:04 -03:00

80 lines
3.4 KiB
Text

=== The GstValidate CLI Tools
The commands here assume that you have installed gst-validate. If this
is not the case, go into the gst-validate directory and call the tools
directly with the path tools/<tool-executable>
1- gst-validate-1.0: It is the simplest tool and is used to run a gst
launch style pipeline. Monitors are added to it to identify issues in the
used elements. At the end a report will be printed, this report will
contain informations about all issues that were encontered while running
gst-validate. To view issues as they are created, set the environment
variable GST_DEBUG=validate:2 and it will be printed as gstreamer
debugging. You can basically run any GstPipeline pipeline using it.
If you are not familiar with gst-launch syntax, please refer to
gst-launch's documentation.
Examples:
# Simple playback pipeline
gst-validate-1.0 playbin uri=file:///path/to/some/media/file
# Transcoding pipeline
gst-validate-1.0 filesrc location=/root/Videos/big_buck_bunny_1080p_h264.mov ! \
qtdemux name=d ! queue ! x264enc ! h264parse ! mpegtsmux name=m ! progressreport ! filesink location=/root/test.ts \
d. ! queue ! faac ! m.
You can also activate what we call "scenarios" which will execute
actions on the pipeline. Those actions can be for example, "set pipeline
to pause", "seek to N with rate=x" etc, using the following syntax:
gst-validate-1.0 playbin uri=file:///path/to/some/media/file --set-scenario=seek_forward
You can list all available scenarios using:
gst-validate-transcoding-1.0 --list-scenarios
Scenarios are XML files describing a list of actions, you can find the
source XML files in gst-validate/data/
2- gst-validate-transcoding-1.0: Transcodes input-uri to output-uri,
using the given encoding profile. The pipeline will be monitored for
possible issues detection using the gst-validate lib, at the end of
execution, a report containing informations about all found issues will
be printed.
Example:
# Will transcode file://path/to/some/media/file to H264/AAC into mp4
gst-validate-transcoding-1.0 -o 'video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=4' \
file://path/to/some/media/file file:///path/to/destination_h264_aac.qt
The same scenarios can be activated on gst-validate-transcoding-1.0 as
with gst-validate-1.0
3- gst-validate-media-check-1.0: Analizes a media file and writes the
results to stdout or a file. It can also compare the results found with
another results file for identifying regressions. The monitoring lib
from gst-validate will be enabled during the tests to identify issues
with the GStreamer elements involved with the media file's container and
codec types. It will actually do a serie of checks over the media file.
Example:
# Will check various media properties from the file
gst-validate-media-check-1.0 file://path/to/some/media/file
=== LD_PRELOAD / Testing with exiting application
If you want to test an already existing application without modifying it. Just
use:
LD_PRELOAD=path/to/libgstvalidatepreload.so yourapp ...
gst-validate will try to replace GstPipeline creating functions and configure
monitors automatically for you, reports will be printed to stderr when
they are found. You can also use GST_DEBUG to view the issues that were found
NOTS: The exit code will be "18" in case a critical issue has
been seen while running any of those tools.