diff --git a/validate/README b/validate/README index b7696f1737..fe822caed2 100644 --- a/validate/README +++ b/validate/README @@ -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 , download and extract the tarball. If you +want to use latest git version, do: + +git clone + +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= +make +sudo make install (only if you want to install it) + +Replace 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 diff --git a/validate/docs/validate-usage.txt b/validate/docs/validate-usage.txt index b9bdc021ad..5dabedb331 100644 --- a/validate/docs/validate-usage.txt +++ b/validate/docs/validate-usage.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/ -== 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.