mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-06-05 06:58:56 +00:00
Code Issues 1 Projects Releases Wiki Activity

doc: Port to hotdoc

Browse source 
Ideally we want a GstValidate hotdoc plugin... not for now.
This commit is contained in:
Thibault Saunier 2018-10-22 11:38:30 +02:00
parent 8754d0520f
commit 0a7b23f566
51 changed files with 836 additions and 2140 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/api.md Normal file
View file

@ -0,0 +1,6 @@
# GstValidate API reference
This is GstValidate API reference but note that the GstValidate is not
totally stable and might very well change even between minor versions.
The override API should be mostly stable still.

1
docs/gi-index.md Normal file
View file

@ -0,0 +1 @@
# GstValidate API reference

9
docs/gst-validate-config.md Normal file
View file

@ -0,0 +1,9 @@
---
title: Configuration
short-description: GstValidate configuration
...
# GstValidate Configuration
GstValidate comes with some possible configuration files
to setup its plugins (and potentially core behaviour).

153
docs/gst-validate-environment-variables.md Normal file
View file

@ -0,0 +1,153 @@
---
title: Environment variables
short-description: Environment variables influencing runtime behaviour
...
# GstValidate Environment Variables
The runtime behaviour of GstValidate applications can be influenced by a
number of environment variables.
**GST_VALIDATE.**
This environment variable can be set to a list of debug options, which
cause GstValidate to print out different types of test result
information and consider differently the level of the reported issues.
* `fatal-criticals`: Causes GstValidate to consider only critical issues as import enough
to consider the test failed (default behaviour)
* `fatal-warnings`: Causes GstValidate to consider warning, and critical issues as
import enough to consider the test failed
* `fatal-issues`: Causes GstValidate to consider issue, warning, and critical issues
as import enough to consider the test failed
* `print-issues`: Causes GstValidate to print issue, warning and critical issues in
the final reports (default behaviour)
* `print-warnings`: Causes GstValidate to only print warning and critical issues in the
final reports
* `print-criticals`: Causes GstValidate to only print critical issues in the final
reports
**GST_VALIDATE_FILE.**
Set this variable to a colon-separated list of paths to redirect all
GstValidate messages to this file. If left unset, debug messages will be
outputed into the standard error.
You can use the special names `stdout` and `stderr` to use those output.
**GST_VALIDATE_SCENARIOS_PATH.**
Set this variable to a colon-separated list of paths. GstValidate will
scan these paths for GstValidate scenario files. By default GstValidate
will look for scenarios in the user data directory as specified in the
[XDG standard]:
`.local/share/gstreamer-GST_API_VERSION/validate/scenarios` and the
system wide user data directory:
`/usr/lib/gstreamer-GST_API_VERSION/validate/scenarios`
**GST_VALIDATE_CONFIG.**
Set this variable to a colon-separated list of paths to GstValidate
config files or directly as a string in the GstCaps serialization
format. The config file has a format similar to the scenario file. The
name of the configuration corresponds to the name of the plugin the
configuration applies to.
The special name "core" is used to configure GstValidate core
functionalities (monitors, scenarios, etc...).
If you want to make sure to set a property on a element of a type (for
example to disable QoS on all sinks) you can do:
```
core, action=set-property, target-element-klass=Sink
```
If you want the GstPipeline to get dumped when an issue of a certain
level (and higher) happens, you can do:
```
core, action=dot-pipeline, report-level=issue
```
Note that you will still need to set GST_DEBUG_DUMP_DOT_DIR.
For more examples you can look at the ssim GstValidate plugin
documentation to see how to configure that plugin.
You can also check that a src pad is pushing buffers at a minimum
frequency. For example to check if v4l2src is producing at least 60 frames
per second you can do:
``` yaml
core,min-buffer-frequency=60,target-element-factory-name=v4l2src
```
This config accepts the following fields:
- `min-buffer-frequency`: the expected minimum rate, in buffers per
second, at which buffers are pushed on the pad
- `target-element-{factory-name,name,klass}`: the factory-name, object
name or class of the element to check
- `name`: (optional) only check the frequency if the src pad has this
name
- `buffer-frequency-start`: (optional) if defined, validate will
ignore the frequency of the pad during the time specified in this
field, in ns. This can be useful when testing live pipelines where
configuring and setting up elements can take some time slowing down
the first buffers until the pipeline reaches its cruising speed.
**GST_VALIDATE_OVERRIDE.**
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]:
`.local/share/gstreamer-GST_API_VERSION/validate/scenarios` and the
system wide user data directory:
`/usr/lib/gstreamer-GST_API_VERSION/validate/scenarios`
**GST_VALIDATE_SCENARIO_WAIT_MULITPLIER.**
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 the waiting time will only be of
1.0 second. If set to 0, wait action will be ignored.
**GST_VALIDATE_REPORTING_DETAILS.**
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.
Omit the object category / name to set the global level.
Examples:
```
GST_VALIDATE_REPORTING_DETAILS=synthetic,h264parse:all
GST_VALIDATE_REPORTING_DETAILS=none,h264parse::sink_0:synthetic
```
Levels being:
* `none`: No debugging level specified or desired. Used to deactivate
debugging output.
* `synthetic`: Summary of the issues found, with no details.
* `subchain`: 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`), validate will report the issues where
the object is the first to report an issue for a subchain.
* `monitor`: If set as the default level, all the distinct issues for all the
monitors will be reported. If set as the level for a particular
object, all the distinct issues for this object will be reported.
Note that if the same issue happens twice on the same object, up
until this level that issue is only reported once.
* `all`: All the issues will be reported, even those that repeat themselves
inside the same object. This can be **very** verbose if set
globally.
Setting the reporting level allows to control the way issues are
reported when calling [gst_validate_runner_printf()](gst_validate_runner_printf).
[XDG standard]: http://www.freedesktop.org/wiki/Software/xdg-user-dirs/

129
docs/gst-validate-launcher.md Normal file
View file

@ -0,0 +1,129 @@
---
short-description: Integration testsuite builder and launcher
...
# gst-validate-launcher
`gst-validate-launcher` 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 [scenario](GstValidateScenario) format.
## Run the GstValidate default testsuite
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 the default testsuite.
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:
gst-validate-launcher validate --sync
This will only launch the GstValidate tests and not other applications
that might be supported (currently `ges-launch` is also supported and
has its own default testsuite).
Launching the default testsuite will open/close many windows, you might
want to mute it so you can keep using your computer:
gst-validate-launcher validate --sync --mute
## Example of a testsuite implementation
To implement a testsuite, you will have to write some simple python code
that defines the tests to be launched by `gst-validate-launcher`.
In this example, we will assume that you want to write a whole new
testsuite based on your own media samples and [scenarios](GstValidateScenario). The
set of media files and the testsuite implementation file will be
structured as follow:
testsuite_folder/
|-> testsuite.py
|-> sample_files/
|-> file.mp4
|-> file1.mkv
|-> file2.ogv
|-> scenarios
|-> scenario.scenario
|-> scenario1.scenario
You should generate the `.media_info` files. To generate them for local
files, you can use:
gst-validate-launcher --medias-paths /path/to/sample_files/ --generate-media-info
For remote streams, you should use
`gst-validate-media-check-GST_API_VERSION`. For an http stream you can
for example do:
gst-validate-media-check-GST_API_VERSION http://someonlinestream.com/thestream \
--output-file /path/to/testsuite_folder/sample_files/thestream.stream_info
The `gst-validate-launcher` will use the generated `.media_info` and
`.stream_info` files to validate the tests as those contain the
necessary information.
Then you will need to write the `testsuite.py` file. You can for example
implement the following testsuite:
``` 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")]
)
```
Once this is done, you've got a testsuite that will:
- Run playbin pipelines on `file.mp4`, `file1.mkv` and `file2.ogv`>
executing `scenario` and `scenario1` scenarios
- Transcode `file.mp4,` `file1.mkv` and `file2.ogv` to Theora and
Vorbis in a OGG container
The only thing to do to run the testsuite is:
gst-validate-launcher --config /path/to/testsuite_folder/testsuite.py
# Invocation
You can find detailed information about the launcher by launching it:
gst-validate-launcher --help

32
docs/gst-validate-media-check.md Normal file
View file

@ -0,0 +1,32 @@
---
short-description: Tool to test GStreamer media types discovery
...
# gst-validate-media-check
`gst-validate-media-check` is command line tool checking that media
files discovering works properly with `gst-discoverer` 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 `gst-discoverer` in the following runs.
For example, given that we have a valid `reference.media_info` file, we
can run:
gst-validate-media-check-GST_API_VERSION file:///./file.ogv --expected-results reference.media_info
It will then output any error encountered and return an exit code
different from 0 if any error is found.
# Invocation
`gst-validate-media-check` takes an URI to analyze and some extra
options to control the output.
## Options
* `-o`, `--output-file`: The output file to store the results.
* `-f`, `--full`: Fully analize the file frame by frame.
* `-e`, `--expected-results`: Path to file containing the expected results (or the last results
found) for comparison with new results.

95
docs/gst-validate-scenarios.md Normal file
View file

@ -0,0 +1,95 @@
---
title: Scenarios
short-description: The GstValidate Scenario format
...
# GstValidate Scenario File Format
To be able to define a list of actions to execute on a [`GstPipeline`],
a dedicated file format is used. The name of the scenario is the name of
the file without its `.scenario` extension. The scenario file format is
based on the [`GstStructure`] 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
`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`).
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/scenarios` ,
`$GST_DATADIR/gstreamer-1.0/validate/scenarios` 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 explaining
what the scenario does and then several info fields about the scenario.
You can find more info about it running:
gst-validate-1.0 --inspect-action-type action_type_name
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:
- `seek`: Seeks into the stream.
- `play`: Set the pipeline state to `GST_STATE_PLAYING`.
- `pause`: Set the pipeline state to `GST_STATE_PAUSED`.
- `stop`: Stop the execution of the pipeline.
> **NOTE**: This action actually posts a [`GST_MESSAGE_REQUEST_STATE`]
> message requesting [`GST_STATE_NULL`] on the bus and the application
> should quit.
To get all the details about the registered action types, you can list
them all with:
```
gst-validate-1.0 --inspect-action-type
```
and to include transcoding specific action types:
```
gst-validate-transcoding-1.0 --inspect-action-type
```
Many scenarios are distributed with `gst-validate`, you can list them
all using:
```
gst-validate-1.0 --list-scenarios
```
You can find more information about the scenario implementation and
action types in the [`GstValidateScenario` section].
[`GstPipeline`]: GstPipeline
[`GstStructure`]: GstStructure
[`GST_MESSAGE_REQUEST_STATE`]: GST_MESSAGE_REQUEST_STATE
[`GST_STATE_NULL`]: GST_STATE_NULL
[`GstValidateScenario` section]: GstValidateScenario

126
docs/gst-validate-transcoding.md Normal file
View file

@ -0,0 +1,126 @@
---
short-description: Tool to test GStreamer components
...
# gst-validate-transcoding
`gst-validate-transcoding` is tool to create media files transcoding
pipelines running inside the GstValidate monitoring infrastructure.
You can for example transcode any media file to Vorbis audio + VP8 video
in a WebM container by doing:
gst-validate-transcoding-GST_API_VERSION file:///./file.ogg file:///.../transcoded.webm -o 'video/webm:video/x-vp8:audio/x-vorbis'
`gst-validate-transcoding` will list every issue encountered during the
execution of the transcoding operation in a human readable report like
the one below:
issue : buffer is out of the segment range Detected on theoradec0.srcpad
at 0:00:00.096556426 Details : buffer is out of segment and shouldn't be
pushed. Timestamp: 0:00:25.000 - duration: 0:00:00.040 Range:
0:00:00.000 - 0:00:04.520 Description : buffer being pushed is out of
the current segment's start-stop range. Meaning it is going to be
discarded downstream without any use
The return code of the process will be 18 in case a `CRITICAL` issue has
been found.
## The encoding profile serialization format
This is the serialization format of a [GstEncodingProfile](GstEncodingProfile).
Internally the transcoding application uses [GstEncodeBin](encodebin).
`gst-validate-transcoding-GST_API_VERSION` uses its own serialization
format to describe the [`GstEncodeBin.profile`](GstEncodeBin--profile) property of the
encodebin.
The simplest serialized profile looks like:
muxer_source_caps:videoencoder_source_caps:audioencoder_source_caps
For example to encode a stream into a WebM container, with an OGG audio
stream and a VP8 video stream, the serialized [GstEncodingProfile](GstEncodingProfile)
will look like:
video/webm:video/x-vp8:audio/x-vorbis
You can also set the preset name of the encoding profile using the
caps+preset\_name syntax as in:
video/webm:video/x-vp8+youtube-preset:audio/x-vorbis
Moreover, you can set the [presence](gst_encoding_profile_set_presence) property
of an encoding profile using the `|presence` syntax as in:
video/webm:video/x-vp8|1:audio/x-vorbis
This field allows you to specify how many times maximum a
[GstEncodingProfile](GstEncodingProfile) can be used inside an encodebin.
You can also use the `restriction_caps->encoded_format_caps` syntax to
specify the [restriction caps](GstEncodingProfile::restriction-caps)
to be set on a [GstEncodingProfile](GstEncodingProfile). It
corresponds to the restriction [GstCaps](GstCaps) to apply before the encoder
that will be used in the profile. The fields present in restriction caps
are properties of the raw stream (that is, before encoding), such as
height and width for video and depth and sampling rate for audio. This
property does not make sense for muxers.
To force 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:
video/webm:video/x-raw,width=1920,height=1080->video/x-vp8:audio/x-vorbis
### Some serialized encoding formats examples:
MP3 audio and H264 in MP4:
<div class="informalexample">
video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3
</div>
Vorbis and theora in OGG:
<div class="informalexample">
application/ogg:video/x-theora:audio/x-vorbis
</div>
AC3 and H264 in MPEG-TS:
<div class="informalexample">
video/mpegts:video/x-h264:audio/x-ac3
</div>
# Invocation
`gst-validate-transcoding` takes and input URI and an output URI, plus a
few options to control how transcoding should be tested.
## Options
* `--set-scenario`: Let you set a scenario, it can be a full path to a scenario file or
the name of the scenario (name of the file without the `.scenario`
extension).
* `-l`, `--list-scenarios`: List the avalaible scenarios that can be run.
* `--scenarios-defs-output-file`: The output file to store scenarios details. Implies
`--list-scenario`.
* `-t`, `--inspect-action-type`: 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.
* `--set-configs`: Let you set a config scenario. The scenario needs to be set as
`config`. You can specify a list of scenarios separated by `:`. It
will override the GST\_VALIDATE\_SCENARIO environment variable.
* `-e`, `--eos-on-shutdown`: 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.
* `-r`, `--force-reencoding`: Whether to try to force reencoding, meaning trying to only remux if
possible, defaults to `TRUE`.

58
docs/gst-validate.md Normal file
View file

@ -0,0 +1,58 @@
---
short-description: Tool to test GStreamer components
...
# gst-validate
`gst-validate` is the simplest `gst-launch`-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 `GST_DEBUG=validate:2`{.shell} and they will get printed in the
GStreamer debug log. You can basically run any [GstPipeline](GstPipeline) pipeline
using this tool. If you are not familiar with `gst-launch` syntax,
please refer to `gst-launch`'s documentation.
Simple playback pipeline:
gst-validate-1.0 playbin uri=file:///path/to/some/media/file
Transcoding pipeline:
gst-validate-1.0 filesrc location=/media/file/location ! qtdemux name=d ! queue \
! x264enc ! h264parse ! mpegtsmux name=m ! progressreport \
! filesink location=/root/test.ts d. ! queue ! faac ! m.
It will list each issue that has been encountered during the execution
of the specified pipeline in a human readable report like:
issue : buffer is out of the segment range Detected on theoradec0.srcpad at 0:00:00.096556426
Details : buffer is out of segment and shouldn't be pushed. Timestamp: 0:00:25.000 - duration: 0:00:00.040 Range: 0:00:00.000 - 0:00:04.520
Description : buffer being pushed is out of the current segment's start-stop range. Meaning it is going to be discarded downstream without any use
The return code of the process will be 18 in case a `CRITICAL` issue has
been found.
# Invocation
`gst-validate` takes a mandatory description of the pipeline to launch,
similar to `gst-launch`, and some extra options.
## Options
* `--set-scenario`: Let you set a scenario, it can be a full path to a scenario file or
the name of the scenario (name of the file without the `.scenario`
extension).
* `-l`, `--list-scenarios`: List the avalaible scenarios that can be run.
* `--scenarios-defs-output-file`: The output file to store scenarios details. Implies
`--list-scenario`.
* `-t`, `--inspect-action-type`: 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.
* `--set-media-info`: Set a media\_info XML file descriptor to share information about the
media file that will be reproduced.
* `--set-configs`: Let you set a config scenario. The scenario needs to be set as
`config`. You can specify a list of scenarios separated by "`:`". It
will override the GST\_VALIDATE\_SCENARIO environment variable.

27
docs/index.md Normal file
View file

@ -0,0 +1,27 @@
# GStreamer Validate
GstValidate is a tool that allows GStreamer developers to check that the
GstElements they write behave the way they are supposed to. It was first
started to provide plug-ins developers with a tool to check that they
use the framework the proper way.
GstValidate implements a monitoring logic that allows the system to
check that the elements of a GstPipeline respect some rules GStreamer
components have to follow 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.
Then GstValidate implements a reporting system that allows users to 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".
Some tools have been implemented to help developers validate and test
their GstElement, you can have a look at the [command line tools
section](command-line-tools.md) to find more information.
On top of that, the notion of a [validation scenario] 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.

71
docs/meson.build Normal file
View file

@ -0,0 +1,71 @@
build_hotdoc = false
if meson.is_cross_build()
if get_option('doc').enabled()
error('Documentation enabled but building the doc while cross building is not supported yet.')
endif
message('Documentation not built as building it while cross building is not supported yet.')
subdir_done()
endif
hotdoc_p = find_program('hotdoc', required: get_option('doc'))
if not hotdoc_p.found()
message('Hotdoc not found, not building the documentation')
subdir_done()
endif
required_hotdoc_extensions = ['gi-extension']
if not build_gir
if get_option('doc').enabled()
error('Documentation enabled but introspection not built.')
endif
message('Introspection not built, can\'t build the documentation')
subdir_done()
endif
hotdoc = import('hotdoc')
foreach extension: required_hotdoc_extensions
if not hotdoc.has_extensions(extension)
if get_option('doc').enabled()
error('Documentation enabled but @0@ missing'.format(extension))
endif
message('@0@ extension not found, not building documentation'.format(extension))
subdir_done()
endif
endforeach
excludes = ['gettext.h',
'gst-validate-internal.h',
'gst-validate-i18n-lib.c'
]
build_hotdoc = true
validate_excludes = []
foreach f: excludes
validate_excludes += [join_paths(meson.current_source_dir(), '..',
'validate', 'gst', 'validate', f)]
endforeach
validate_sources = []
foreach f: gstvalidate_headers + gstvalidate_sources
validate_sources += [join_paths(meson.current_source_dir(), '..',
'validate', 'gst', 'validate', f)]
endforeach
hotdoc = import('hotdoc')
plugins_doc = []
libs_doc = [hotdoc.generate_doc('gst-devtools',
project_version: apiversion,
sitemap: 'sitemap.txt',
index: 'index.md',
gi_c_sources: validate_sources,
gi_c_source_filters: validate_excludes,
gi_index: 'gi-index.md',
gi_smart_index: true,
gi_sources: [validate_gir[0].full_path()],
disable_incremental_build: true,
dependencies : [validate_dep],
)]

3
docs/plugins/index.md Normal file
View file

@ -0,0 +1,3 @@
# GstValidate plugins
GstValidate offers a plugin system to extend the checks and add new functionnality

84
docs/plugins/ssim.md Normal file
View file

@ -0,0 +1,84 @@
---
title: SSIM plugin
short_description: GstValidate plugin to detect frame corruptions
...
# SSIM plugin
GstValidate plugin to run the ssim algorithm on the buffers flowing in the
pipeline to find regressions and detect frame corruptions.
It allows you to generate image files from the buffers flowing in the pipeline
(either as raw in the many formats supported by GStreamer or as png) and then
check them against pre generated, reference images.
The ssim algorithm will set a value of 1.0 when images are perfectly identical,
and -1.0 if they have nothing in common. By default we consider images as similar
if they have at least a ssim value of 0.95 but you can override it defining the value
under which the test will be considered as failed.
Errors are reported on the GstValidate reporting system. You can also ask
the plugin to generate grey scale output images. Those will be named in a way
that should lets you precisely see where and how the test failed.
# Configuration
The configuration of the plugin is done through a validate configuration file,
specified with the %GST_VALIDATE_CONFIG environment variable. Each line starting
with 'ssim,' will configure the ssim plugin. In practice each configuration statement
will lead to the creation of a #GstValidateOverride object which will then dump
image files and if wanted compare those with a set of reference images.
The following parameters can be passed in the configuration file:
- element-classification: The target element classification as define in
gst_element_class_set_metadata
- output-dir: The directory in which the image files will be saved
- min-avg-priority: (default 0.95): The minimum average similarity
under which we consider the test as failing
- min-lowest-priority: (default 1): The minimum 'lowest' similarity
under which we consider the test as failing
- reference-images-dir: Define the directory in which the files to be
compared can be found
- result-output-dir: The folder in which to store resulting grey scale
images when the test failed. In that folder you will find images
with the structural difference between the expected result and the actual
result.
- output-video-format: The format in which you want the images to be saved
- reference-video-format: The format in which the reference images are stored
- check-recurrence: The recurrence in seconds (as float) the frames should
be dumped and checked.By default it is GST_CLOCK_TIME_NONE, meaning each
and every frame is checked. Not that in any case, after a discontinuity
in the stream (after a seek or a change in the video format for example)
a check is done. And if recurrence == 0, images will be checked only after
such discontinuity
- is-config: Property letting the plugin know that the config line is exclusively
used to configure the following configuration expressions. In practice this
means that it will change the default values for the other configuration
expressions.
# Example #
Let's take a special configuration where we want to compare frames that are
outputted by a video decoder with the ones after a agingtv element we would
call my_agingtv. We force to check one frame every 5.0 seconds only (with
check-recurrence=5.0) so the test is fast.
The configuration file:
``` shell
core, action=set-property, target-element-klass=Sink, property-name=sync, property-value=false
ssim, is-config=true, output-video-format="I420", reference-video-format="I420"
ssim, element-classification="Video/Decoder", output-dir=/tmp/test/before-agingtv/
ssim, element-name=my_agingtv, output-dir=/tmp/test/after-agingtv/, \
reference-images-dir=/tmp/test/before-agingtv/, \
result-output-dir=/tmp/test/failures, check-recurrence=5.0
```
Save that content in a file called check_agingtv_ssim.config
## Launch the pipeline
``` shell
GST_VALIDATE_CONFIG=check_agingtv_ssim.config gst-validate-1.0-debug uridecodebin uri=file://a/file ! videoconvert ! agingtv name=my_agingtv ! videoconvert ! autovideosink
```

10
docs/sitemap.txt Normal file
View file

@ -0,0 +1,10 @@
index.md
gst-validate.md
gst-validate-transcoding.md
gst-validate-media-check.md
gst-validate-launcher.md
gst-validate-scenarios.md
gst-validate-environment-variables.md
gi-index
plugins/index.md
plugins/ssim.md

4
meson.build
View file

@ -1,6 +1,6 @@
project('gst-devtools', 'c',
version : '1.17.0.1',
meson_version : '>= 0.47',
meson_version : '>= 0.48',
default_options : [ 'warning_level=1',
'c_std=gnu99',
'buildtype=debugoptimized' ])
@ -141,6 +141,7 @@ if get_option('default_library') == 'shared'
plugins_pkgconfig_install_dir = disabler()
endif
plugins = []
i18n = import('i18n')
python_mod = import('python')
@ -153,5 +154,6 @@ endif
if get_option('debug_viewer')
subdir('debug-viewer')
endif
subdir('docs')
run_command(python3, '-c', 'import shutil; shutil.copy("hooks/multi-pre-commit.hook", ".git/hooks/pre-commit")')

2
meson_options.txt
View file

@ -10,3 +10,5 @@ option('tests', type : 'feature', value : 'auto', yield : true,
description : 'Build and enable unit tests')
option('nls', type : 'feature', value : 'auto', yield: true,
description : 'Enable native language support (translations)')
option('doc', type : 'feature', value : 'auto', yield: true,
description: 'Enable documentation.')

3
validate/Makefile.am
View file

@ -1,5 +1,3 @@
DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
SUBDIRS = \
common \
data \
@ -9,7 +7,6 @@ SUBDIRS = \
launcher \
tools \
pkgconfig \
docs \
tests \
po

13
validate/configure.ac
View file

@ -106,14 +106,6 @@ AM_CONDITIONAL(HAVE_VALGRIND, test ! "x$VALGRIND_PATH" = "xno")
dnl check for gobject-introspection
GOBJECT_INTROSPECTION_CHECK([0.6.3])
dnl check for documentation tools
AG_GST_DOCBOOK_CHECK
GTK_DOC_CHECK([1.3])
AC_CHECK_PROG(enable_sphinx_doc, sphinx-build, yes, no)
AM_CONDITIONAL(HAVE_SPHINHX, test ! "x$enable_sphinx_doc" = "xno")
dnl *** checks for libraries ***
dnl *** checks for header files ***
@ -352,11 +344,6 @@ tools/Makefile
launcher/Makefile
launcher/apps/Makefile
launcher/testsuites/Makefile
docs/Makefile
docs/version.entities
docs/validate/Makefile
docs/plugins/Makefile
docs/launcher/Makefile
])
AC_OUTPUT

13
validate/docs/Makefile.am
View file

@ -1,13 +0,0 @@
SUBDIRS = validate plugins
DIST_SUBDIRS = validate launcher plugins
if HAVE_SPHINHX
SUBDIRS += launcher
endif
upload:
@if test "x$(SUBDIRS)" != x; then for a in $(SUBDIRS); do cd $$a; make upload; cd ..; done; fi
libs: validate
include $(top_srcdir)/common/parallel-subdirs.mak

177
validate/docs/launcher/Makefile.am
View file

@ -1,177 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = .
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf html/*
-rm -rf dirhtml/*
-rm -rf singlehtml/*
-rm -rf pickle/*
-rm -rf json/*
-rm -rf htmlhelp/*
-rm -rf qthelp/*
-rm -rf devhelp/*
-rm -rf epub/*
-rm -rf latex/*
-rm -rf text/*
-rm -rf man/*
-rm -rf texinfo/*
-rm -rf info/*
-rm -rf gettext/*
-rm -rf changes/*
-rm -rf linkcheck/*
-rm -rf doctest/*
all:
@export PYTHONPATH=$(PYTHONPATH):$(top_srcdir)/tools/launcher:$(top_srcdir)/tools/launcher/apps
@echo $(PYTHONPATH)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/gst-validate-launcher.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/gst-validate-launcher.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/gst-validate-launcher"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/gst-validate-launcher"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
# for upload-doc.mak
DOC=gst-validate-launcher
FORMATS=html
include $(top_srcdir)/common/upload-doc.mak

244
validate/docs/launcher/conf.py
View file

@ -1,244 +0,0 @@
# -*- coding: utf-8 -*-
#
# gst-validate-launcher documentation build configuration file, created by
# sphinx-quickstart on Sat Sep 6 11:26:51 2014.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'gst-validate-launcher'
copyright = u'2014, Thibault Saunier'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0.0.1'
# The full version, including alpha/beta/rc tags.
release = '1.0.0.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'gst-validate-launcherdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'gst-validate-launcher.tex', u'gst-validate-launcher Documentation',
u'Thibault Saunier', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'gst-validate-launcher', u'gst-validate-launcher Documentation',
[u'Thibault Saunier'], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'gst-validate-launcher', u'gst-validate-launcher Documentation',
u'Thibault Saunier', 'gst-validate-launcher', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
autoclass_content = 'both'

22
validate/docs/launcher/index.rst
View file

@ -1,22 +0,0 @@
.. gst-validate-launcher documentation master file, created by
sphinx-quickstart on Sat Sep 6 11:26:51 2014.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to gst-validate-launcher's documentation!
=================================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

43
validate/docs/launcher/launcher.rst
View file

@ -1,43 +0,0 @@
launcher Package
================
:mod:`launcher` Package
-----------------------
.. automodule:: __init__
:members:
:undoc-members:
:show-inheritance:
:mod:`baseclasses` Module
-------------------------
.. automodule:: baseclasses
:members:
:undoc-members:
:show-inheritance:
:mod:`reporters` Module
-----------------------
.. automodule:: reporters
:members:
:undoc-members:
:show-inheritance:
:mod:`utils` Module
-------------------
.. automodule:: utils
:members:
:undoc-members:
:show-inheritance:
:mod:`gstvalidate` Module
-------------------
.. automodule:: gstvalidate
:members:
:undoc-members:
:show-inheritance:

7
validate/docs/launcher/modules.rst
View file

@ -1,7 +0,0 @@
.
=
.. toctree::
:maxdepth: 4
launcher

2
validate/docs/meson.build
View file

@ -1,2 +0,0 @@
subdir('validate')
# subdir('launcher')

18
validate/docs/plugins/.gitignore vendored
View file

@ -1,18 +0,0 @@
*.bak
*.stamp
html
xml
Makefile
Makefile.in
doc-registry.xml
*-decl-list.txt
*-decl.txt
*-undeclared.txt
*-undocumented.txt
*-unused.txt
*.args
*.hierarchy
*.interfaces
*.prerequisites
*.signals

62
validate/docs/plugins/Makefile.am
View file

@ -1,62 +0,0 @@
GST_DOC_SCANOBJ = $(top_srcdir)/common/gstdoc-scangobj
# The name of the module, e.g. 'glib'.
MODULE=gst-validate
DOC_MODULE=$(MODULE)-plugins
# for upload-doc.mak
DOC=$(MODULE)-plugins
FORMATS=html
html: html-build.stamp
include $(top_srcdir)/common/upload-doc.mak
# The top-level SGML file. Change it if you want.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code.
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting functions and macros.
DOC_SOURCE_DIR = $(top_srcdir)/plugins/
# Extra options to supply to gtkdoc-scan.
SCAN_OPTIONS=
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--sgml-mode
# Extra options to supply to gtkdoc-fixref.
FIXXREF_OPTIONS=--extra-dir=$(top_builddir)/docs/gst/html \
--extra-dir=$(top_builddir)/docs/libs/html \
--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html \
--extra-dir=$(datadir)/gtk-doc/html
# Used for dependencies.
CFILE_GLOB=$(top_srcdir)/plugins/*/*.c
# Header files to ignore when scanning.
IGNORE_HFILES =
IGNORE_CFILES =
# Images to copy into HTML directory.
HTML_IMAGES =
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
content_files =
# Other files to distribute.
extra_files =
# CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
# contains GtkObjects/GObjects and you want to document signals and properties.
GTKDOC_CFLAGS = $(GST_BASE_CFLAGS) $(GST_OBJ_CFLAGS) -I$(top_builddir) -I$(top_builddir)/gst-libs
GTKDOC_LIBS = $(GST_BASE_LIBS)
GTKDOC_CC=$(LIBTOOL) --tag=CC --mode=compile $(CC)
GTKDOC_LD=$(LIBTOOL) --tag=CC --mode=link $(CC)
# If you need to override some of the declarations, place them in this file
# and uncomment this line.
DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
include $(top_srcdir)/common/gtk-doc.mak

28
validate/docs/plugins/gst-validate-plugins-docs.sgml
View file

@ -1,28 +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;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GStreamer Validate Plugins &GST_API_VERSION; Plugins Reference Manual</title>
<releaseinfo>
GStreamer Validate Plugins &GST_API_VERSION; Plugins Reference Manual
for GStreamer Validate &GST_API_VERSION; (&GST_VERSION;)
The latest version of this documentation can be found on-line at
<ulink role="online-location"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-validate-plugins/html/">
http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-validate-plugins/html/
</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
<title>GstValidate plugins</title>
<xi:include href="xml/validate-ssim.xml"/>
</chapter>
</book>

0
validate/docs/plugins/gst-validate-plugins-overrides.txt
View file

9
validate/docs/plugins/gst-validate-plugins-sections.txt
View file

@ -1,9 +0,0 @@
<SECTION>
<FILE>validate-ssim</FILE>
<TITLE>Validate SSim plugin</TITLE>
VALIDATE_TYPE_S_SIM_OVERRIDE
ValidateSSimOverrideClass
validate_s_sim_override_new
ValidateSSimOverride
</SECTION>

24
validate/docs/plugins/gst-validate-plugins.sgml
View file

@ -1,24 +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;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GStreamer Validate Plugins &GST_API_VERSION; Plugins Reference Manual</title>
<releaseinfo>
for GStreamer Validate &GST_API_VERSION; (&GST_VERSION;)
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base/html/">http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-validate/html/</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
<title>gst-validate plugins</title>
<xi:include href="xml/ssim.xml" />
</chapter>
</book>

1
validate/docs/plugins/gst-validate-plugins.types
View file

@ -1 +0,0 @@
#include <gst/gst.h>

6
validate/docs/validate/.gitignore vendored
View file

@ -1,6 +0,0 @@
*.bak
*.stamp
html
xml
Makefile
Makefile.in

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

@ -1,101 +0,0 @@
GST_DOC_SCANOBJ = $(top_srcdir)/common/gstdoc-scangobj
## Process this file with automake to produce Makefile.in
# The name of the module, e.g. 'glib'.
MODULE=gst-validate
DOC_MODULE=gst-validate
# don't want $(DOC_MODULE)-scan.c to be built with -Werror
ERROR_CFLAGS=
# for upload-doc.mak
DOC=gst-validate
FORMATS=html
html: html-build.stamp
include $(top_srcdir)/common/upload-doc.mak
# The top-level SGML file. Change it if you want.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code.
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting functions and macros.
DOC_SOURCE_DIR=$(top_srcdir)/gst/validate/
# Extra options to supply to gtkdoc-scan.
SCAN_OPTIONS=--deprecated-guards="GST_DISABLE_DEPRECATED"
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-fixref.
FIXXREF_OPTIONS=--extra-dir=$(top_builddir)/docs/gst/html \
--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html \
--extra-dir=$(datadir)/gtk-doc/html
# Used for dependencies.
HFILE_GLOB=$(top_srcdir)/gst/validate/gst-validate-scenario.h
CFILE_GLOB=$(top_srcdir)/gst/validate/gst-validate-scenario.c
# Extra options to pass to gtkdoc-scanobj or gtkdoc-scangobj.
SCANOBJ_OPTIONS=--type-init-func="gst_init(&argc,&argv); gst_validate_init()"
# Header files to ignore when scanning.
IGNORE_HFILES = \
gettext.h \
gst-validate-internal.h \
gst-validate-monitor.h \
gst-validate-bin-monitor.h \
gst-validate-element-monitor.h \
gst-validate-pad-monitor.h \
gst-validate-override.h \
gst-validate-override-registry.h \
gst-validate-utils.h \
gst-validate-media-info.h \
gst-validate-report.h \
media-descriptor.h \
media-descriptor-parser.h \
media-descriptor-writer.h \
gst-validate-i18n-lib.h
IGNORE_CFILES = \
gst-validate-monitor.c \
gst-validate-bin-monitor.c \
gst-validate-pad-monitor.c \
gst-validate-element-monitor.c \
gst-validate-override.c \
gst-validate-override-registry.c \
gst-validate-utils.c \
gst-validate-report.c \
gst-validate-media-info.c \
media-descriptor.c \
media-descriptor-parser.c \
media-descriptor-writer.c \
gst-validate-i18n-lib.c
# Images to copy into HTML directory.
# HTML_IMAGES = gdp-header.png
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
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 =
# CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
# contains GtkObjects/GObjects and you want to document signals and properties.
GTKDOC_CFLAGS = -I$(top_srcdir) $(GST_PBUTILS_CFLAGS) $(GST_BASE_CFLAGS) \
$(GST_CFLAGS) $(GIO_CFLAGS) $(GCOV_CFLAGS)
GTKDOC_LIBS = \
$(top_builddir)/gst/validate/libgstvalidate-@GST_API_VERSION@.la \
$(GST_BASE_LIBS) $(GST_LIBS) $(GIO_LIBS) $(GCOV_LIBS)
GTKDOC_CC=$(LIBTOOL) --tag=CC --mode=compile $(CC)
GTKDOC_LD=$(LIBTOOL) --tag=CC --mode=link $(CC)
# If you need to override some of the declarations, place them in this file
# and uncomment this line.
DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
include $(top_srcdir)/common/gtk-doc.mak

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

@ -1,268 +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;
]>
<sect1 id="envvariables" revision="20 Apr 2015">
<title>GstValidate Environment Variables</title>
<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 information
and consider differently the level of the reported issues.
<variablelist>
<varlistentry>
<term>fatal-criticals</term>
<listitem><para>Causes GstValidate to consider only critical issues as import enough to consider the test failed (default behaviour)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fatal-warnings</term>
<listitem><para>Causes GstValidate to consider warning, and critical issues as import enough to consider the test failed</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fatal-issues</term>
<listitem><para>Causes GstValidate to consider issue, warning, and critical issues as import enough to consider 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 critical 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 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 <literal>stdout</literal> and <literal>stderr</literal> 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 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 <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>
<formalpara id="GST-VALIDATE-CONFIG">
<title><envar>GST_VALIDATE_CONFIG</envar></title>
<para>
Set this variable to a colon-separated list of paths to GstValidate config files or
directly as a string in the GstCaps serialization format.
The config file has a format similar to the scenario file. The name of the configuration
corresponds to the name of the plugin the configuration applies to.
</para>
<para>
The special name "core" is used to configure GstValidate core functionnalities
(monitors, scenarios, etc...).
</para>
<informalexample>
If you want to make sure to set a property on a element of a type
(for example to disable QoS on all sinks) you can do:
<programlisting>
core, action=set-property, target-element-klass=Sink
</programlisting>
</informalexample>
<informalexample>
If you want the GstPipeline to get dumped when an issue of a
certain level (and higher) happens, you can do:
<programlisting>
core, action=dot-pipeline, report-level=issue
</programlisting>
Note that you will still need to set <envar>GST_DEBUG_DUMP_DOT_DIR</envar>.
</informalexample>
<informalexample>
You can also check that a src pad is pushing buffers at a
minimum frequency. For example to check if <literal>v4l2src</literal> is
producing at least 60 frames per second you can do:
<programlisting>
core,min-buffer-frequency=60,target-element-factory-name=v4l2src
</programlisting>
This config accepts the following fields:
<itemizedlist>
<listitem>
<para><literal>min-buffer-frequency</literal>: the expected minimum
rate, in buffers per second, at which buffers are pushed on the pad
</para>
</listitem>
<listitem>
<para><literal>target-element-{factory-name,name,klass}</literal>:
the factory-name, object name or class of the element to check
</para>
</listitem>
<listitem>
<para><literal>name</literal>: (optional) only check the frequency if
the src pad has this name
</para>
</listitem>
<listitem>
<para><literal>buffer-frequency-start</literal>: (optional) if defined,
validate will ignore the frequency of the pad during the time specified
in this field, in ns.
This can be useful when testing live pipelines where
configuring and setting up elements can take some time slowing
down the first buffers until the pipeline reaches its cruising
speed.
</para>
</listitem>
</itemizedlist>
</informalexample>
<para>
For more examples you can look at the ssim GstValidate plugin documentation to
see how to configure that plugin.
</para>
</formalpara>
<formalpara id="GST-VALIDATE-OVERRIDE">
<title><envar>GST_VALIDATE_OVERRIDE</envar></title>
<para>
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 <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>
<formalpara id="GST-VALIDATE-WAIT-MULTIPLIER">
<title><envar>GST_VALIDATE_SCENARIO_WAIT_MULITPLIER</envar></title>
<para>
A decimal number to set as a multiplier for the wait actions. For example if you set
<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>
<formalpara id="GST-VALIDATE-REPORTING-DETAILS">
<title><envar>GST_VALIDATE_REPORTING_DETAILS</envar></title>
<para>
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:
<programlisting>
GST_VALIDATE_REPORTING_DETAILS=synthetic,h264parse:all
GST_VALIDATE_REPORTING_DETAILS=none,h264parse::sink_0:synthetic
</programlisting>
</informalexample>
<para>
Levels being:
</para>
<variablelist>
<varlistentry>
<term>none</term>
<listitem><para>No debugging level specified or desired. Used to deactivate debugging output.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
synthetic
</term>
<listitem>
<para>
Summary of the issues found, with no details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
subchain
</term>
<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 (<literal>my_object:subchain</literal>),
validate will report the issues where the object is the first to report an issue for
a subchain.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
monitor
</term>
<listitem>
<para>
If set as the default level, all the
distinct issues for all the monitors will be reported.
If set as the level for a particular object, all the distinct issues for this object
will be reported.
Note that if the same issue happens twice on the same object, up until this
level that issue is only reported once.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
all
</term>
<listitem>
<para>
All the issues will be reported, even those
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 <function>gst_validate_runner_printf()</function>.
</para>
</formalpara>
</sect1>

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

@ -1,83 +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;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GstValidate Reference Manual</title>
<releaseinfo>
for GstValidate &GST_API_VERSION;
</releaseinfo>
</bookinfo>
<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.
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 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 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 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 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="scenarios.xml"/>
<xi:include href="envvariables.xml"/>
</chapter>
<chapter>
<title>API Documentation</title>
<xi:include href="xml/validate.xml"/>
<xi:include href="xml/gst-validate-runner.xml"/>
<xi:include href="xml/gst-validate-scenario.xml"/>
<xi:include href="xml/gst-validate-reporter.xml"/>
<xi:include href="xml/gst-validate-monitor-factory.xml"/>
</chapter>
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="deprecated-api-index" role="deprecated">
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

194
validate/docs/validate/gst-validate-launcher.xml
View file

@ -1,194 +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="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>
<command>gst-validate-launcher</command> allows specifying that a local media file should also be tested in push mode.
To do so you will need to generate (or symlink) a media info file with the extension <filename>.media_info.push</filename>.
In that case a "pushfile" source will be used instead of the usual "filesource".
</para>
<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
View file

@ -1,89 +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="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>

94
validate/docs/validate/gst-validate-sections.txt
View file

@ -1,94 +0,0 @@
<SECTION>
<FILE>validate</FILE>
<TITLE>Initialization</TITLE>
gst_validate_init
</SECTION>
<SECTION>
<FILE>gst-validate-monitor-factory</FILE>
<TITLE>GstValidate monitoring system</TITLE>
gst_validate_monitor_factory_create
</SECTION>
<SECTION>
<FILE>gst-validate-runner</FILE>
<TITLE>GstValidateRunner</TITLE>
GstValidateRunner
GstValidateRunnerClass
gst_validate_runner_new
gst_validate_runner_get_reports_count
gst_validate_runner_printf
<SUBSECTION Private>
gst_validate_runner_get_reports
gst_validate_runner_add_report
<SUBSECTION Standard>
GST_IS_VALIDATE_RUNNER
GST_VALIDATE_RUNNER_CAST
GST_VALIDATE_RUNNER_CLASS_CAST
GST_IS_VALIDATE_RUNNER_CLASS
GST_TYPE_VALIDATE_RUNNER
GST_VALIDATE_RUNNER
GST_VALIDATE_RUNNER_CLASS
GST_VALIDATE_RUNNER_GET_CLASS
gst_validate_runner_get_type
</SECTION>
<SECTION>
<FILE>gst-validate-scenario</FILE>
<TITLE>GstValidateScenario</TITLE>
GstValidateExecuteAction
GstValidateAction
GstValidateActionParameter
GstValidateScenario
GstValidateScenarioClass
gst_validate_print_action_types
gst_validate_list_scenarios
gst_validate_register_action_type
gst_validate_action_get_clocktime
gst_validate_scenario_execute_seek
gst_validate_action_set_done
gst_validate_action_get_scenario
GstValidateActionType
<SUBSECTION Private>
gst_validate_scenario_factory_create
<SUBSECTION Standard>
GST_IS_VALIDATE_ACTION
GST_IS_VALIDATE_ACTION_TYPE
GST_IS_VALIDATE_SCENARIO
GST_IS_VALIDATE_SCENARIO_CLASS
GST_TYPE_VALIDATE_ACTION
GST_TYPE_VALIDATE_ACTION_TYPE
GST_TYPE_VALIDATE_SCENARIO
GST_VALIDATE_ACTION_TYPE
GST_VALIDATE_SCENARIO
GST_VALIDATE_SCENARIO_CLASS
GST_VALIDATE_SCENARIO_GET_CLASS
GstValidateScenarioPrivate
gst_validate_action_get_type
gst_validate_action_type_get_type
gst_validate_scenario_get_type
</SECTION>
<SECTION>
<FILE>gst-validate-report</FILE>
<TITLE>GstValidate reporting system</TITLE>
GstValidateIssue
gst_validate_issue_new
GstValidateReport
</SECTION>
<SECTION>
<FILE>gst-validate-reporter</FILE>
<TITLE>GstValidateReporter</TITLE>
GstValidateReporter
GST_VALIDATE_REPORT
gst_validate_reporter_set_handle_g_logs
gst_validate_report
gst_validate_reporter_get_reports_count
<SUBSECTION Standard>
GST_TYPE_VALIDATE_REPORTER
GST_VALIDATE_REPORTER
GST_IS_VALIDATE_REPORTER
GST_VALIDATE_REPORTER_GET_INTERFACE
GST_VALIDATE_REPORTER_CAST
</SECTION>

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

@ -1,220 +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="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,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>

10
validate/docs/validate/gst-validate.types
View file

@ -1,10 +0,0 @@
#include <gst/gst.h>
#include <gst/validate/validate.h>
#include <gst/validate/gst-validate-scenario.h>
gst_validate_action_get_type
gst_validate_action_type_get_type
gst_validate_report_get_type
gst_validate_reporter_get_type
gst_validate_runner_get_type
gst_validate_scenario_get_type

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

@ -1,139 +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="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>

32
validate/docs/validate/meson.build
View file

@ -1,32 +0,0 @@
types = configure_file(input : 'gst-validate.types',
output : 'gst-validate.types',
copy: true)
doc_deps_names = ['glib-2.0',
'gstreamer-@0@'.format(apiversion),
'gstreamer-plugins-base-@0@'.format(apiversion)]
doc_deps = []
foreach doc_dep : doc_deps_names
# FIXME: use get_pkgconfig_variable() instead
runcmd = run_command('pkg-config', '--variable=prefix', doc_dep)
if runcmd.returncode() == 0
tmp = '--extra-dir=' + runcmd.stdout().strip() + '/share/gtk-doc/html/'
tmp.strip()
doc_deps = doc_deps + [tmp]
endif
endforeach
gnome.gtkdoc('gst-validate',
main_sgml : 'gst-validate-docs.sgml',
src_dir : '@0@/../../gst/validate'.format(meson.current_source_dir()),
scan_args : ['--deprecated-guards=GST_DISABLE_DEPRECATED',
'--ignore-decorators=GST_VALIDATE_API',
'--ignore-headers=gettext.h gst-validate-internal.h gst-validate-monitor.h gst-validate-bin-monitor.h gst-validate-element-monitor.h gst-validate-pad-monitor.h gst-validate-override.h gst-validate-override-registry.h gst-validate-utils.h gst-validate-media-info.h gst-validate-report.h media-descriptor.h media-descriptor-parser.h media-descriptor-writer.h gst-validate-i18n-lib.h'
],
scanobjs_args : ['--type-init-func="gst_init(NULL,NULL)"'],
gobject_typesfile : types,
dependencies : [validate_dep],
content_files : ['gst-validate.xml', 'gst-validate-transcoding.xml', 'gst-validate-media-check.xml', 'gst-validate-launcher.xml', 'envvariables.xml', 'scenarios.xml'],
fixxref_args: doc_deps + ['--html-dir=' + get_option('prefix') + '/share/gtk-doc/html/'],
install : true)

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

@ -1,143 +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;
]>
<sect1 id="scenarios" revision="20 Apr 2015">
<title>GstValidate Scenario File Format</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 <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>

2
validate/docs/version.entities.in
View file

@ -1,2 +0,0 @@
<!ENTITY GST_API_VERSION "@GST_API_VERSION@">
<!ENTITY GST_VERSION "@VERSION@">

13
validate/gst/validate/gst-validate-report.h
View file

@ -38,6 +38,16 @@ GST_VALIDATE_API
GType gst_validate_report_get_type (void);
#define GST_TYPE_VALIDATE_REPORT (gst_validate_report_get_type ())
/**
* GstValidateDebugFlags:
* GST_VALIDATE_FATAL_DEFAULT:
* GST_VALIDATE_FATAL_ISSUES:
* GST_VALIDATE_FATAL_WARNINGS:
* GST_VALIDATE_FATAL_CRITICALS:
* GST_VALIDATE_PRINT_ISSUES:
* GST_VALIDATE_PRINT_WARNINGS:
* GST_VALIDATE_PRINT_CRITICALS:
*/
typedef enum {
GST_VALIDATE_FATAL_DEFAULT = 0,
GST_VALIDATE_FATAL_ISSUES = 1 << 0,
@ -48,6 +58,9 @@ typedef enum {
GST_VALIDATE_PRINT_CRITICALS = 1 << 5
} GstValidateDebugFlags;
/**
* GstValidateReportLevel:
*/
typedef enum {
GST_VALIDATE_REPORT_LEVEL_CRITICAL,
GST_VALIDATE_REPORT_LEVEL_WARNING,

8
validate/gst/validate/gst-validate-scenario.h
View file

@ -40,6 +40,14 @@ G_BEGIN_DECLS
typedef struct _GstValidateScenarioPrivate GstValidateScenarioPrivate;
typedef struct _GstValidateActionParameter GstValidateActionParameter;
/**
* GstValidateActionReturn:
* GST_VALIDATE_EXECUTE_ACTION_ERROR:
* GST_VALIDATE_EXECUTE_ACTION_OK:
* GST_VALIDATE_EXECUTE_ACTION_ASYNC:
* GST_VALIDATE_EXECUTE_ACTION_INTERLACED:
* GST_VALIDATE_EXECUTE_ACTION_ERROR_REPORTED:
*/
typedef enum
{
GST_VALIDATE_EXECUTE_ACTION_ERROR,

3
validate/gst/validate/media-descriptor-writer.h
View file

@ -56,6 +56,9 @@ typedef struct {
} GstValidateMediaDescriptorWriterClass;
/**
* GstValidateMediaDescriptorWriterFlags
*/
typedef enum
{
GST_VALIDATE_MEDIA_DESCRIPTOR_WRITER_FLAGS_NONE = 1 << 0,

5
validate/gst/validate/meson.build
View file

@ -77,7 +77,7 @@ gstvalidatetracer = library('gstvalidatetracer',
validate_gen_sources = []
if build_gir
gst_validate_gir_extra_args = gir_init_section + [ '--c-include=gst/validate/validate.h' ]
validate_gen_sources = [gnome.generate_gir(gstvalidate,
validate_gir = gnome.generate_gir(gstvalidate,
sources : gstvalidate_sources + gstvalidate_headers + gst_validate_enums,
nsversion : '1.0',
namespace : 'GstValidate',
@ -93,7 +93,8 @@ if build_gir
install : true,
dependencies : [gst_dep, gstbase_dep, glib_dep, gio_dep, gst_pbutils_dep],
extra_args : gst_validate_gir_extra_args,
)]
)
validate_gen_sources += [validate_gir]
endif
validate_dep = declare_dependency(link_with : gstvalidate,

10
validate/meson.build
View file

@ -27,16 +27,6 @@ subdir('gst')
subdir('gst-libs')
subdir('launcher')
subdir('tools')
if build_machine.system() == 'windows'
message('Disabling gtk-doc while building on Windows')
else
gtkdoc = find_program('gtkdoc-scan', required : get_option('gtk_doc'))
if gtkdoc.found()
subdir('docs')
else
message('Not building documentation as gtk-doc was not found')
endif
endif
subdir('pkgconfig')
if not get_option('tests').disabled()
subdir('tests')

80
validate/plugins/ssim/gstvalidatessim.c
View file

@ -20,86 +20,6 @@
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION:validate-ssim
* @short_description: GstValidate plugin to detect frame corruptions
*
* GstValidate plugin to run the ssim algorithm on the buffers flowing in the
* pipeline to find regressions and detect frame corruptions.
* It allows you to generate image files from the buffers flowing in the pipeline
* (either as raw in the many formats supported by GStreamer or as png) and then
* check them against pre generated, reference images.
*
* The ssim algorithm will set a value of 1.0 when images are perfectly identical,
* and -1.0 if they have nothing in common. By default we consider images as similar
* if they have at least a ssim value of 0.95 but you can override it defining the value
* under which the test will be considered as failed.
*
* Errors are reported on the GstValidate reporting system. You can also ask
* the plugin to generate grey scale output images. Those will be named in a way
* that should lets you precisely see where and how the test failed.
*
* # Configuration
*
* The configuration of the plugin is done through a validate configuration file,
* specified with the %GST_VALIDATE_CONFIG environment variable. Each line starting
* with 'ssim,' will configure the ssim plugin. In practice each configuration statement
* will lead to the creation of a #GstValidateOverride object which will then dump
* image files and if wanted compare those with a set of reference images.
*
* The following parameters can be passed in the configuration file:
* - element-classification: The target element classification as define in
* gst_element_class_set_metadata
* - output-dir: The directory in which the image files will be saved
* - min-avg-priority: (default 0.95): The minimum average similarity
* under which we consider the test as failing
* - min-lowest-priority: (default 1): The minimum 'lowest' similarity
* under which we consider the test as failing
* - reference-images-dir: Define the directory in which the files to be
* compared can be found
* - result-output-dir: The folder in which to store resulting grey scale
* images when the test failed. In that folder you will find images
* with the structural difference between the expected result and the actual
* result.
* - output-video-format: The format in which you want the images to be saved
* - reference-video-format: The format in which the reference images are stored
* - check-recurrence: The recurrence in seconds (as float) the frames should
* be dumped and checked.By default it is GST_CLOCK_TIME_NONE, meaning each
* and every frame is checked. Not that in any case, after a discontinuity
* in the stream (after a seek or a change in the video format for example)
* a check is done. And if recurrence == 0, images will be checked only after
* such discontinuity
* - is-config: Property letting the plugin know that the config line is exclusively
* used to configure the following configuration expressions. In practice this
* means that it will change the default values for the other configuration
* expressions.
*
* # Example #
*
* Let's take a special configuration where we want to compare frames that are
* outputted by a video decoder with the ones after a agingtv element we would
* call my_agingtv. We force to check one frame every 5.0 seconds only (with
* check-recurrence=5.0) so the test is fast.
*
* The configuration file:
* |[
* core, action=set-property, target-element-klass=Sink, property-name=sync, property-value=false
*
* ssim, is-config=true, output-video-format="I420", reference-video-format="I420"
* ssim, element-classification="Video/Decoder", output-dir=/tmp/test/before-agingtv/
* ssim, element-name=my_agingtv, output-dir=/tmp/test/after-agingtv/, \
* reference-images-dir=/tmp/test/before-agingtv/, \
* result-output-dir=/tmp/test/failures, check-recurrence=5.0
* ]|
*
* Save that content in a file called check_agingtv_ssim.config
*
* ## Launch the pipeline
* |[
* GST_VALIDATE_CONFIG=check_agingtv_ssim.config gst-validate-1.0-debug uridecodebin uri=file://a/file ! videoconvert ! agingtv name=my_agingtv ! videoconvert ! autovideosink
* ]|
*/
#define _GNU_SOURCE
#ifdef HAVE_CONFIG_H