docs: update and improve

Thanks to Thibault Saunier for most of the explanatory texts

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 <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

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/<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.