mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-02-18 20:25:25 +00:00
Code Issues 1 Projects Releases Wiki Activity

validate: Reshape documentation

Browse source 
Fix some errors, use more Docbook tags and split each command reference
in its own file.

https://bugzilla.gnome.org/show_bug.cgi?id=749162
This commit is contained in:
Emanuele Aina 2015-05-09 16:28:20 +02:00 committed by Thibault Saunier
parent 1286989c31
commit 2c3d0c9eab
9 changed files with 812 additions and 483 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
validate/docs/validate/Makefile.am
View file

@ -77,7 +77,7 @@ IGNORE_CFILES = \
# HTML_IMAGES = gdp-header.png
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
content_files = scenarios.xml command-line-tools.xml envvariables.xml
content_files = gst-validate.xml gst-validate-transcoding.xml gst-validate-media-check.xml gst-validate-launcher.xml envvariables.xml scenarios.xml
# Other files to distribute.
extra_files =

316
validate/docs/validate/command-line-tools.xml
View file

@ -1,316 +0,0 @@
<?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>Documentation 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
* <link linkend="gst-validate-launcher--default-testsuite">The default testsuite </link>The default GstValidate testsuite
* <link linkend="gst-validate-launcher--implement-testsuite">Implementing a testsuite </link>How to implement a testsuite
</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 information about all issues that were encountered 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' syntax 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 information 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 information about the launcher reading its help manual:
<programlisting>gst-validate-launcher --help</programlisting>
</informalexample>
</para>
<refsect2 id="gst-validate-launcher--default-testsuite">
<title>Run the GstValidate default testsuite</title>
<para>
GstValidate comes with a default testsuite to be executed on a default set of media samples.
Those media samples are stored with git-annex so you will need it to be able to launch that
default testsuite.
</para>
<informalexample>
The first time you launch the testsuite, you will need to make sure that the media samples are
downloaded. To do so and launch the testsuite you can simply do:
<programlisting>gst-validate-launcher validate --sync</programlisting>
</informalexample>
<para>
This will only launch the GstValidate tests and not other application that might be supported
(currently ges-launch is also supported and has its own default testsuite).
</para>
<informalexample>
Launching the default testsuite will open/close many windows, you might want to mute it
so you can keep using your computer:
<programlisting>gst-validate-launcher validate --sync --mute</programlisting>
</informalexample>
</refsect2>
<refsect2 id="gst-validate-launcher--implement-testsuite">
<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 consider 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-launcher --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 information.
<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 theora 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 theora 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>

48
validate/docs/validate/envvariables.xml
View file

@ -4,21 +4,12 @@
<!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>
<sect1 id="envvariables" revision="20 Apr 2015">
<title>GstValidate Environment Variables</title>
<refsect1>
<para>
The runtime behaviour of GstValidate applications can be influenced by a number of environment variables.
</para>
<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>
@ -72,7 +63,7 @@
</para>
<para>
You can use the special names "stdout" and "stderr" to use those output.
You can use the special names <literal>stdout</literal> and <literal>stderr</literal> to use those output.
</para>
</formalpara>
@ -84,7 +75,8 @@
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/scenarios</filename>
specified in the <ulink url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">XDG standard</ulink>:
<filename>.local/share/gstreamer-&GST_API_VERSION;/validate/scenarios</filename>
and the system wide user data directory: <filename>/usr/lib/gstreamer-&GST_API_VERSION;/validate/scenarios</filename>
</para>
</formalpara>
@ -93,11 +85,12 @@
<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
Set this variable to a colon-separated list of dynamically linkable files that GstValidate will
scan looking for 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/scenarios</filename>
specified in the <ulink url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">XDG standard</ulink>:
<filename>.local/share/gstreamer-&GST_API_VERSION;/validate/scenarios</filename>
and the system wide user data directory: <filename>/usr/lib/gstreamer-&GST_API_VERSION;/validate/scenarios</filename>
</para>
</formalpara>
@ -107,7 +100,7 @@
<para>
A decimal number to set as a multiplier for the wait actions. For example if you set
GST_VALIDATE_SCENARIO_WAIT_MULITPLIER=0.5, for a wait action that has a duration of 2.0
<literal>GST_VALIDATE_SCENARIO_WAIT_MULITPLIER=0.5</literal>, for a wait action that has a duration of 2.0
the waiting time will only be of 1.0 second. If set to 0, wait action will be ignored.
</para>
</formalpara>
@ -116,9 +109,9 @@
<title><envar>GST_VALIDATE_REPORTING_DETAILS</envar></title>
<para>
The reporting level can be set through the "GST_VALIDATE_REPORTING_DETAILS"
environment variable, as a comma-separated list of (optional) object categories / names
and levels. No object category / name sets the global level.
The reporting level can be set through the <envar>GST_VALIDATE_REPORTING_DETAILS</envar>
environment variable, as a comma-separated list of (optional) object categories / names
and levels. Omit the object category / name to set the global level.
<informalexample>
Examples:
@ -153,7 +146,7 @@
<listitem>
<para>
If set as the default level, similar issues can be reported multiple times for
different subchains. If set as the level for a particular object (my_object:subchain),
different subchains. If set as the level for a particular object (<literal>my_object:subchain</literal>),
validate will report the issues where the object is the first to report an issue for
a subchain.
</para>
@ -181,16 +174,15 @@
<listitem>
<para>
All the issues will be reported, even those
that repeat themselves inside the same object. This can be *very* verbose if
that repeat themselves inside the same object. This can be <emphasis role="bold">very</emphasis> verbose if
set globally.
</para>
</listitem>
</varlistentry>
</variablelist>
Setting the reporting level allows to control the way issues are reported
when calling #gst_validate_runner_printf.
when calling <function>gst_validate_runner_printf()</function>.
</para>
</formalpara>
</refsect1>
</refentry>
</sect1>

27
validate/docs/validate/gst-validate-docs.sgml
View file

@ -13,8 +13,9 @@
</releaseinfo>
</bookinfo>
<chapter>
<chapter id="overview">
<title>Overview and usage</title>
<sect1>
<para>
GstValidate is a tool that allows GStreamer developers to check
that the GstElements they write behave the way they are supposed to.
@ -25,27 +26,33 @@
<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.
have to follow to make them 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".
get detailed informations about what was not properly handled by the elements.
The generated reports are ordered 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
Some tools have been implemented to help developers validate and test
their GstElement, you can have a look at the <link linkend="command-line-tools">command line tools section</link>
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
On top of that, the notion of a <link linkend="scenarios">validation
scenario</link> has been implemented so that developers can easily execute a set
of actions on pipelines to test real world interactive cases and reproduce existing
issues in a convenient way.
</para>
</sect1>
<xi:include href="gst-validate.xml"/>
<xi:include href="gst-validate-transcoding.xml"/>
<xi:include href="gst-validate-media-check.xml"/>
<xi:include href="gst-validate-launcher.xml"/>
<xi:include href="command-line-tools.xml"/>
<xi:include href="scenarios.xml"/>
<xi:include href="envvariables.xml"/>
</chapter>

189
validate/docs/validate/gst-validate-launcher.xml Normal file
View file

@ -0,0 +1,189 @@
<?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="gst-validate-launcher">
<refentryinfo>
<author>
<othername>The GstValidate team</othername>
<personblurb>see http://cgit.freedesktop.org/gstreamer/gst-devtools/</personblurb>
</author>
<productname>gst-validate</productname>
</refentryinfo>
<refmeta>
<refentrytitle>gst-validate-launcher</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">GstValidate</refmiscinfo>
<refmiscinfo class="version">&GST_API_VERSION;</refmiscinfo>
<refmiscinfo class="manual">GstValidate Manual Pages</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gst-validate-launcher</refname>
<refpurpose>Tool to launch GstValidate testsuites</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gst-validate-launcher</command>
<arg choice="opt" rep="repeat">options</arg>
<arg choice="opt" rep="repeat">TESTSUITE</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>gst-validate-launcher</command> is an application to create
full testsuites on top of the GstValidate tools, testing behaviour with
dynamic pipelines and user actions (seeking, changing the pipeline
state, etc.) as described by the <link linkend="scenarios">scenario</link> format.
</para>
<refsect2 id="gst-validate-launcher--default-testsuite">
<title>Run the GstValidate default testsuite</title>
<para>
GstValidate comes with a default testsuite to be executed on a default set of media samples.
Those media samples are stored with <command>git-annex</command> so you
will need it to be able to launch the default testsuite.
</para>
<para>
The first time you launch the testsuite, you will need to make sure that the media samples are
downloaded. To do so and launch the testsuite you can simply do:
</para>
<informalexample>
<programlisting>gst-validate-launcher validate --sync</programlisting>
</informalexample>
<para>
This will only launch the GstValidate tests and not other applications that might be supported
(currently <command>ges-launch</command> is also supported and has its own default testsuite).
</para>
<para>
Launching the default testsuite will open/close many windows, you might want to mute it
so you can keep using your computer:
</para>
<informalexample>
<programlisting>gst-validate-launcher validate --sync --mute</programlisting>
</informalexample>
</refsect2>
<refsect2 id="gst-validate-launcher--implement-testsuite">
<title>Example of a testsuite implementation</title>
<para>
To implement a testsuite, you will have to write some simple python code that defines
the tests to be launched by <command>gst-validate-launcher</command>.
</para>
<para>
In this example, we will assume that you want to write a whole new testsuite based on
your own media samples and <link linkend="scenarios">scenarios</link>.
The set of media files and the testsuite implementation file will be structured as follow:
</para>
<literallayout>
testsuite_folder/
|-> testsuite.py
|-> sample_files/
|-> file.mp4
|-> file1.mkv
|-> file2.ogv
|-> scenarios
|-> scenario.scenario
|-> scenario1.scenario
</literallayout>
<para>
You should generate the <filename>.media_info</filename> files. To generate them for local files,
you can use:
</para>
<informalexample>
<programlisting>gst-validate-launcher --medias-paths /path/to/sample_files/ --generate-media-info</programlisting>
</informalexample>
<para>
For remote streams, you should use <command>gst-validate-media-check-&GST_API_VERSION;</command>. For an http stream you can for example do:
</para>
<informalexample>
<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 <command>gst-validate-launcher</command> will use the generated
<filename>.media_info</filename> and <filename>.stream_info</filename>
files to validate the tests as those contain the necessary information.
</para>
<para>
Then you will need to write the <filename>testsuite.py</filename> file. You can for example implement the following testsuite:
</para>
<informalexample>
<programlisting language="python">
import os
# Make sure gst-validate-launcher uses our media files
options.paths = os.path.dirname(os.path.realpath(__file__))
# Make sure GstValidate is able to use our 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 only care about critical issues in
# the report:
# os.environ["GST_VALIDATE"] = "print_criticals"
# Make gst-validate use our scenarios
validate.add_scenarios(["scenario", "scenario1"])
# Now add "Theora and Vorbis in OGG container" as a wanted transcoding format. That means
# that conversion to this format will be tested on all the media files/streams.
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 tests that are known to fail because a feature is not supported
# or due to any other 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>
Once this is done, you've got a testsuite that will:
</para>
<itemizedlist>
<listitem>
<para>
Run playbin pipelines on <filename>file.mp4</filename>, <filename>file1.mkv</filename> and
<filename>file2.ogv</filename>> executing <literal>scenario</literal> and <literal>scenario1</literal> scenarios
</para>
</listitem>
<listitem>
<para>
Transcode <filename>file.mp4,</filename> <filename>file1.mkv</filename> and <filename>file2.ogv</filename>
to Theora and Vorbis in a OGG container
</para>
</listitem>
</itemizedlist>
<para>
The only thing to do to run the testsuite is:
</para>
<informalexample>
<programlisting>gst-validate-launcher --config /path/to/testsuite_folder/testsuite.py</programlisting>
</informalexample>
</refsect2>
</refsect1>
<refsect1><title>Invocation</title>
<para>
You can find detailed information about the launcher by launching it:
</para>
<informalexample>
<programlisting>gst-validate-launcher --help</programlisting>
</informalexample>
</refsect1>
</refentry>

89
validate/docs/validate/gst-validate-media-check.xml Normal file
View file

@ -0,0 +1,89 @@
<?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="gst-validate-media-check">
<refentryinfo>
<author>
<othername>The GstValidate team</othername>
<personblurb>see http://cgit.freedesktop.org/gstreamer/gst-devtools/</personblurb>
</author>
<productname>gst-validate</productname>
</refentryinfo>
<refmeta>
<refentrytitle>gst-validate-media-check</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">GstValidate</refmiscinfo>
<refmiscinfo class="version">&GST_API_VERSION;</refmiscinfo>
<refmiscinfo class="manual">GstValidate Manual Pages</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gst-validate-media-check</refname>
<refpurpose>Tool to test GStreamer media types discovery</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gst-validate-media-check</command>
<arg choice="opt" rep="repeat">options</arg>
<arg choice="opt">URI</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gst-validate-media-check</command> is command line tool checking that media files discovering works
properly with <command>gst-discoverer</command> over multiple runs. 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 the reference matches what will be reported by <command>gst-discoverer</command> in the following runs.
</para>
<para>
For example, given that we have a valid <filename>reference.media_info</filename> file, we can run:
</para>
<informalexample>
<programlisting>gst-validate-media-check-&GST_API_VERSION; file:///./file.ogv --expected-results reference.media_info</programlisting>
</informalexample>
<para>
It will then output any error encountered and return an exit code different from 0 if any error is found.
</para>
</refsect1>
<refsect1><title>Invocation</title>
<para>
<command>gst-validate-media-check</command> takes an URI to analyze
and some extra options to control the output.
</para>
<refsect2 id="gst-validate-media-check.options"><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-o</option>, <option>--output-file</option></term>
<listitem><para>
The output file to store the results.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--full</option></term>
<listitem><para>
Fully analize the file frame by frame.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--expected-results</option></term>
<listitem><para>
Path to file containing the expected results (or the last results found) for comparison with new results.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
</refentry>

220
validate/docs/validate/gst-validate-transcoding.xml Normal file
View file

@ -0,0 +1,220 @@
<?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="gst-validate-transcoding">
<refentryinfo>
<author>
<othername>The GstValidate team</othername>
<personblurb>see http://cgit.freedesktop.org/gstreamer/gst-devtools/</personblurb>
</author>
<productname>gst-validate</productname>
</refentryinfo>
<refmeta>
<refentrytitle>gst-validate-transcoding</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">GstValidate</refmiscinfo>
<refmiscinfo class="version">&GST_API_VERSION;</refmiscinfo>
<refmiscinfo class="manual">GstValidate Manual Pages</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gst-validate-transcoding</refname>
<refpurpose>Tool to test GStreamer transcoding components</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gst-validate-transcoding</command>
<arg choice="opt" rep="repeat">options</arg>
<arg choice="opt">INPUT-URI</arg>
<arg choice="opt">OUTPUT-URI</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>gst-validate-transcoding</command> is tool to create media
files transcoding pipelines running inside the GstValidate monitoring
infrastructure.</para>
<para>
You can for example transcode any media file to Vorbis audio + VP8 video in a WebM container by doing:
</para>
<informalexample>
<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>
<command>gst-validate-transcoding</command> will list every issue encountered during the execution of the
transcoding operation in a human readable report like the one below:
</para>
<informalexample>
<computeroutput>
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</computeroutput>
</informalexample>
<para>
The return code of the process will be 18 in case a <literal>CRITICAL</literal> issue has been found.
</para>
<refsect2 id="gst-validate-transcoding--encoding-profile">
<title>The encoding profile serialization format</title>
<para>This is the serialization format of a <link linkend="GstEncodingProfile"><type>GstEncodingProfile</type></link>.</para>
<para>
Internally the transcoding application uses <link linkend="GstEncodeBin"><type>GstEncodeBin</type></link>. <command>gst-validate-transcoding-&GST_API_VERSION;</command> uses its own
serialization format to describe the <link linkend="GstEncodeBin--profile"><type>GstEncodeBin.profile</type></link>
property of the encodebin.
</para>
<para>
The simplest serialized profile looks like:
</para>
<informalexample>
<programlisting>muxer_source_caps:videoencoder_source_caps:audioencoder_source_caps</programlisting>
</informalexample>
<para>
For example to encode a stream into a WebM container, with an OGG audio stream and a VP8 video stream,
the serialized <link linkend="GstEncodingProfile"><type>GstEncodingProfile</type></link> will look like:
</para>
<informalexample>
<programlisting>video/webm:video/x-vp8:audio/x-vorbis</programlisting>
</informalexample>
<para>
You can also set the preset name of the encoding profile using the caps+preset_name syntax as in:
</para>
<informalexample>
<programlisting>video/webm:video/x-vp8+youtube-preset:audio/x-vorbis</programlisting>
</informalexample>
<para>
Moreover, you can set the <link linkend="gst-encoding-profile-set-presence">presence</link> property of an
encoding profile using the <code>|presence</code> syntax as in:
</para>
<informalexample>
<programlisting>video/webm:video/x-vp8|1:audio/x-vorbis</programlisting>
</informalexample>
<para>
This field allows you to specify how many times maximum a <link linkend="GstEncodingProfile"><type>GstEncodingProfile</type></link> can be used inside an encodebin.
</para>
<para>
You can also use the <code>restriction_caps->encoded_format_caps</code> syntax to specify the
<link linked="gst-encoding-profile-get-restriction">restriction caps</link>
to be set on a <link linkend="GstEncodingProfile"><type>GstEncodingProfile</type></link>. It corresponds to the
restriction <link linkend="GstCaps"><type>GstCaps</type></link> 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>
To force a video stream to be encoded with a Full HD resolution (using WebM as the container format,
VP8 as the video codec and Vorbis as the audio codec), you should use:
</para>
<informalexample>
<programlisting>video/webm:video/x-raw-yuv,width=1920,height=1080-->video/x-vp8:audio/x-vorbis</programlisting>
</informalexample>
<refsect3>
<title>Some serialized encoding formats examples:</title>
<para>
MP3 audio and H264 in MP4:
</para>
<informalexample>
<programlisting>video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3</programlisting>
</informalexample>
<para>
Vorbis and theora in OGG:
</para>
<informalexample>
<programlisting>application/ogg:video/x-theora:audio/x-vorbis</programlisting>
</informalexample>
<para>
AC3 and H264 in MPEG-TS:
</para>
<informalexample>
<programlisting>video/mpegts:video/x-h264:audio/x-ac3</programlisting>
</informalexample>
</refsect3>
</refsect2>
</refsect1>
<refsect1><title>Invocation</title>
<para>
<command>gst-validate-transcoding</command> takes and input URI and an output URI,
plus a few options to control how transcoding should be tested.
</para>
<refsect2 id="gst-validate-transcoding.options"><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--set-scenario</option></term>
<listitem><para>
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
<filename>.scenario</filename> extension).
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--list-scenarios</option></term>
<listitem><para>
List the avalaible scenarios that can be run.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--scenarios-defs-output-file</option></term>
<listitem><para>
The output file to store scenarios details. Implies <option>--list-scenario</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>, <option>--inspect-action-type</option></term>
<listitem><para>
Inspect the avalaible action types with which to write scenarios
if no parameter passed, it will list all avalaible action types
otherwize will print the full description of the wanted types.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--set-configs</option></term>
<listitem><para>
Let you set a config scenario. The scenario needs to be set as
<literal>config</literal>. You can specify a list of scenarios
separated by <literal>:</literal>. It will override the
<envar>GST_VALIDATE_SCENARIO</envar> environment variable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--eos-on-shutdown</option></term>
<listitem><para>
If an EOS event should be sent to the pipeline if an interrupt is
received, instead of forcing the pipeline to stop. Sending an EOS
will allow the transcoding to finish the files properly before exiting.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-r</option>, <option>--force-reencoding</option></term>
<listitem><para>
Whether to try to force reencoding, meaning trying to only remux if possible, defaults to <literal>TRUE</literal>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
</refentry>

139
validate/docs/validate/gst-validate.xml Normal file
View file

@ -0,0 +1,139 @@
<?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="gst-validate">
<refentryinfo>
<author>
<othername>The GstValidate team</othername>
<personblurb>see http://cgit.freedesktop.org/gstreamer/gst-devtools/</personblurb>
</author>
<productname>gst-validate</productname>
</refentryinfo>
<refmeta>
<refentrytitle>gst-validate</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">GstValidate</refmiscinfo>
<refmiscinfo class="version">&GST_API_VERSION;</refmiscinfo>
<refmiscinfo class="manual">GstValidate Manual Pages</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gst-validate</refname>
<refpurpose>Tool to test GStreamer components</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gst-validate</command>
<arg choice="opt" rep="repeat">options</arg>
<arg choice="plain">PIPELINE-DESCRIPTION</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gst-validate</command> is the simplest <command>gst-launch</command>-like pipeline launcher
running inside GstValidate monitoring infrastructure. Monitors are added to it to identify issues in the
used elements. At the end it will print a report with some information
about all the issues encountered during its run. To view issues as they are detected, set the environment
variable <code language="shell">GST_DEBUG=validate:2</code> and they will get printed in the GStreamer debug log.
You can basically run any <link linkend="GstPipeline"><type>GstPipeline</type></link> pipeline using this tool.
If you are not familiar with <command>gst-launch</command> syntax, please refer to
<command>gst-launch</command>'s documentation.
</para>
<para>
Simple playback pipeline:
</para>
<informalexample>
<programlisting>gst-validate-1.0 playbin uri=file:///path/to/some/media/file</programlisting>
</informalexample>
<para>
Transcoding pipeline:
</para>
<informalexample>
<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>
It will list each issue that has been encountered during the execution of the specified pipeline in a human readable report like:
</para>
<informalexample>
<literallayout><computeroutput>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</computeroutput></literallayout>
</informalexample>
<para>
The return code of the process will be 18 in case a <literal>CRITICAL</literal> issue has been found.
</para>
</refsect1>
<refsect1><title>Invocation</title>
<para>
<command>gst-validate</command> takes a mandatory description of the
pipeline to launch, similar to <command>gst-launch</command>, and
some extra options.
</para>
<refsect2 id="gst-validate.options"><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--set-scenario</option></term>
<listitem><para>
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
<filename>.scenario</filename> extension).
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--list-scenarios</option></term>
<listitem><para>
List the avalaible scenarios that can be run.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--scenarios-defs-output-file</option></term>
<listitem><para>
The output file to store scenarios details. Implies <option>--list-scenario</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>, <option>--inspect-action-type</option></term>
<listitem><para>
Inspect the avalaible action types with which to write scenarios
if no parameter passed, it will list all avalaible action types
otherwize will print the full description of the wanted types.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--set-media-info</option></term>
<listitem><para>
Set a media_info XML file descriptor to share information about the media file that will be reproduced.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--set-configs</option></term>
<listitem><para>
Let you set a config scenario. The scenario needs to be set as
<literal>config</literal>. You can specify a list of scenarios
separated by "<literal>:</literal>". It will override the
<envar>GST_VALIDATE_SCENARIO</envar> environment variable.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
</refentry>

265
validate/docs/validate/scenarios.xml
View file

@ -1,134 +1,143 @@
<?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" [
<!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="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>
<sect1 id="scenarios" revision="20 Apr 2015">
<title>GstValidate Scenario File Format</title>
<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 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 comma separated field, and then
the key values pair of the form 'parameter=value' separated by commas. 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 considered as a
int, but '1.0' will be considered as a double and '"1.0"' will be considered 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/scenarios ,
$GST_DATADIR/gstreamer-1.0/validate/scenarios 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 explaining 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 --inspect-action-type action_type_name
</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 --inspect-action-type
</programlisting>
</informalexample>
</para>
<para>
and (includes transcoding specific action types):
</para>
<para>
<informalexample>
<programlisting>
gst-validate-transcoding-1.0 --inspect-action-type
</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>
<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 <filename>.scenario</filename> extension.
The scenario 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 in the first comma separated field, and then
some key value pairs in the form <literal>parameter=value</literal> separated by commas. The values
type will be guessed if not casted as in <literal>parameter=(string)value</literal>. 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. <literal>1</literal> will be considered as a
<type>int</type>, but <literal>1.0</literal> will be considered as a <type>double</type> and <literal>"1.0"</literal>
will be considered as a <type>string</type>).
</para>
<para>
For example to represent a seek action, you should add the following line in the <filename>.scenario</filename>
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 <filename>.scenario</filename> extension and
should be placed either in <filename>$USER_DATA_DIR/gstreamer-1.0/validate/scenarios</filename> ,
<filename>$GST_DATADIR/gstreamer-1.0/validate/scenarios</filename> or in a path defined in the
<envar>$GST_VALIDATE_SCENARIOS_PATH</envar> environment variable.
</para>
<para>
Each line in the <filename>.scenario</filename> file represent an action (you can also use <literal>\</literal> at the end of a line
write a single action on multiple lines). Usually you should start you scenario with a <literal>description</literal>
"config" action in order for the user to have more information about the scenario. It can contain
a <literal>summary</literal> field which is a string explaining 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 --inspect-action-type action_type_name
</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>
<literal>seek</literal>: Seeks into the stream.
</para>
</listitem>
<listitem>
<para>
<literal>play</literal>: Set the pipeline state to
<type><link linkend="GST-STATE-PLAYING:CAPS">GST_STATE_PLAYING</link></type>.
</para>
</listitem>
<listitem>
<para>
<literal>pause</literal>: Set the pipeline state to
<type><link linkend="GST-STATE-PAUSED:CAPS">GST_STATE_PAUSED</link></type>.
</para>
</listitem>
<listitem>
<para>
<literal>stop</literal>: Stop the execution of the pipeline.
</para>
<para>
<emphasis role="bold">NOTE</emphasis>: This action actually posts a
<link linkend="GST-MESSAGE-REQUEST-STATE:CAPS"><type>GST_MESSAGE_REQUEST_STATE</type></link> message requesting
<link linkend="GST-STATE-NULL:CAPS"><type>GST_STATE_NULL</type></link> 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 --inspect-action-type
</programlisting>
</informalexample>
</para>
<para>
and to include transcoding specific action types:
</para>
<para>
<informalexample>
<programlisting>
gst-validate-transcoding-1.0 --inspect-action-type
</programlisting>
</informalexample>
</para>
<para>
Many scenarios are distributed with <command>gst-validate</command>, 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 scenario implementation and action types in the
<link linkend="GstValidateScenario"><type>GstValidateScenario</type> section</link>.
</para>
</sect1>