<?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>
