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