Example Codecs
==============

.. _example_codecs:

Schema for describing example/sample codec configurations. These codecs use pre-computed results (RD reports, VMAF scores) instead of running actual encoding and decoding, and are used for testing and demonstration purposes.

.. note::

   The following top-level properties are **required**: ``example-codec-result``.


Properties
----------

.. _example_codecs_example_codec_result:


[Required] ``example-codec-result``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Path:* ``Example Codecs > example-codec-result``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``object``
   * - **Required**
     - Yes

Dictionary of example codec configurations. Each key is a codec name used to reference it in the main configuration file under 'codecs.examples'.

Each entry in this object follows the structure below.

.. _example_codecs_example_codec_result_entry_raw_type:


[Required] ``raw_type``
^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Example Codecs > example-codec-result > raw_type``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Raw format associated with this codec's decoded output. Used to determine how to handle sample data.

**Example(s):**

.. code-block:: json

   "pgx"

.. code-block:: json

   "yuv"

.. _example_codecs_example_codec_result_entry_rd_preferences:


[Required] ``rd_preferences``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Example Codecs > example-codec-result > rd_preferences``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``object``
   * - **Required**
     - Yes

Visual preferences for this codec in rate-distortion plots.

.. _example_codecs_example_codec_result_entry_rd_preferences_title:


[Required] ``title``
''''''''''''''''''''

*Path:* ``Example Codecs > example-codec-result > rd_preferences > title``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Label for this codec in RD plots.

**Example(s):**

.. code-block:: json

   "JPLM (CTC)"

.. code-block:: json

   "x265 (CTC)"

.. _example_codecs_example_codec_result_entry_rd_preferences_color:


[Optional] ``color``
''''''''''''''''''''

*Path:* ``Example Codecs > example-codec-result > rd_preferences > color``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - No

Line/marker color for this codec in RD plots.

**Example(s):**

.. code-block:: json

   "blueviolet"

.. code-block:: json

   "red"

.. code-block:: json

   "tab:blue"

.. _example_codecs_example_codec_result_entry_rd_preferences_marker:


[Optional] ``marker``
'''''''''''''''''''''

*Path:* ``Example Codecs > example-codec-result > rd_preferences > marker``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - No

Marker style for this codec in RD plots.

**Example(s):**

.. code-block:: json

   "o"

.. code-block:: json

   "x"

.. code-block:: json

   "+"

.. _example_codecs_example_codec_result_entry_samples_path:


[Required] ``samples_path``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Example Codecs > example-codec-result > samples_path``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``object``
   * - **Required**
     - Yes

Paths to directories containing pre-computed sample results for this codec.

.. _example_codecs_example_codec_result_entry_samples_path_rd_reports:


[Required] ``rd_reports``
'''''''''''''''''''''''''

*Path:* ``Example Codecs > example-codec-result > samples_path > rd_reports``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Path to the directory containing pre-computed RD report JSON files.

**Example(s):**

.. code-block:: json

   "${base-path}/../samples/jplm/rd_reports"

.. _example_codecs_example_codec_result_entry_samples_path_vmaf:


[Required] ``vmaf``
'''''''''''''''''''

*Path:* ``Example Codecs > example-codec-result > samples_path > vmaf``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Path to the directory containing pre-computed VMAF result files.

**Example(s):**

.. code-block:: json

   "${base-path}/../samples/jplm/vmaf"