Codecs
======

.. _codecs_schema:

Schema for describing codec configurations. The codecs wrapper modules (Python files) must have access to the CodecWrapper class declared in src/codecwrappers/codec_wrapper.py

.. note::

   The following top-level properties are **required**: ``ctc-codecs-declaration``.


Properties
----------

.. _codecs_schema_ctc_codecs_declaration:


[Required] ``ctc-codecs-declaration``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Path:* ``Codecs > ctc-codecs-declaration``

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

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

Dictionary of codec configurations. Each key is a codec name used to reference it in the main configuration file.

Each entry in this object follows the structure below.

.. _codecs_schema_ctc_codecs_declaration_entry_wrapper_file:


[Required] ``wrapper_file``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > wrapper_file``

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

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

Filename of the wrapper module, without the .py extension. The wrapper module is responsible for calling the encoder and decoder binaries.

**Example(s):**

.. code-block:: json

   "jplm_wrapper"

.. code-block:: json

   "x265_wrapper"

.. _codecs_schema_ctc_codecs_declaration_entry_wrapper_name:


[Required] ``wrapper_name``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > wrapper_name``

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

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

Class name of the wrapper inside the wrapper module.

**Example(s):**

.. code-block:: json

   "JPLMWrapper"

.. code-block:: json

   "x265Wrapper"

.. _codecs_schema_ctc_codecs_declaration_entry_repository:


[Required] ``repository``
^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > repository``

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

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

URL of the codec git remote repository. Can be either HTTPS or SSH.

**Example(s):**

.. code-block:: json

   "https://gitlab.com/wg1/jpeg-pleno-refsw.git"

.. code-block:: json

   "https://bitbucket.org/multicoreware/x265_git.git"

.. _codecs_schema_ctc_codecs_declaration_entry_tag:


[Optional] ``tag``
^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > tag``

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

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

Git tag, branch, or commit hash to checkout after cloning.

**Example(s):**

.. code-block:: json

   "v2.0.1-m110"

.. code-block:: json

   "4.0"

.. code-block:: json

   "master"

.. _codecs_schema_ctc_codecs_declaration_entry_path:


[Required] ``path``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > path``

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

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

Local path where the codec will be cloned and built.

**Example(s):**

.. code-block:: json

   "${base-path}/../temporary/jpeg-plm-private"

.. code-block:: json

   "${base-path}/../temporary/x265_git"

.. _codecs_schema_ctc_codecs_declaration_entry_log:


[Optional] ``log``
^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > log``

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

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

Filename for the codec execution log (JSON format). Saved inside the 'results' directory.

**Example(s):**

.. code-block:: json

   "execution_log_jplm.json"

.. code-block:: json

   "execution_log_x265_anchor.json"

.. _codecs_schema_ctc_codecs_declaration_entry_clear_log:


[Optional] ``clear_log``
^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > clear_log``

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

   * - **Type**
     - ``boolean``
   * - **Required**
     - No
   * - **Default**
     - ``false``

If true, clears the codec log file before running.

.. _codecs_schema_ctc_codecs_declaration_entry_force_encoding:


[Optional] ``force_encoding``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > force_encoding``

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

   * - **Type**
     - ``boolean``
   * - **Required**
     - No
   * - **Default**
     - ``false``

If true, forces re-encoding even if encoded files already exist.

.. _codecs_schema_ctc_codecs_declaration_entry_force_building:


[Optional] ``force_building``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > force_building``

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

   * - **Type**
     - ``boolean``
   * - **Required**
     - No
   * - **Default**
     - ``false``

If true, forces rebuilding the codec binary even if it already exists.

.. _codecs_schema_ctc_codecs_declaration_entry_build_options:


[Optional] ``build_options``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > build_options``

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

   * - **Type**
     - ``array of string``
   * - **Required**
     - No
   * - **Default**
     - ``[]``

CMake build options passed during codec compilation.

**Example(s):**

.. code-block:: json

   [
       "-DCMAKE_BUILD_TYPE=Release"
   ]

.. code-block:: json

   [
       "-DCMAKE_BUILD_TYPE=Release",
       "-DHIGH_BIT_DEPTH=ON"
   ]

.. _codecs_schema_ctc_codecs_declaration_entry_cmake_path:


[Optional] ``cmake_path``
^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > cmake_path``

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

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

Relative path (from 'path') to the directory containing CMakeLists.txt.

**Example(s):**

.. code-block:: json

   ".."

.. code-block:: json

   "../source"

.. _codecs_schema_ctc_codecs_declaration_entry_results:


[Optional] ``results``
^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > results``

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

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

Directory path where encoded and decoded results will be stored.

**Example(s):**

.. code-block:: json

   "${base-path}/../temporary/results/jplm_results"

.. code-block:: json

   "${base-path}/../temporary/results/x265_anchor_results"

.. _codecs_schema_ctc_codecs_declaration_entry_encoded_extension:


[Required] ``encoded_extension``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > encoded_extension``

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

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

File extension for encoded bitstream files.

**Example(s):**

.. code-block:: json

   "jpl"

.. code-block:: json

   "h265"

.. _codecs_schema_ctc_codecs_declaration_entry_raw_type:


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

*Path:* ``Codecs > ctc-codecs-declaration > raw_type``

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

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

Raw format used as input for encoding and expected output of decoding.

**Example(s):**

.. code-block:: json

   "pgx"

.. code-block:: json

   "yuv"

.. _codecs_schema_ctc_codecs_declaration_entry_decoded_conversions:


[Optional] ``decoded_conversions``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > decoded_conversions``

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

   * - **Type**
     - ``array of string``
   * - **Required**
     - No
   * - **Default**
     - ``[]``

List of formats to convert the decoded output into after decoding.

**Example(s):**

.. code-block:: json

   [
       "yuv",
       "ppm"
   ]

.. code-block:: json

   [
       "pgx",
       "ppm"
   ]

.. _codecs_schema_ctc_codecs_declaration_entry_keep_decoded:


[Optional] ``keep_decoded``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > keep_decoded``

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

   * - **Type**
     - ``array of string``
   * - **Required**
     - No

List of decoded formats to retain after conversion. Formats not listed may be deleted.

**Example(s):**

.. code-block:: json

   [
       "pgx"
   ]

.. code-block:: json

   [
       "yuv"
   ]

.. code-block:: json

   [
       "ppm"
   ]

.. _codecs_schema_ctc_codecs_declaration_entry_repetitions:


[Optional] ``repetitions``
^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > repetitions``

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

   * - **Type**
     - ``integer``
   * - **Required**
     - No
   * - **Default**
     - ``1``

Number of times encoding and decoding should be repeated for each LF/bitrate combination. Useful for averaging performance measurements.

.. _codecs_schema_ctc_codecs_declaration_entry_kwargs:


[Optional] ``kwargs``
^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Codecs > ctc-codecs-declaration > kwargs``

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

   * - **Type**
     - ``object``
   * - **Required**
     - No

Additional wrapper-specific parameters passed directly to the codec wrapper.

**Example(s):**

.. code-block:: json

   {
       "fps": 30,
       "tune_metric": "psnr",
       "bpp_to_actual_kbps_map_path": "${base-path}/../data/x265_target_kbps.json"
   }

.. _codecs_schema_ctc_codecs_declaration_entry_rd_preferences:


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

*Path:* ``Codecs > ctc-codecs-declaration > rd_preferences``

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

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

Visual preferences for this codec in rate-distortion plots.

.. _codecs_schema_ctc_codecs_declaration_entry_rd_preferences_title:


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

*Path:* ``Codecs > ctc-codecs-declaration > 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 (v2.0.1)"

.. code-block:: json

   "x265"

.. _codecs_schema_ctc_codecs_declaration_entry_rd_preferences_color:


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

*Path:* ``Codecs > ctc-codecs-declaration > 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

   "blue"

.. code-block:: json

   "red"

.. code-block:: json

   "tab:orange"

.. _codecs_schema_ctc_codecs_declaration_entry_rd_preferences_marker:


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

*Path:* ``Codecs > ctc-codecs-declaration > 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

   "+"