mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-19 18:40:31 +00:00
validate: docs: Add some GstValidate usage documentation
+ Fix minor issues in the gst-validate and gst-validate-transcoding tools documentation
This commit is contained in:
Thibault Saunier
Thibault Saunier
parent
f7955f5249
commit
34fd5af840
8 changed files with 584 additions and 101 deletions
|
|
@ -77,7 +77,7 @@ IGNORE_CFILES = \
|
||||||
# HTML_IMAGES = gdp-header.png
|
# HTML_IMAGES = gdp-header.png
|
||||||
|
|
||||||
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
|
# 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.
|
# Other files to distribute.
|
||||||
extra_files =
|
extra_files =
|
||||||
|
|
|
||||||
292
validate/docs/validate/command-line-tools.xml
Normal file
292
validate/docs/validate/command-line-tools.xml
Normal file
|
|
@ -0,0 +1,292 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
|
<!ENTITY % version-entities SYSTEM "version.entities">
|
||||||
|
%version-entities;
|
||||||
|
]>
|
||||||
|
<refentry id="command-line-tools" revision="4 Sept 2014">
|
||||||
|
<refmeta>
|
||||||
|
<refentrytitle>GstValidate Command line tools</refentrytitle>
|
||||||
|
<manvolnum>1</manvolnum>
|
||||||
|
<refmiscinfo>GstValidate</refmiscinfo>
|
||||||
|
</refmeta>
|
||||||
|
<refnamediv>
|
||||||
|
<refname>GstValidate command line tools</refname>
|
||||||
|
<refpurpose>Documenation of the various command line tools provided by GstValidate</refpurpose>
|
||||||
|
</refnamediv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Introduction</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
<refsynopsisdiv id="command-line-tools.synopsis" role="synopsis">
|
||||||
|
<synopsis>
|
||||||
|
<link linkend="gst-validate">gst-validate</link>: The simplest gst-launch like pipeline launcher running inside GstValidate monitoring infrastructure
|
||||||
|
<link linkend="gst-validate-transcoding">gst-validate-transcoding</link>: A tool to easily create media files transcoding pipeline running inside GstValidate monitoring infrastructure
|
||||||
|
* <link linkend="gst-validate-transcoding--encoding-profile">Encoding Profile: </link>The serialization format of a GstEncodingProfile
|
||||||
|
<link linkend="gst-validate-media-check">gst-validate-media-check</link>: A tool to easily check that the discovering of a media file works properly over runs
|
||||||
|
<link linkend="gst-validate-launcher">gst-validate-launcher</link>: An application permitting to create testsuites on top of GstValidate tools
|
||||||
|
</synopsis></refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1 id="gst-validate">
|
||||||
|
<title>gst-validate-&GST_API_VERSION;</title>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
<informalexample>
|
||||||
|
Simple playback pipeline:
|
||||||
|
<programlisting>gst-validate-1.0 playbin uri=file:///path/to/some/media/file</programlisting>
|
||||||
|
|
||||||
|
Transcoding pipeline:
|
||||||
|
<programlisting>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.</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
It will report what issues happened during the execution of that pipeline in a human readable report like:
|
||||||
|
<programlisting>
|
||||||
|
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</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The return code of the process will be 18 in case a CRITICAL issue has been found
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
<refsect1 id="gst-validate-transcoding">
|
||||||
|
<title>The gst-validate-transcoding tool</title>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
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:
|
||||||
|
<programlisting>gst-validate-transcoding-&GST_API_VERSION; file:///./file.ogg file:///.../transcoded.webm -o 'video/webm:video/x-vp8:audio/x-vorbis'</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
|
||||||
|
<informalexample>
|
||||||
|
It will report what issues happened during the execution of that pipeline in a human readable report like:
|
||||||
|
<programlisting>
|
||||||
|
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</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The return code of the process will be 18 in case a CRITICAL issue has been found
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<refsect2 id="gst-validate-transcoding--encoding-profile">
|
||||||
|
<title>The Encoding profile serialization format</title>
|
||||||
|
<para>
|
||||||
|
Internally the transcoding application uses <link linkend="GstEncodeBin"><type>GstEncodeBin</type></link>. gst-validate-transcoding-&GST_API_VERSION; uses its own
|
||||||
|
serialization format to describe the <link linkend="GstEncodeBin--profile"><type>GstEncodeBin.profile</type></link>
|
||||||
|
property of the encodebin.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
The simplest serialized profile looks like:
|
||||||
|
<programlisting>muxer_source_caps:videoencoder_source_caps:audioencoder_source_caps</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
For example to encode a stream into a webm container, with a ogg audio stream and a h264 video stream,
|
||||||
|
the serialized <link linkend="GstEncodingProfile"><type>GstEncodingProfile</type></link> will look like:
|
||||||
|
<programlisting>video/webm:video/x-vp8:audio/x-vorbis</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
You can also set the preset name of the encoding profile using the caps+preset_name syntax such as in:
|
||||||
|
<programlisting>video/webm:video/x-vp8+youtube-preset:audio/x-vorbis</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
Moreover, you can set the <link linkend="gst-encoding-profile-set-presence">presence</link> property of an
|
||||||
|
encoding profile using the '|presence' synthax such as in:
|
||||||
|
<programlisting>video/webm:video/x-vp8|1:audio/x-vorbis</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
|
||||||
|
This field allows you to specify how many times maximum a GstEncodingProfile can be used inside a encodebin.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
You can also use the 'restriction_caps->encoded_format_caps' to specify the
|
||||||
|
<link linked="gst-encoding-profile-get-restriction">restriction caps</link>
|
||||||
|
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.
|
||||||
|
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
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:
|
||||||
|
<programlisting>video/webm:video/x-raw-yuv,width=1920,height=1080-->video/x-vp8:audio/x-vorbis</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<refsect3>
|
||||||
|
<title>Some serialized encoding formats examples:</title>
|
||||||
|
<informalexample>
|
||||||
|
MP3 audio and H264 in MP4:
|
||||||
|
<programlisting>video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3</programlisting>
|
||||||
|
|
||||||
|
Vorbis and theora in OGG:
|
||||||
|
<programlisting>application/ogg:video/x-theora:audio/x-vorbis</programlisting>
|
||||||
|
|
||||||
|
AC3 and H264 in MPEG-TS:
|
||||||
|
<programlisting>video/mpegts:video/x-h264:audio/x-ac3</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</refsect3>
|
||||||
|
</refsect2>
|
||||||
|
</refsect1>
|
||||||
|
<refsect1 id="gst-validate-media-check">
|
||||||
|
<title>The gst-validate-media-check tool</title>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
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:
|
||||||
|
<programlisting>gst-validate-media-check-&GST_API_VERSION; file:///./file.ogv --expected-results reference.media_info</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
That will then output found errors if any and return an exist code different from 0 if an error was found.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
<refsect1>
|
||||||
|
<para>
|
||||||
|
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
|
||||||
|
<link linkend="ScenarioFileFormat"><type>scenarios</type></link>
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
<refsect1 id="gst-validate-launcher">
|
||||||
|
<title>gst-validate-launcher</title>
|
||||||
|
<para>
|
||||||
|
To be able to implement actual testsuite based on the previously described command line tools,
|
||||||
|
a test launcher has been developed: gst-validate-launcher.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
You can find detailed informations about the launcher reading its help manual:
|
||||||
|
<programlisting>gst-validate-launcher --help</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<refsect2>
|
||||||
|
<title>Example of a testsuite implementation</title>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
In that example, we will concider that you want to write a whole new testsuite based on
|
||||||
|
your own media samples and <link linkend="ScenarioFileFormat">scenarios</link>.
|
||||||
|
That set of file and the testsuite implementation file will be structured as follow:
|
||||||
|
<synopsis>
|
||||||
|
testsuite_folder/
|
||||||
|
|-> testsuite.py
|
||||||
|
|-> sample_files/
|
||||||
|
|-> file.mp4
|
||||||
|
|-> file1.mkv
|
||||||
|
|-> file2.ogv
|
||||||
|
|-> scenarios
|
||||||
|
|-> scenario.scenario
|
||||||
|
|-> scenario1.scenario
|
||||||
|
</synopsis>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
You should generate the .media_infos files. To generate them for local files,
|
||||||
|
you can use:
|
||||||
|
<programlisting>gst-validate-launch --medias-paths /path/to/sample_files/ --generate-media-info</programlisting>
|
||||||
|
For remote streams, you should use gst-validate-media-check-&GST_API_VERSION;. For an http stream you can for example do:
|
||||||
|
<programlisting>gst-validate-media-check-&GST_API_VERSION; http://someonlinestream.com/thestream --output-file /path/to/testsuite_folder/sample_files/thestream.stream_info</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
The gst-validate-launcher will use those .media_info and .stream_info files to generate the tests as those contain the necessary informations.
|
||||||
|
<para>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Then you will need to write the testsuite.py file. You can for example implement the following testsuite:
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
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")]
|
||||||
|
)
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Once this is done, we got a testsuite that will:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
Run playbin pipelines on file.mp4, file1.mkv and file2.ogv executing "scenario" and "scenario1" scenarios
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
Transcode file.mp4, file1.mkv and file2.ogv to thearo and vorbis in OGG
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<informalexample>
|
||||||
|
The only thing to do to run the testsuite is:
|
||||||
|
<programlisting>gst-validate-launcher --config /path/to/testsuite_folder/testsuite.py</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
</refsect1>
|
||||||
|
</refentry>
|
||||||
106
validate/docs/validate/envvariables.xml
Normal file
106
validate/docs/validate/envvariables.xml
Normal file
|
|
@ -0,0 +1,106 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
|
<!ENTITY % version-entities SYSTEM "version.entities">
|
||||||
|
%version-entities;
|
||||||
|
]>
|
||||||
|
<refentry id="envvariables" revision="4 Sept 2014">
|
||||||
|
<refmeta>
|
||||||
|
<refentrytitle>GstValidate environment variables</refentrytitle>
|
||||||
|
<manvolnum>1</manvolnum>
|
||||||
|
<refmiscinfo>GstValidate</refmiscinfo>
|
||||||
|
</refmeta>
|
||||||
|
<refnamediv>
|
||||||
|
<refname>GstValidate environment variables</refname>
|
||||||
|
<refpurpose>The environment variable variable influencing the run of GstValidate</refpurpose>
|
||||||
|
</refnamediv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<para>
|
||||||
|
The runtime behaviour of GstValidate applications can be influenced by a number of environment variables.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<formalpara id="GST-VALIDATE:CAPS">
|
||||||
|
<title><envar>GST_VALIDATE</envar></title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term>fatal-criticals</term>
|
||||||
|
<listitem><para>Causes GstValidate to concider only critical issues as import enough to concider the test failed (default behaviour)</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>fatal-warnings</term>
|
||||||
|
<listitem><para>Causes GstValidate to concider warning, and critical issues as import enough to concider the test failed</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>fatal-issues</term>
|
||||||
|
<listitem><para>Causes GstValidate to concider issue, warning, and critical issues as import enough to concider the test failed</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>print-issues</term>
|
||||||
|
<listitem><para>Causes GstValidate to print issue, warning and critical issues in the final reports (default behaviour)</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>print-warnings</term>
|
||||||
|
<listitem><para>Causes GstValidate to only print warning and critical issues in the final reports</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>print-criticals</term>
|
||||||
|
<listitem><para>Causes GstValidate to only print criticals issues in the final reports</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
|
||||||
|
<formalpara id="GST-VALIDATE-FILE">
|
||||||
|
<title><envar>GST_VALIDATE_FILE</envar></title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You can use the special names "stdout" and "stderr" to use those output.
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
|
||||||
|
<formalpara id="GST-VALIDATE-SCENARIOS-PATH">
|
||||||
|
<title><envar>GST_VALIDATE_SCENARIOS_PATH</envar></title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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: <filename>.local/share/gstreamer-&GST_API_VERSION;/validate-scenario</filename>
|
||||||
|
and the system wide user data directory: <filename>/usr/lib/gstreamer-&GST_API_VERSION;/validate-scenario</filename>
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
|
||||||
|
<formalpara id="GST-VALIDATE-OVERRIDE">
|
||||||
|
<title><envar>GST_VALIDATE_OVERRIDE</envar></title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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: <filename>.local/share/gstreamer-&GST_API_VERSION;/validate-scenario</filename>
|
||||||
|
and the system wide user data directory: <filename>/usr/lib/gstreamer-&GST_API_VERSION;/validate-scenario</filename>
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
|
||||||
|
</refsect1>
|
||||||
|
</refentry>
|
||||||
|
|
@ -1,19 +1,57 @@
|
||||||
<?xml version="1.0"?>
|
<?xml version="1.0"?>
|
||||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
[
|
<!ENTITY % version-entities SYSTEM "version.entities">
|
||||||
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
%version-entities;
|
||||||
]>
|
]>
|
||||||
<book id="index">
|
|
||||||
|
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
|
||||||
<bookinfo>
|
<bookinfo>
|
||||||
<title>gst-validate Reference Manual</title>
|
<title>GstValidate Reference Manual</title>
|
||||||
<releaseinfo>
|
<releaseinfo>
|
||||||
for GstValidate &GST_API_VERSION;
|
for GstValidate &GST_API_VERSION;
|
||||||
</releaseinfo>
|
</releaseinfo>
|
||||||
</bookinfo>
|
</bookinfo>
|
||||||
|
|
||||||
<chapter>
|
<chapter>
|
||||||
<title>GstValidate documentation</title>
|
<title>Overview and usage</title>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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".
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<xi:include href="command-line-tools.xml"/>
|
||||||
|
<xi:include href="scenarios.xml"/>
|
||||||
|
<xi:include href="envvariables.xml"/>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter>
|
||||||
|
<title>API Documentation</title>
|
||||||
<xi:include href="xml/validate.xml"/>
|
<xi:include href="xml/validate.xml"/>
|
||||||
<xi:include href="xml/gst-validate-runner.xml"/>
|
<xi:include href="xml/gst-validate-runner.xml"/>
|
||||||
<xi:include href="xml/gst-validate-scenario.xml"/>
|
<xi:include href="xml/gst-validate-scenario.xml"/>
|
||||||
|
|
|
||||||
134
validate/docs/validate/scenarios.xml
Normal file
134
validate/docs/validate/scenarios.xml
Normal file
|
|
@ -0,0 +1,134 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
|
<!ENTITY % version-entities SYSTEM "version.entities">
|
||||||
|
%version-entities;
|
||||||
|
]>
|
||||||
|
|
||||||
|
<refentry id="ScenarioFileFormat">
|
||||||
|
<refmeta>
|
||||||
|
<refentrytitle role="top_of_page" id="Scenarios.top_of_page">GstValidate Scenario File Format</refentrytitle>
|
||||||
|
<manvolnum>1</manvolnum>
|
||||||
|
<refmiscinfo>
|
||||||
|
GST-VALIDATE Library
|
||||||
|
</refmiscinfo>
|
||||||
|
</refmeta>
|
||||||
|
<refnamediv>
|
||||||
|
<refname>Scenario File Format</refname>
|
||||||
|
<refpurpose>The GstValidate Scenarios file format</refpurpose>
|
||||||
|
</refnamediv>
|
||||||
|
|
||||||
|
<refsect1 id="GstValidateScenario.description" role="desc">
|
||||||
|
<title role="desc.title">Description</title>
|
||||||
|
<para>
|
||||||
|
To be able to define a list of actions to execute on a <link linkend="GstPipeline"><type>GstPipeline</type></link>, 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 <link linkend="GstStructure"><type>GstStructure</type></link> 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)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
For example to represent a seek action, you should add the following line in the '.scenario'
|
||||||
|
file.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
seek, playback_time=10.0, start=0.0, flags=accurate+flush
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
gst-validate-1.0 --list-action-types description
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So a basic scenario file that will seek three times and stop would look like:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
|
||||||
|
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
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Many action types have been implemented to help users define their own scenarios.
|
||||||
|
For example there are:
|
||||||
|
<itemizedlist><title>Action type examples:</title><listitem><para>
|
||||||
|
seek: Seeks into the stream
|
||||||
|
</para></listitem><listitem><para>
|
||||||
|
play: Set the pipeline state to GST_STATE_PLAYING
|
||||||
|
</para></listitem><listitem><para>
|
||||||
|
pause: Set the pipeline state to GST_STATE_PAUSED
|
||||||
|
</para></listitem><listitem><para>
|
||||||
|
stop: Stop the execution of the pipeline. NOTE: That action actually post a
|
||||||
|
<link linkend="GST-MESSAGE-REQUEST-STATE:CAPS"><type>GST_MESSAGE_REQUEST_STATE</type></link> (requesting <link linkend="GST-STATE-NULL:CAPS"><type>GST_STATE_NULL</type></link>) message on the bus and
|
||||||
|
the application should quit.
|
||||||
|
</para></listitem><listitem><para>
|
||||||
|
...
|
||||||
|
</para></listitem></itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
To get all the details about the registered action types, you can list them all with:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
gst-validate-1.0 --list-action-types
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
and (includes transcoding specific action types):
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
gst-validate-transcoding-1.0 --list-action-types
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Many scenarios are distributed with gst-validate, you can list them all using:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<informalexample>
|
||||||
|
<programlisting>
|
||||||
|
gst-validate-1.0 --list-scenarios
|
||||||
|
</programlisting>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
You can find more information about the implementation of GstValidateScenario and the action types <link linkend="GstValidateScenario"><type>here</type></link>
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
</refentry>
|
||||||
|
|
@ -27,95 +27,6 @@
|
||||||
* A #GstValidateScenario represents the scenario that will be executed on a #GstPipeline.
|
* 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
|
* It is basically an ordered list of #GstValidateAction that will be executed during the
|
||||||
* execution of the pipeline.
|
* 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:
|
|
||||||
* <itemizedlist><title>Action type examples:</title>
|
|
||||||
* <listitem><para>
|
|
||||||
* seek: Seeks into the stream
|
|
||||||
* </para></listitem>
|
|
||||||
* <listitem><para>
|
|
||||||
* play: Set the pipeline state to GST_STATE_PLAYING
|
|
||||||
* </para></listitem>
|
|
||||||
* <listitem><para>
|
|
||||||
* pause: Set the pipeline state to GST_STATE_PAUSED
|
|
||||||
* </para></listitem>
|
|
||||||
* <listitem><para>
|
|
||||||
* 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.
|
|
||||||
* </para></listitem>
|
|
||||||
* <listitem><para>
|
|
||||||
* ...
|
|
||||||
* </para></listitem>
|
|
||||||
* </itemizedlist>
|
|
||||||
*
|
|
||||||
* 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
|
#ifdef HAVE_CONFIG_H
|
||||||
|
|
|
||||||
|
|
@ -789,8 +789,9 @@ main (int argc, gchar ** argv)
|
||||||
"video/webm:video/x-vp8|<presence>:audio/x-vorbis\n",
|
"video/webm:video/x-vp8|<presence>:audio/x-vorbis\n",
|
||||||
"properties-values"},
|
"properties-values"},
|
||||||
{"set-scenario", '\0', 0, G_OPTION_ARG_STRING, &scenario,
|
{"set-scenario", '\0', 0, G_OPTION_ARG_STRING, &scenario,
|
||||||
"Let you set a scenario, it will override the GST_VALIDATE_SCENARIO "
|
"Let you set a scenario, it can be a full path to a scenario file"
|
||||||
"environment variable", NULL},
|
" or the name of the scenario (name of the file without the"
|
||||||
|
" '.scenario' extension).", NULL},
|
||||||
{"set-configs", '\0', 0, G_OPTION_ARG_STRING, &configs,
|
{"set-configs", '\0', 0, G_OPTION_ARG_STRING, &configs,
|
||||||
"Let you set a config scenario, the scenario needs to be set as 'config"
|
"Let you set a config scenario, the scenario needs to be set as 'config"
|
||||||
"' you can specify a list of scenario separated by ':'"
|
"' you can specify a list of scenario separated by ':'"
|
||||||
|
|
|
||||||
|
|
@ -355,8 +355,9 @@ main (int argc, gchar ** argv)
|
||||||
|
|
||||||
GOptionEntry options[] = {
|
GOptionEntry options[] = {
|
||||||
{"set-scenario", '\0', 0, G_OPTION_ARG_STRING, &scenario,
|
{"set-scenario", '\0', 0, G_OPTION_ARG_STRING, &scenario,
|
||||||
"Let you set a scenario, it will override the GST_VALIDATE_SCENARIO "
|
"Let you set a scenario, it can be a full path to a scenario file"
|
||||||
"environment variable", NULL},
|
" 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-scenarios", 'l', 0, G_OPTION_ARG_NONE, &list_scenarios,
|
||||||
"List the avalaible scenarios that can be run", NULL},
|
"List the avalaible scenarios that can be run", NULL},
|
||||||
{"scenarios-defs-output-file", '\0', 0, G_OPTION_ARG_FILENAME,
|
{"scenarios-defs-output-file", '\0', 0, G_OPTION_ARG_FILENAME,
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue