mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-10-02 08:42:32 +00:00
docs: update and improve
Thanks to Thibault Saunier for most of the explanatory texts
This commit is contained in:
Thiago Santos
parent
2e216818bd
commit
7154f280b5
2 changed files with 113 additions and 23 deletions
|
|
@ -1,2 +1,48 @@
|
|||
== Gst-Validate
|
||||
|
||||
The goal of GstValidate is to be able to detect when elements are not
|
||||
behaving as expected and report it to the user so he knows how things
|
||||
are supposed to work inside a GstPipeline. In the end, fixing issues
|
||||
found by the tool will ensure that all elements behave all together in
|
||||
the expected way.
|
||||
|
||||
The easiest way of using GstValidate is to use one of its command-line
|
||||
tools, located at tools/ directory. It is also possible to monitor
|
||||
GstPipelines from any application by using the LD_PRELOAD gstvalidate
|
||||
lib. The third way of using it is to write your own application that
|
||||
links and uses libgstvalidate.
|
||||
|
||||
== BUILDING
|
||||
|
||||
Getting the code:
|
||||
|
||||
Releases are available at <URL>, download and extract the tarball. If you
|
||||
want to use latest git version, do:
|
||||
|
||||
git clone <URI>
|
||||
|
||||
After cloning or extracting from a tarball, enter the gst-validate directory:
|
||||
|
||||
cd gst-validate
|
||||
|
||||
The 'master' branch uses gstreamer 1.0, there is a '0.10' branch for
|
||||
gstreamer 0.10. The default is the 'master' branch, if you want to use it
|
||||
for 0.10, do:
|
||||
|
||||
git checkout --track origin/0.10
|
||||
|
||||
Build with:
|
||||
|
||||
./autogen.sh --prefix=<installation-prefix>
|
||||
make
|
||||
sudo make install (only if you want to install it)
|
||||
|
||||
Replace <installation-prefix> with your desired installation path, you can omit
|
||||
the --prefix argument if you aren't going to install it or if you want the
|
||||
default /usr/local. It is possible to use gst-validate CLI tools without
|
||||
installation.
|
||||
|
||||
== INSTRUCTIONS
|
||||
|
||||
If you are looking for informations on how to use gst-validate -> docs/validate-usage.txt
|
||||
If you are looking for informations on gst-validate design -> docs/validate-design.txt
|
||||
|
|
|
|||
|
|
@ -1,34 +1,78 @@
|
|||
=== Testing with monitors
|
||||
=== The GstValidate CLI Tools
|
||||
|
||||
Using gst-validate monitors is quite simple, there are 2 ways to test your
|
||||
pipeline/element.
|
||||
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>
|
||||
|
||||
== Creating the monitors yourself
|
||||
This method requires writing a specific application (or modifying yours) to
|
||||
add GstValidateMonitors and GstValidateRunner to it. Create a GstValidateRunner
|
||||
with gst_validate_runner_new, then use gst_validate_monitor_factory_create to
|
||||
create monitors for your pipeline.
|
||||
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.
|
||||
|
||||
Now all you have to do is use your pipeline as usual, the reports will be
|
||||
created and posted to the runner. You can list them after the pipeline
|
||||
finishes to look at the issues found.
|
||||
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
|
||||
|
||||
== Using LD_PRELOAD and an existing 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 already
|
||||
configure runners and monitors for you, reports will be printed to stderr when
|
||||
they are found.
|
||||
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
|
||||
|
||||
|
||||
=== Using the file checker
|
||||
The GstValidateFileChecker is a convenient API to compare a media file
|
||||
properties with its expected properties. The uri of the file to be tested and
|
||||
the expected values can be configured via gobject properties.
|
||||
gst_validate_file_checker_run is used to start the tests.
|
||||
|
||||
There is also a convenience tool (gst-validate-file-check) that can be used to
|
||||
run the file checker.
|
||||
|
|
|
|||
Loading…
Reference in a new issue