From 34fd5af840c6df93ec6c0daf0d1b3da214148388 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Thu, 4 Sep 2014 23:54:34 +0200 Subject: [PATCH] validate: docs: Add some GstValidate usage documentation + Fix minor issues in the gst-validate and gst-validate-transcoding tools documentation --- validate/docs/validate/Makefile.am | 2 +- validate/docs/validate/command-line-tools.xml | 292 ++++++++++++++++++ validate/docs/validate/envvariables.xml | 106 +++++++ validate/docs/validate/gst-validate-docs.sgml | 52 +++- validate/docs/validate/scenarios.xml | 134 ++++++++ validate/gst/validate/gst-validate-scenario.c | 89 ------ validate/tools/gst-validate-transcoding.c | 5 +- validate/tools/gst-validate.c | 5 +- 8 files changed, 584 insertions(+), 101 deletions(-) create mode 100644 validate/docs/validate/command-line-tools.xml create mode 100644 validate/docs/validate/envvariables.xml create mode 100644 validate/docs/validate/scenarios.xml diff --git a/validate/docs/validate/Makefile.am b/validate/docs/validate/Makefile.am index 8659f7603d..ee4796bf92 100644 --- a/validate/docs/validate/Makefile.am +++ b/validate/docs/validate/Makefile.am @@ -77,7 +77,7 @@ IGNORE_CFILES = \ # HTML_IMAGES = gdp-header.png # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). -content_files = +content_files = scenarios.xml command-line-tools.xml envvariables.xml # Other files to distribute. extra_files = diff --git a/validate/docs/validate/command-line-tools.xml b/validate/docs/validate/command-line-tools.xml new file mode 100644 index 0000000000..1b7812564d --- /dev/null +++ b/validate/docs/validate/command-line-tools.xml @@ -0,0 +1,292 @@ + + +%version-entities; +]> + + + GstValidate Command line tools + 1 + GstValidate + + + GstValidate command line tools + Documenation of the various command line tools provided by GstValidate + + + + Introduction + + + In order to make gst-validate usage simple, dedicated tools that allow plugin developers test there elements in many use cases from a high level perspective + are provided with GstValidate. + + + + + gst-validate: The simplest gst-launch like pipeline launcher running inside GstValidate monitoring infrastructure + gst-validate-transcoding: A tool to easily create media files transcoding pipeline running inside GstValidate monitoring infrastructure + * Encoding Profile: The serialization format of a GstEncodingProfile + gst-validate-media-check: A tool to easily check that the discovering of a media file works properly over runs + gst-validate-launcher: An application permitting to create testsuites on top of GstValidate tools + + + + gst-validate-&GST_API_VERSION; + + 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. + + Simple playback pipeline: + gst-validate-1.0 playbin uri=file:///path/to/some/media/file + + Transcoding pipeline: + gst-validate-1.0 filesrc location=/media/file/location ! qtdemux name=d ! queue ! x264enc ! h264parse ! mpegtsmux name=m ! progressreport ! filesink location=/root/test.ts d. ! queue ! faac ! m. + + + + + It will report what issues happened during the execution of that pipeline in a human readable report like: + + issue : buffer is out of the segment range Detected on theoradec0.srcpad at 0:00:00.096556426 + + Details : buffer is out of segment and shouldn't be pushed. Timestamp: 0:00:25.000 - duration: 0:00:00.040 Range: 0:00:00.000 - 0:00:04.520 + Description : buffer being pushed is out of the current segment's start-stop range. Meaning it is going to be discarded downstream without any use + + + + The return code of the process will be 18 in case a CRITICAL issue has been found + + + + The gst-validate-transcoding tool + + + A command line tool allowing to test media files transcoding with a straight forward syntax. You can for example transcode any media file to vorbis vp8 in webm doing: + gst-validate-transcoding-&GST_API_VERSION; file:///./file.ogg file:///.../transcoded.webm -o 'video/webm:video/x-vp8:audio/x-vorbis' + + + + + + + It will report what issues happened during the execution of that pipeline in a human readable report like: + + issue : buffer is out of the segment range Detected on theoradec0.srcpad at 0:00:00.096556426 + + Details : buffer is out of segment and shouldn't be pushed. Timestamp: 0:00:25.000 - duration: 0:00:00.040 Range: 0:00:00.000 - 0:00:04.520 + Description : buffer being pushed is out of the current segment's start-stop range. Meaning it is going to be discarded downstream without any use + + + + The return code of the process will be 18 in case a CRITICAL issue has been found + + + + The Encoding profile serialization format + + Internally the transcoding application uses GstEncodeBin. gst-validate-transcoding-&GST_API_VERSION; uses its own + serialization format to describe the GstEncodeBin.profile + property of the encodebin. + + + + + The simplest serialized profile looks like: + muxer_source_caps:videoencoder_source_caps:audioencoder_source_caps + + + + + + For example to encode a stream into a webm container, with a ogg audio stream and a h264 video stream, + the serialized GstEncodingProfile will look like: + video/webm:video/x-vp8:audio/x-vorbis + + + + + + You can also set the preset name of the encoding profile using the caps+preset_name syntax such as in: + video/webm:video/x-vp8+youtube-preset:audio/x-vorbis + + + + + + Moreover, you can set the presence property of an + encoding profile using the '|presence' synthax such as in: + video/webm:video/x-vp8|1:audio/x-vorbis + + + This field allows you to specify how many times maximum a GstEncodingProfile can be used inside a encodebin. + + + You can also use the 'restriction_caps->encoded_format_caps' to specify the + restriction caps + to be set on a GstEncodingProfile. It corresponds to the restriction GstCaps to apply before + the encoder that will be used in the profile. The fields present in restriction + caps are properties of the raw stream (that is before encoding), such as height + and width for video and depth and sampling rate for audio. This property does not + make sense for muxers. + + + + + To force to encode a video in full HD (using webm as a container, + vp8 as a video codec and vorbis as an audio codec), you should use: + video/webm:video/x-raw-yuv,width=1920,height=1080-->video/x-vp8:audio/x-vorbis + + + + Some serialized encoding formats examples: + + MP3 audio and H264 in MP4: + video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3 + + Vorbis and theora in OGG: + application/ogg:video/x-theora:audio/x-vorbis + + AC3 and H264 in MPEG-TS: + video/mpegts:video/x-h264:audio/x-ac3 + + + + + + The gst-validate-media-check tool + + + A command line tool checking that media files discovering works properly with gst-discoverer. Basically it + needs a reference text file containing valid information about a media file (which can be generated with the same tool) + and then it will be able to check that those informations correspond to what is reported by gst-discoverer over new runs. + For example, given that we have a valid reference.media_info file, we can run: + gst-validate-media-check-&GST_API_VERSION; file:///./file.ogv --expected-results reference.media_info + + + + That will then output found errors if any and return an exist code different from 0 if an error was found. + + + + + As you can notice, those tools let us test static pipelines execution and not that the pipeline reacts properly during execution of actions from the end user such as seeking, or changing the pipeline state, etc… In order to make that possible and easy to use we introduced the concept of + scenarios + + + + gst-validate-launcher + + To be able to implement actual testsuite based on the previously described command line tools, + a test launcher has been developed: gst-validate-launcher. + + + + You can find detailed informations about the launcher reading its help manual: + gst-validate-launcher --help + + + + Example of a testsuite implementation + + To implement a testsuite, you will have to write some simple python code that will define + the test to be launched by the gst-validate-launcher. + + + In that example, we will concider that you want to write a whole new testsuite based on + your own media samples and scenarios. + That set of file and the testsuite implementation file will be structured as follow: + +testsuite_folder/ + |-> testsuite.py + |-> sample_files/ + |-> file.mp4 + |-> file1.mkv + |-> file2.ogv + |-> scenarios + |-> scenario.scenario + |-> scenario1.scenario + + + + + You should generate the .media_infos files. To generate them for local files, + you can use: + gst-validate-launch --medias-paths /path/to/sample_files/ --generate-media-info + For remote streams, you should use gst-validate-media-check-&GST_API_VERSION;. For an http stream you can for example do: + gst-validate-media-check-&GST_API_VERSION; http://someonlinestream.com/thestream --output-file /path/to/testsuite_folder/sample_files/thestream.stream_info + + + The gst-validate-launcher will use those .media_info and .stream_info files to generate the tests as those contain the necessary informations. + + + + Then you will need to write the testsuite.py file. You can for example implement the following testsuite: + + +import os + +# Make sure gst-validate-launcher uses our special media files +options.paths = os.path.dirname(os.path.realpath(__file__)) + +# Make sure GstValidate will be able to use our special scenarios +# from the testsuite_folder/scenarios folder +os.environ["GST_VALIDATE_SCENARIOS_PATH"] = \ + os.path.join(os.path.dirname(os.path.realpath(__file__)), "scenarios") + +# You can activate the following if you care only about the critical issues in +# the report: +# os.environ["GST_VALIDATE"] = "print_criticals" + +# Make gst-validate use our scenarios +validate.add_scenarios(["scenario", "scenario1"]) + + +# Now add the thearo and vorbis in OGG as a wanted transcoding format. That means +# that tests with all the media files/streams will be converted to that format. +validate.add_encoding_formats([MediaFormatCombination("ogg", "vorbis", "theora")]) + +# Use the GstValidatePlaybinTestsGenerator to generate tests that will use playbin +# and GstValidateTranscodingTestsGenerator to create media transcoding tests that +# will use all the media format added with validate.add_encoding_formats +validate.add_generators([validate.GstValidatePlaybinTestsGenerator(validate), + GstValidateTranscodingTestsGenerator(self)]) + +# Blacklist some test that are known to fail because a feature is not supported +# or any reason. +# The tuple defining those tests is of the form: +# ("regex defining the test name", "Reason why the test should be disabled") +validate.set_default_blacklist([ + ("validate.*.scenario1.*ogv$" + "oggdemux does not support some action executed in scenario1")] + ) + + + + + + Once this is done, we got a testsuite that will: + + + Run playbin pipelines on file.mp4, file1.mkv and file2.ogv executing "scenario" and "scenario1" scenarios + + + Transcode file.mp4, file1.mkv and file2.ogv to thearo and vorbis in OGG + + + + The only thing to do to run the testsuite is: + gst-validate-launcher --config /path/to/testsuite_folder/testsuite.py + + + + + diff --git a/validate/docs/validate/envvariables.xml b/validate/docs/validate/envvariables.xml new file mode 100644 index 0000000000..dd9c76b6db --- /dev/null +++ b/validate/docs/validate/envvariables.xml @@ -0,0 +1,106 @@ + + +%version-entities; +]> + + + GstValidate environment variables + 1 + GstValidate + + + GstValidate environment variables + The environment variable variable influencing the run of GstValidate + + + + + The runtime behaviour of GstValidate applications can be influenced by a number of environment variables. + + + + <envar>GST_VALIDATE</envar> + + + This environment variable can be set to a list of debug options, + which cause GstValidate to print out different types of test result informations + and concider differently the level of the reported issues. + + + fatal-criticals + Causes GstValidate to concider only critical issues as import enough to concider the test failed (default behaviour) + + + + fatal-warnings + Causes GstValidate to concider warning, and critical issues as import enough to concider the test failed + + + + fatal-issues + Causes GstValidate to concider issue, warning, and critical issues as import enough to concider the test failed + + + + print-issues + Causes GstValidate to print issue, warning and critical issues in the final reports (default behaviour) + + + + print-warnings + Causes GstValidate to only print warning and critical issues in the final reports + + + + print-criticals + Causes GstValidate to only print criticals issues in the final reports + + + + + + + + <envar>GST_VALIDATE_FILE</envar> + + + Set this variable to a to a colon-separated list of paths to redirect all + GstValidate messages to this file. If left unset, debug messages will be + outputed into the standard error. + + + + You can use the special names "stdout" and "stderr" to use those output. + + + + + <envar>GST_VALIDATE_SCENARIOS_PATH</envar> + + + Set this variable to a to a colon-separated list of paths. GstValidate will + scan these paths for GstValidate scenario files. + + By default GstValidate will look for scenarios in the user data directory as + specified in the XDG standard: .local/share/gstreamer-&GST_API_VERSION;/validate-scenario + and the system wide user data directory: /usr/lib/gstreamer-&GST_API_VERSION;/validate-scenario + + + + + <envar>GST_VALIDATE_OVERRIDE</envar> + + + Set this variable to a to a colon-separated list of dynamically linkable files. GstValidate will + scan these paths for GstValidate overrides + + By default GstValidate will look for scenarios in the user data directory as + specified in the XDG standard: .local/share/gstreamer-&GST_API_VERSION;/validate-scenario + and the system wide user data directory: /usr/lib/gstreamer-&GST_API_VERSION;/validate-scenario + + + + + diff --git a/validate/docs/validate/gst-validate-docs.sgml b/validate/docs/validate/gst-validate-docs.sgml index da40722ab8..9ca3b06d7b 100644 --- a/validate/docs/validate/gst-validate-docs.sgml +++ b/validate/docs/validate/gst-validate-docs.sgml @@ -1,19 +1,57 @@ - + +%version-entities; ]> - + + - gst-validate Reference Manual + GstValidate Reference Manual for GstValidate &GST_API_VERSION; - GstValidate documentation + Overview and usage + + GstValidate is a tool that allows GStreamer developers to check + that the GstElements they write behave the way they are supposed to. + It was first started to provide plug-ins developers with a tool to + check that they use the framework the proper way. + + + + GstValidate implements a monitoring logic that allows the system to check + that the elements of a GstPipeline respect some rules GStreamer components + have to follow so that elements can properly interact together. + For example, a GstValidatePadMonitor will make sure that if we receive a GstSegment + from upstream, an equivalent segment is sent downstream before any buffer gets out. + + + Then GstValidate implements a reporting system that allows users to + get detailed informations about what was not properly handle in elements. + The reports are order by level of importance from "issue" to "critical". + + + Some tools have been implemented to help the developer validate and test + their GstElement, you can have a look at the command line tools section to find more information + + + On top of those tools, the notion of + scenario has been implemented so that developers can easily execute a set + of actions on pipelines and thus test real world interactive cases and reproduce existing + issues in a convenient way. + + + + + + + + + API Documentation diff --git a/validate/docs/validate/scenarios.xml b/validate/docs/validate/scenarios.xml new file mode 100644 index 0000000000..b363534feb --- /dev/null +++ b/validate/docs/validate/scenarios.xml @@ -0,0 +1,134 @@ + + +%version-entities; +]> + + + + GstValidate Scenario File Format + 1 + + GST-VALIDATE Library + + + + Scenario File Format + The GstValidate Scenarios file format + + + + Description + + To be able to define a list of actions to execute on a GstPipeline, a dedicated file format is used. + The name of the scenario is the name of the file without its '.scenario' extension. + The scenario file file format is based on the GstStructure serialized format which is a basic, type aware, + key value format. + It takes the type of the action as first coma separeted field, and then + the key values pair of the form 'parameter=value' separated by comas. The values + type will be guessed if not casted as in 'parameter=(string)value'. You can force the type + guessing system to actually know what type you want by giving it the right hints. For example + to make sure the value is a double, you should add a decimal (ie '1' will be concidered as a + int, but '1.0' will be concidered as a double and '"1.0"' will be concidered as a string) + + + For example to represent a seek action, you should add the following line in the '.scenario' + file. + + + + + seek, playback_time=10.0, start=0.0, flags=accurate+flush + + + + + The files to be used as scenario should have a '.scenario' extension and + should be placed either in $USER_DATA_DIR/gstreamer-1.0/validate-scenario , + $GST_DATADIR/gstreamer-1.0/validate-scenario or in a path defined in the + $GST_VALIDATE_SCENARIOS_PATH environment variable. + + + Each line in the '.scenario' file represent an action (you can also use \ at the end of a line + write a single action on multiple lines). Usually you should start you scenario with a 'description' + "config" action in order for the user to have more information about the scenario. It can contain + a 'summary' field which is a string explaning what the scenario does and then several info fields + about the scenario. You can find more info about it running: + + + + + gst-validate-1.0 --list-action-types description + + + + + So a basic scenario file that will seek three times and stop would look like: + + + + + + description, summary="Seeks at 1.0 to 2.0 then at \ + 3.0 to 0.0 and then seeks at \ + 1.0 to 2.0 for 1.0 second (between 2.0 and 3.0).", \ + seek=true, duration=5.0, min-media-duration=4.0 + seek, playback_time=1.0, rate=1.0, start=2.0, flags=accurate+flush + seek, playback_time=3.0, rate=1.0, start=0.0, flags=accurate+flush + seek, playback_time=1.0, rate=1.0, start=2.0, stop=3.0, flags=accurate+flush + + + + + Many action types have been implemented to help users define their own scenarios. + For example there are: + Action type examples: + seek: Seeks into the stream + + play: Set the pipeline state to GST_STATE_PLAYING + + pause: Set the pipeline state to GST_STATE_PAUSED + + stop: Stop the execution of the pipeline. NOTE: That action actually post a + GST_MESSAGE_REQUEST_STATE (requesting GST_STATE_NULL) message on the bus and + the application should quit. + + ... + + + + To get all the details about the registered action types, you can list them all with: + + + + + gst-validate-1.0 --list-action-types + + + + + and (includes transcoding specific action types): + + + + + gst-validate-transcoding-1.0 --list-action-types + + + + + Many scenarios are distributed with gst-validate, you can list them all using: + + + + + gst-validate-1.0 --list-scenarios + + + + + You can find more information about the implementation of GstValidateScenario and the action types here + + + diff --git a/validate/gst/validate/gst-validate-scenario.c b/validate/gst/validate/gst-validate-scenario.c index 58617b263c..c0940bbdb9 100644 --- a/validate/gst/validate/gst-validate-scenario.c +++ b/validate/gst/validate/gst-validate-scenario.c @@ -27,95 +27,6 @@ * A #GstValidateScenario represents the scenario that will be executed on a #GstPipeline. * It is basically an ordered list of #GstValidateAction that will be executed during the * execution of the pipeline. - * - * To be able to simply define that list of actions, a dedicated file format is used. This - * file format is based on the #GstStructure serialized format which is a basic, type aware, - * key value format. It takes the type of the action as first coma separeted field, and then - * the key values pair of the form 'parameter=value' are separated by comas. The values - * type will be guessed if not casted as in 'parameter=(string)value'. You can force the type - * guessing system to actually know what type you want by giving it the right hints. For example - * to make sure the value is a double, you should add a decimal (ie '1' will be concidered as a - * int, but '1.0' will be concidered as a double and '"1.0"' will be concidered as a string) - * - * For example to represent a seek action, you should add the following line in the '.scenario' - * file. - * - * |[ - * seek, playback_time=10.0, start=0.0, flags=accurate+flush - * ]| - * - * - * The files to be used as scenario should have a '.scenario' extension and - * should be placed either in $USER_DATA_DIR/gstreamer-1.0/validate-scenario , - * $GST_DATADIR/gstreamer-1.0/validate-scenario or in a path defined in the - * $GST_VALIDATE_SCENARIOS_PATH environment variable. - * - * Each line in the '.scenario' file represent an action (you can also use \ at the end of a line - * write a single action on multiple lines). Usually you should start you scenario with a 'description' - * "config" action in order for the user to have more information about the scenario. It can contain - * a 'summary' field which is a string explaning what the scenario does and then several info fields - * about the scenario. You can find more info about it running: - * - * |[ - * gst-validate-1.0 --list-action-types description - * ]| - * - * So a basic scenario file that will seek three times and stop would look like: - * - * |[ - * - * description, summary="Seeks at 1.0 to 2.0 then at \ - * 3.0 to 0.0 and then seeks at \ - * 1.0 to 2.0 for 1.0 second (between 2.0 and 3.0).", \ - * seek=true, duration=5.0, min-media-duration=4.0 - * seek, playback_time=1.0, rate=1.0, start=2.0, flags=accurate+flush - * seek, playback_time=3.0, rate=1.0, start=0.0, flags=accurate+flush - * seek, playback_time=1.0, rate=1.0, start=2.0, stop=3.0, flags=accurate+flush - * ]| - * - * Many action types have been implemented to help users define their own scenarios. - * For example there are: - * Action type examples: - * - * seek: Seeks into the stream - * - * - * play: Set the pipeline state to GST_STATE_PLAYING - * - * - * pause: Set the pipeline state to GST_STATE_PAUSED - * - * - * stop: Stop the execution of the pipeline. NOTE: That action actually post a - * #GST_MESSAGE_REQUEST_STATE (requesting #GST_STATE_NULL) message on the bus and - * the application should quit. - * - * - * ... - * - * - * - * To get all the details about the registered action types, you can list them all with: - * - * |[ - * gst-validate-1.0 --list-action-types - * ]| - * - * and (includes transcoding specific action types): - * - * |[ - * gst-validate-transcoding-1.0 --list-action-types - * ]| - * - * You can also register new types yourself thanks to #gst_validate_add_action_type. And you will be able - * to print the action types details thanks to the #gst_validate_print_action_types function in your own - * tool. - * - * Many scenarios are distributed with gst-validate, you can list them all using: - * - * |[ - * gst-validate-1.0 --list-scenarios - * ]| */ #ifdef HAVE_CONFIG_H diff --git a/validate/tools/gst-validate-transcoding.c b/validate/tools/gst-validate-transcoding.c index c4d4f36cb1..9b1abc288e 100644 --- a/validate/tools/gst-validate-transcoding.c +++ b/validate/tools/gst-validate-transcoding.c @@ -789,8 +789,9 @@ main (int argc, gchar ** argv) "video/webm:video/x-vp8|:audio/x-vorbis\n", "properties-values"}, {"set-scenario", '\0', 0, G_OPTION_ARG_STRING, &scenario, - "Let you set a scenario, it will override the GST_VALIDATE_SCENARIO " - "environment variable", NULL}, + "Let you set a scenario, it can be a full path to a scenario file" + " or the name of the scenario (name of the file without the" + " '.scenario' extension).", NULL}, {"set-configs", '\0', 0, G_OPTION_ARG_STRING, &configs, "Let you set a config scenario, the scenario needs to be set as 'config" "' you can specify a list of scenario separated by ':'" diff --git a/validate/tools/gst-validate.c b/validate/tools/gst-validate.c index e642eec397..99c02c86c8 100644 --- a/validate/tools/gst-validate.c +++ b/validate/tools/gst-validate.c @@ -355,8 +355,9 @@ main (int argc, gchar ** argv) GOptionEntry options[] = { {"set-scenario", '\0', 0, G_OPTION_ARG_STRING, &scenario, - "Let you set a scenario, it will override the GST_VALIDATE_SCENARIO " - "environment variable", NULL}, + "Let you set a scenario, it can be a full path to a scenario file" + " or the name of the scenario (name of the file without the" + " '.scenario' extension).", NULL}, {"list-scenarios", 'l', 0, G_OPTION_ARG_NONE, &list_scenarios, "List the avalaible scenarios that can be run", NULL}, {"scenarios-defs-output-file", '\0', 0, G_OPTION_ARG_FILENAME,