Ideally we want a GstValidate hotdoc plugin... not for now.
--- /dev/null
+# 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.
--- /dev/null
+# GstValidate API reference
--- /dev/null
+---
+title: Configuration
+short-description: GstValidate configuration
+...
+
+# GstValidate Configuration
+
+GstValidate comes with some possible configuration files
+to setup its plugins (and potentially core behaviour).
--- /dev/null
+---
+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/
--- /dev/null
+---
+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
--- /dev/null
+---
+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.
--- /dev/null
+---
+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
+
--- /dev/null
+---
+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`.
--- /dev/null
+---
+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.
--- /dev/null
+# 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.
--- /dev/null
+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],
+)]
--- /dev/null
+# GstValidate plugins
+
+GstValidate offers a plugin system to extend the checks and add new functionnality
\ No newline at end of file
--- /dev/null
+---
+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
+```
--- /dev/null
+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
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' ])
plugins_pkgconfig_install_dir = disabler()
endif
+plugins = []
i18n = import('i18n')
python_mod = import('python')
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")')
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.')
-DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
-
SUBDIRS = \
common \
data \
launcher \
tools \
pkgconfig \
- docs \
tests \
po
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 ***
launcher/Makefile
launcher/apps/Makefile
launcher/testsuites/Makefile
-docs/Makefile
-docs/version.entities
-docs/validate/Makefile
-docs/plugins/Makefile
-docs/launcher/Makefile
])
AC_OUTPUT
+++ /dev/null
-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
+++ /dev/null
-# 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
+++ /dev/null
-# -*- 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'
+++ /dev/null
-.. 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`
-
+++ /dev/null
-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:
-
+++ /dev/null
-.
-=
-
-.. toctree::
- :maxdepth: 4
-
- launcher
+++ /dev/null
-subdir('validate')
-# subdir('launcher')
+++ /dev/null
-*.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
-
+++ /dev/null
-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
-
+++ /dev/null
-<?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>
-
-
+++ /dev/null
-<SECTION>
-<FILE>validate-ssim</FILE>
-<TITLE>Validate SSim plugin</TITLE>
-VALIDATE_TYPE_S_SIM_OVERRIDE
-ValidateSSimOverrideClass
-validate_s_sim_override_new
-ValidateSSimOverride
-</SECTION>
-
+++ /dev/null
-<?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>
-
-
+++ /dev/null
-#include <gst/gst.h>
+++ /dev/null
-*.bak
-*.stamp
-html
-xml
-Makefile
-Makefile.in
+++ /dev/null
-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
-
+++ /dev/null
-<?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>
+++ /dev/null
-<?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>
+++ /dev/null
-<?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>
+++ /dev/null
-<?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>
+++ /dev/null
-<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>
+++ /dev/null
-<?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>
+++ /dev/null
-#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
+++ /dev/null
-<?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>
+++ /dev/null
-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)
+++ /dev/null
-<?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>
+++ /dev/null
-<!ENTITY GST_API_VERSION "@GST_API_VERSION@">
-<!ENTITY GST_VERSION "@VERSION@">
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,
GST_VALIDATE_PRINT_CRITICALS = 1 << 5
} GstValidateDebugFlags;
+/**
+ * GstValidateReportLevel:
+ */
typedef enum {
GST_VALIDATE_REPORT_LEVEL_CRITICAL,
GST_VALIDATE_REPORT_LEVEL_WARNING,
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,
} GstValidateMediaDescriptorWriterClass;
+/**
+ * GstValidateMediaDescriptorWriterFlags
+ */
typedef enum
{
GST_VALIDATE_MEDIA_DESCRIPTOR_WRITER_FLAGS_NONE = 1 << 0,
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',
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,
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')
* 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
projects / platform / upstream / gstreamer.git / commitdiff