From ec291ce6bb239db75ee7a7b7af1275f36374f5c7 Mon Sep 17 00:00:00 2001
From: Thibault Saunier <tsaunier@igalia.com>
Date: Fri, 16 Sep 2022 22:05:18 -0300
Subject: [PATCH] validate: Update action types documentation
Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3040>
---
.../docs/gst-validate-action-types.md | 444 +++++++++++++++---
.../gst/validate/gst-validate-scenario.c | 53 ++-
2 files changed, 409 insertions(+), 88 deletions(-)
diff --git a/subprojects/gst-devtools/docs/gst-validate-action-types.md b/subprojects/gst-devtools/docs/gst-validate-action-types.md
index 65c3105f07..ca6d20ab9f 100644
--- a/subprojects/gst-devtools/docs/gst-validate-action-types.md
+++ b/subprojects/gst-devtools/docs/gst-validate-action-types.md
@@ -1,10 +1,10 @@
# GstValidate action types
-
## meta
``` validate-scenario
meta,
+ [allow-errors=(boolean)],
[duration=(double, int)],
[handles-states=(boolean)],
[ignore-eos=(boolean)],
@@ -28,6 +28,13 @@ NOTE: it used to be called "description"
### Parameters
+* `allow-errors`:(optional): Ignore error messages and keep executing the
+scenario when it happens. By default a 'stop' action is generated on ERROR messages
+
+ Possible types: `boolean`
+
+ Default: false
+
* `duration`:(optional): Lets the user know the time the scenario needs to be fully executed
Possible types: `double, int`
@@ -407,9 +414,14 @@ int: To use the actual index to use`
``` validate-scenario
wait,
+ [check=(structure)],
[duration=(double or string (GstClockTime))],
+ [expected-values=(structure)],
[message-type=(string)],
+ [non-blocking=(string)],
+ [on-clock=(boolean)],
[signal-name=(string)],
+ [target-element-factory-name=(string)],
[target-element-name=(string)],
[playback-time=(double,string)];
```
@@ -419,19 +431,51 @@ Waits for signal 'signal-name', message 'message-type', or during 'duration' sec
### Parameters
+* `check`:(optional): The check action to execute when non blocking signal is received
+
+ Possible types: `structure`
+
+ Default: (null)
+
* `duration`:(optional): the duration while no other action will be executed
Possible types: `double or string (GstClockTime)`
Default: (null)
+* `expected-values`:(optional): Expected values in the message structure (valid only when `message-type`). Example: wait, on-client=true, message-type=buffering, expected-values=[values, buffer-percent=100]
+
+ Possible types: `structure`
+
+ Default: (null)
+
* `message-type`:(optional): The name of the message type to wait for (on @target-element-name if specified)
Possible types: `string`
Default: (null)
-* `signal-name`:(optional): The name of the signal to wait for on @target-element-name
+* `non-blocking`:(optional): **Only for signals**.Make the action non blocking meaning that next actions will be
+executed without waiting for the signal to be emitted.
+
+ Possible types: `string`
+
+ Default: (null)
+
+* `on-clock`:(optional): Wait until the test clock gets a new pending entry.
+See #gst_test_clock_wait_for_next_pending_id.
+
+ Possible types: `boolean`
+
+ Default: (null)
+
+* `signal-name`:(optional): The name of the signal to wait for on @target-element-name. To ensure that the signal is executed without blocking while waiting for it you can set the field 'non-blocking=true'.
+
+ Possible types: `string`
+
+ Default: (null)
+
+* `target-element-factory-name`:(optional): The name factory for which to wait @signal-name on
Possible types: `string`
@@ -521,6 +565,24 @@ Changes the ranking of a particular plugin feature(s)
Possible types: `string, int`
+## remove-feature
+
+
+``` validate-scenario
+remove-feature,
+ name=(string);
+```
+
+Remove a plugin feature(s) or a plugin from the registry
+ * Implementer namespace: core
+ * Is config action (meaning it will be executing right at the beginning of the execution of the pipeline)
+
+### Parameters
+
+* `name`:(mandatory): The name of a GstFeature or GstPlugin to remove
+
+ Possible types: `string`
+
## set-feature-rank
@@ -558,7 +620,7 @@ Changes the state of the pipeline to any GstState
### Parameters
-* `state`:(mandatory): A GstState as a string, should be in:
+* `state`:(mandatory): A GstState as a string, should be in:
* ['null', 'ready', 'paused', 'playing']
Possible types: `string`
@@ -603,6 +665,160 @@ For example you can define vars for buffer checksum to be used in the "check-las
### Parameters
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+ Possible variables:
+
+ * `position`: The current position in the stream
+
+ * `duration`: The duration of the stream
+
+ Possible types: `double,string`
+
+ Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+ Possible types: `string`
+
+ Default: (null)
+
+## set-timed-value-properties
+
+
+``` validate-scenario
+set-timed-value-properties,
+ timestamp=(string or float (GstClockTime)),
+ [binding-type=(string)],
+ [interpolation-mode=(string)],
+ [source-type=(string)],
+ [playback-time=(double,string)];
+```
+
+Sets GstTimedValue on pads on elements properties using GstControlBindings
+and GstControlSource as defined in the parameters.
+The properties values to set will be defined as:
+
+```
+element-name.padname::property-name=new-value
+```
+
+> NOTE: `.padname` is not needed if setting a property on an element
+
+This action also adds necessary control source/control bindings.
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `timestamp`:(mandatory): The timestamp of the keyframe
+
+ Possible types: `string or float (GstClockTime)`
+
+* `binding-type`:(optional): The name of the type of binding to use
+
+ Possible types: `string`
+
+ Default: direct
+
+* `interpolation-mode`:(optional): The name of the GstInterpolationMode to set on the source
+
+ Possible types: `string`
+
+ Default: linear
+
+* `source-type`:(optional): The name of the type of ControlSource to use
+
+ Possible types: `string`
+
+ Default: GstInterpolationControlSource
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+ Possible variables:
+
+ * `position`: The current position in the stream
+
+ * `duration`: The duration of the stream
+
+ Possible types: `double,string`
+
+ Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+ Possible types: `string`
+
+ Default: (null)
+
+## check-properties
+
+
+``` validate-scenario
+check-properties,
+ [playback-time=(double,string)];
+```
+
+Check elements and pads properties values.
+The properties values to check will be defined as:
+
+```
+element-name.padname::property-name
+```
+
+> NOTE: `.padname` is not needed if checking an element property
+
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+ Possible variables:
+
+ * `position`: The current position in the stream
+
+ * `duration`: The duration of the stream
+
+ Possible types: `double,string`
+
+ Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+ Possible types: `string`
+
+ Default: (null)
+
+## set-properties
+
+
+``` validate-scenario
+set-properties,
+ [playback-time=(double,string)];
+```
+
+Set elements and pads properties values.
+The properties values to set will be defined as:
+
+```
+ element-name.padname::property-name
+```
+
+> NOTE: `.padname` is not needed if set an element property
+
+
+ * Implementer namespace: core
+
+### Parameters
+
* `playback-time`:(optional): The playback time at which the action will be executed
Possible variables:
@@ -630,6 +846,7 @@ For example you can define vars for buffer checksum to be used in the "check-las
set-property,
property-name=(string),
property-value=(The same type of @property-name),
+ [on-all-instances=(boolean)],
[target-element-factory-name=(string)],
[target-element-klass=(string)],
[target-element-name=(string)],
@@ -651,6 +868,12 @@ Besides property-name and value, either 'target-element-name' or
Possible types: `The same type of @property-name`
+* `on-all-instances`:(optional): Whether to set property on all instances matching the requirements
+
+ Possible types: `boolean`
+
+ Default: (null)
+
* `target-element-factory-name`:(optional): The name factory for which to set a property on built elements
Possible types: `string`
@@ -806,6 +1029,7 @@ See gst_debug_set_threshold_from_string
emit-signal,
signal-name=(string),
target-element-name=(string),
+ [params=(ValueArray)],
[playback-time=(double,string)];
```
@@ -822,6 +1046,12 @@ Emits a signal to an element in the pipeline
Possible types: `string`
+* `params`:(optional): The signal parameters
+
+ Possible types: `ValueArray`
+
+ Default: (null)
+
* `playback-time`:(optional): The playback time at which the action will be executed
Possible variables:
@@ -1107,11 +1337,8 @@ Checks the last-sample checksum or frame number (set on its GstVideoTimeCodeMet
``` validate-scenario
crank-clock,
- [checksum=(string)],
[expected-elapsed-time=(GstClockTime)],
[expected-time=(GstClockTime)],
- [sinkpad-caps=(string)],
- [timecode-frame-number=(string)],
[playback-time=(double,string)];
```
@@ -1120,12 +1347,6 @@ Crank the clock, possibly checking how much time was supposed to be waited on th
### Parameters
-* `checksum`:(optional): The reference checksum of the buffer.
-
- Possible types: `string`
-
- Default: (null)
-
* `expected-elapsed-time`:(optional): Check time elapsed during the clock cranking
Possible types: `GstClockTime`
@@ -1138,18 +1359,6 @@ Crank the clock, possibly checking how much time was supposed to be waited on th
Default: (null)
-* `sinkpad-caps`:(optional): The caps (as string) of the sink to check.
-
- Possible types: `string`
-
- Default: (null)
-
-* `timecode-frame-number`:(optional): The frame number of the buffer as specified on its GstVideoTimeCodeMeta
-
- Possible types: `string`
-
- Default: (null)
-
* `playback-time`:(optional): The playback time at which the action will be executed
Possible variables:
@@ -1278,14 +1487,6 @@ If not set, GST_CLOCK_TIME_NONE will be used so upstream elements will produce a
``` validate-scenario
check-position,
expected-position=(GstClockTime),
- [all-headers=(boolean)],
- [count=(int)],
- [pad=(string)],
- [running-time=(double or string)],
- [srcpad=(string)],
- [target-element-factory-name=(string)],
- [target-element-klass=(string)],
- [target-element-name=(string)],
[playback-time=(double,string)];
```
@@ -1299,54 +1500,75 @@ Check current pipeline position.
Possible types: `GstClockTime`
-* `all-headers`:(optional): TRUE to produce headers when starting a new key unit
-
- Possible types: `boolean`
-
- Default: FALSE
-
-* `count`:(optional): integer that can be used to number key units
-
- Possible types: `int`
-
- Default: 0
-
-* `pad`:(optional): The name of the GstPad to send a send force-key-unit to
-
- Possible types: `string`
-
- Default: sink
-
-* `running-time`:(optional): The running_time can be set to request a new key unit at a specific running_time.
-If not set, GST_CLOCK_TIME_NONE will be used so upstream elements will produce a new key unit as soon as possible.
+* `playback-time`:(optional): The playback time at which the action will be executed
Possible variables:
- * position: The current position in the stream
+ * `position`: The current position in the stream
- * duration: The duration of the stream
+ * `duration`: The duration of the stream
- Possible types: `double or string`
+ Possible types: `double,string`
- Default: (null)
+ Default: 0.0
-* `srcpad`:(optional): The name of the GstPad to send a send force-key-unit to
-
- Possible types: `string`
-
- Default: src
-
-* `target-element-factory-name`:(optional): The factory name of the GstElements to send a send force-key-unit to
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
Possible types: `string`
Default: (null)
-* `target-element-klass`:(optional): The klass of the GstElements to send a send force-key-unit to
+## check-current-pad-caps
+
+
+``` validate-scenario
+check-current-pad-caps,
+ [comparison-type=(string in [intersect, equal])],
+ [expected-caps=(caps,structure)],
+ [pad=(string)],
+ [target-element-factory-name=(string)],
+ [target-element-klass=(string)],
+ [target-element-name=(string)],
+ [playback-time=(double,string)];
+```
+
+Check currently set caps on a particular pad.
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `comparison-type`:(optional): __No description__
+
+ Possible types: `string in [intersect, equal]`
+
+ Default: (null)
+
+* `expected-caps`:(optional): The expected caps. If not present, expected no caps to be set
+
+ Possible types: `caps,structure`
+
+ Default: (null)
+
+* `pad`:(optional): The name of the GstPad to get pad from
Possible types: `string`
- Default: Video/Encoder
+ Default: (null)
+
+* `target-element-factory-name`:(optional): The factory name of the GstElements to get pad from
+
+ Possible types: `string`
+
+ Default: (null)
+
+* `target-element-klass`:(optional): The klass of the GstElements to get pad from
+
+ Possible types: `string`
+
+ Default: (null)
* `target-element-name`:(optional): The name of the GstElement to send a send force-key-unit to
@@ -1374,6 +1596,98 @@ If not set, GST_CLOCK_TIME_NONE will be used so upstream elements will produce a
Default: (null)
+## run-command
+
+
+``` validate-scenario
+run-command,
+ argv=((string){array,}),
+ [env=(structure)],
+ [playback-time=(double,string)];
+```
+
+Run an external command.
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `argv`:(mandatory): The subprocess arguments, include the program name itself
+
+ Possible types: `(string){array,}`
+
+* `env`:(optional): Extra environment variables to set
+
+ Possible types: `structure`
+
+ Default: (null)
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+ Possible variables:
+
+ * `position`: The current position in the stream
+
+ * `duration`: The duration of the stream
+
+ Possible types: `double,string`
+
+ Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+ Possible types: `string`
+
+ Default: (null)
+ optional : Don't raise an error if this action hasn't been executed or failed
+ ### Possible types:
+ boolean
+ Default: false
+
+## foreach
+
+
+``` validate-scenario
+foreach,
+ actions=({array of [structures]}),
+ [playback-time=(double,string)];
+```
+
+Run actions defined in the `actions` array the number of times specified
+with an iterator parameter passed in. The iterator can be
+a range like: `i=[start, end, step]` or array of values
+such as: `values=<value1, value2>`.
+One and only one iterator field is supported as parameter.
+ * Implementer namespace: core
+
+### Parameters
+
+* `actions`:(mandatory): The array of actions to repeat
+
+ Possible types: `{array of [structures]}`
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+ Possible variables:
+
+ * `position`: The current position in the stream
+
+ * `duration`: The duration of the stream
+
+ Possible types: `double,string`
+
+ Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+ Possible types: `string`
+
+ Default: (null)
+
## corrupt-socket-recv
diff --git a/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c b/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c
index c15fba1c20..2bca7d3bb1 100644
--- a/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c
+++ b/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c
@@ -6715,8 +6715,8 @@ register_action_types (void)
},
{
.name = "allow-errors",
- .description = "Ignore error messages and keep executing the scenario when it happens.\n By default "
- "a 'stop' action is generated one ERROR messages",
+ .description = "Ignore error messages and keep executing the\n"
+ "scenario when it happens. By default a 'stop' action is generated on ERROR messages",
.mandatory = FALSE,
.types = "boolean",
.possible_variables = NULL,
@@ -6882,7 +6882,8 @@ register_action_types (void)
{
.name = "non-blocking",
.description = "**Only for signals**."
- " Ensures that the signal is emitted without a blocking waiting.",
+ "Make the action non blocking meaning that next actions will be\n"
+ "executed without waiting for the signal to be emitted.",
.mandatory = FALSE,
.types = "string",
NULL
@@ -6901,13 +6902,13 @@ register_action_types (void)
"`message-type`). Example: "
"wait, on-client=true, message-type=buffering, expected-values=[values, buffer-percent=100]",
.mandatory = FALSE,
- .types = "GstStructure",
+ .types = "structure",
NULL
},
{
.name = "on-clock",
- .description = "Wait until the test clock get a new pending entry"
- " see #gst_test_clock_wait_for_next_pending_id.",
+ .description = "Wait until the test clock gets a new pending entry.\n"
+ "See #gst_test_clock_wait_for_next_pending_id.",
.mandatory = FALSE,
.types = "boolean",
NULL
@@ -7029,7 +7030,7 @@ register_action_types (void)
},
{
.name = "interpolation-mode",
- .description = "The name of the GstInterpolationMode to on the source",
+ .description = "The name of the GstInterpolationMode to set on the source",
.types = "string",
.mandatory = FALSE,
.def = "linear",
@@ -7042,10 +7043,12 @@ register_action_types (void)
},
{NULL}
}),
- "Sets GstTimedValue on pads on elements properties using GstControlBindings \n"
+ "Sets GstTimedValue on pads on elements properties using GstControlBindings\n"
"and GstControlSource as defined in the parameters.\n"
"The properties values to set will be defined as:\n\n"
- " element-name.padname::property-name=new-value\n\n"
+ "```\n"
+ "element-name.padname::property-name=new-value\n"
+ "```\n\n"
"> NOTE: `.padname` is not needed if setting a property on an element\n\n"
"This action also adds necessary control source/control bindings.\n",
GST_VALIDATE_ACTION_TYPE_NONE);
@@ -7056,7 +7059,9 @@ register_action_types (void)
}),
"Check elements and pads properties values.\n"
"The properties values to check will be defined as:\n\n"
- " element-name.padname::property-name\n\n"
+ "```\n"
+ "element-name.padname::property-name\n"
+ "```\n\n"
"> NOTE: `.padname` is not needed if checking an element property\n\n",
GST_VALIDATE_ACTION_TYPE_CHECK);
@@ -7066,8 +7071,10 @@ register_action_types (void)
}),
"Set elements and pads properties values.\n"
"The properties values to set will be defined as:\n\n"
- " element-name.padname::property-name\n\n"
- "> NOTE: `.padname` is not needed if checking an element property\n\n",
+ "```\n"
+ " element-name.padname::property-name\n"
+ "```\n\n"
+ "> NOTE: `.padname` is not needed if set an element property\n\n",
GST_VALIDATE_ACTION_TYPE_NONE);
REGISTER_ACTION_TYPE ("set-property", _execute_set_or_check_property,
@@ -7192,7 +7199,7 @@ register_action_types (void)
},
{
.name = "params",
- .description = "The signal parametters",
+ .description = "The signal parameters",
.mandatory = FALSE,
.types = "ValueArray",
NULL
@@ -7465,7 +7472,7 @@ register_action_types (void)
.name = "expected-caps",
.description = "The expected caps. If not present, expected no caps to be set",
.mandatory = FALSE,
- .types = "GstCaps,GstStructure",
+ .types = "caps,structure",
NULL
},
{
@@ -7505,14 +7512,14 @@ register_action_types (void)
},
{NULL}
}),
- "Check current pipeline position.\n",
+ "Check currently set caps on a particular pad.\n",
GST_VALIDATE_ACTION_TYPE_NONE | GST_VALIDATE_ACTION_TYPE_CHECK );
REGISTER_ACTION_TYPE("run-command", _run_command,
((GstValidateActionParameter[]) {
{
.name = "argv",
- .description = "The subprocess arguments",
+ .description = "The subprocess arguments, include the program name itself",
.mandatory = TRUE,
.types = "(string){array,}",
NULL
@@ -7521,12 +7528,12 @@ register_action_types (void)
.name = "env",
.description = "Extra environment variables to set",
.mandatory = FALSE,
- .types = "GstStructure",
+ .types = "structure",
NULL
},
{NULL}
}),
- "Run external command.\n",
+ "Run an external command.\n",
GST_VALIDATE_ACTION_TYPE_CAN_BE_OPTIONAL);
REGISTER_ACTION_TYPE("foreach", NULL,
@@ -7534,14 +7541,14 @@ register_action_types (void)
{ .name = "actions",
.description = "The array of actions to repeat",
.mandatory = TRUE,
- .types = "strv",
+ .types = "{array of [structures]}",
NULL },
{ NULL } }),
"Run actions defined in the `actions` array the number of times specified\n"
- " with an iterator parameter passed in. The iterator can be\n"
- " a range like :`i=[start, end, step]` or array of values\n"
- " such as: `values=<value1, value2>`.\n"
- "One and only iterator field is required as parameter.",
+ "with an iterator parameter passed in. The iterator can be\n"
+ "a range like: `i=[start, end, step]` or array of values\n"
+ "such as: `values=<value1, value2>`.\n"
+ "One and only one iterator field is supported as parameter.",
GST_VALIDATE_ACTION_TYPE_NONE);
type->prepare = gst_validate_foreach_prepare;