subprojects/gst-devtools/docs/gst-validate-scenarios.md

   1 ---
   2 title: Scenarios
   3 short-description: The GstValidate Scenario format
   4 ...
   5
   6 # GstValidate Scenario File Format
   7
   8 To be able to define a list of actions to execute on a [`GstPipeline`],
   9 a dedicated file format is used. The name of the scenario is the name of
  10 the file without its `.scenario` extension. The scenario file format is
  11 based on the [`GstStructure`] serialized format which is a basic, type
  12 aware, key value format. It takes the type of the action in the first
  13 comma separated field, and then some key value pairs in the form
  14 `parameter=value` separated by commas. The values type will be guessed
  15 if not casted as in `parameter=(string)value`. You can force the type
  16 guessing system to actually know what type you want by giving it the
  17 right hints. For example to make sure the value is a double, you should
  18 add a decimal (ie. `1` will be considered as a `int`, but `1.0` will be
  19 considered as a `double` and `"1.0"` will be considered as a `string`).
  20
  21 For example to represent a seek action, you should add the following
  22 line in the `.scenario` file.
  23
  24     seek, playback-time=10.0, start=0.0, flags=accurate+flush
  25
  26 The files to be used as scenario should have a `.scenario` extension and
  27 should be placed either in
  28 `$USER_DATA_DIR/gstreamer-1.0/validate/scenarios` ,
  29 `$GST_DATADIR/gstreamer-1.0/validate/scenarios` or in a path defined in
  30 the \$GST\_VALIDATE\_SCENARIOS\_PATH environment variable.
  31
  32 Each line in the `.scenario` file represent an action (you can also use
  33 `\ ` at the end of a line write a single action on multiple lines).
  34 Usually you should start you scenario with a `meta` structure
  35 in order for the user to have more information about the
  36 scenario. It can contain a `summary` field which is a string explaining
  37 what the scenario does and then several info fields about the scenario.
  38 You can find more info about it running:
  39
  40     gst-validate-1.0 --inspect-action-type action_type_name
  41
  42 So a basic scenario file that will seek three times and stop would look
  43 like:
  44
  45 ```
  46 meta, summary="Seeks at 1.0 to 2.0 then at \
  47 3.0 to 0.0 and then seeks at \
  48 1.0 to 2.0 for 1.0 second (between 2.0 and 3.0).", \
  49 seek=true, duration=5.0, min-media-duration=4.0
  50 seek, playback-time=1.0, rate=1.0, start=2.0, flags=accurate+flush
  51 seek, playback-time=3.0, rate=1.0, start=0.0, flags=accurate+flush
  52 seek, playback-time=1.0, rate=1.0, start=2.0, stop=3.0, flags=accurate+flush
  53 ```
  54
  55 Many action types have been implemented to help users define their own
  56 scenarios. For example there are:
  57
  58 -   `seek`: Seeks into the stream.
  59 -   `play`: Set the pipeline state to `GST_STATE_PLAYING`.
  60 -   `pause`: Set the pipeline state to `GST_STATE_PAUSED`.
  61 -   `stop`: Stop the execution of the pipeline.
  62
  63 >   **NOTE**: This action actually posts a [`GST_MESSAGE_REQUEST_STATE`]
  64 >   message requesting [`GST_STATE_NULL`] on the bus and the application
  65 >   should quit.
  66
  67 To get all the details about the registered action types, you can list
  68 them all with:
  69
  70 ```
  71 gst-validate-1.0 --inspect-action-type
  72 ```
  73
  74 and to include transcoding specific action types:
  75
  76 ```
  77 gst-validate-transcoding-1.0 --inspect-action-type
  78 ```
  79
  80 Many scenarios are distributed with `gst-validate`, you can list them
  81 all using:
  82
  83 ```
  84 gst-validate-1.0 --list-scenarios
  85 ```
  86
  87 You can find more information about the scenario implementation and
  88 action types in the [`GstValidateScenario` section].
  89
  90   [`GstPipeline`]: GstPipeline
  91   [`GstStructure`]: GstStructure
  92   [`GST_MESSAGE_REQUEST_STATE`]: GST_MESSAGE_REQUEST_STATE
  93   [`GST_STATE_NULL`]: GST_STATE_NULL
  94   [`GstValidateScenario` section]: GstValidateScenario
  95
  96 ## Default variables
  97
  98 Any action can use the default variables:
  99
 100 - `$(position)`: The current position in the pipeline as reported by
 101   [gst_element_query_position()](gst_element_query_position)
 102 - `$(duration)`: The current duration of the pipeline as reported by
 103   [gst_element_query_duration()](gst_element_query_duration)
 104 - `$(TMPDIR)`: The default temporary directory as returned by `g_get_tmp_dir`.
 105 - `$(SCENARIO_PATH)`: The path of the running scenario.
 106 - `$(SCENARIO_DIR)`: The directory the running scenario is in.
 107 - `$(SCENARIO_NAME)`: The name the running scenario
 108
 109
 110 It is also possible to set variables in scenario with the `set-vars` action.