.. _Configuration:

Configuration
=============

Settings are stored in ``/usr/local/antmedia/conf/scotty.properties`` as YAML. You can edit
the file directly or use the :ref:`web UI <Web UI>`.

Changes to configuration can be applied without restarting AntMedia Server using the hot reload
feature (Dashboard → "Reload Configuration" button or ``POST /rest/scotty/reload``). Active
streams continue with their existing configuration; new streams use the reloaded settings.

Example configuration
---------------------

.. code-block:: yaml

   licenseKey: "YOUR-LICENSE-KEY"
   mode: both
   ssaiTagFormat: EXT_X_CUE_OUT_IN

   # SGAI — Apple HLS Interstitials
   sgaiAdAssetUri: "https://ads.example.com/ad.m3u8"
   sgaiResumeOffset: 0
   sgaiRestrict: "SKIP,JUMP"

   applications:
     LiveApp:
       mode: ssai
     WebRTCAppEE:
       mode: both
       sgaiAdAssetUri: "https://ads.example.com/special.m3u8"

The plugin only activates for applications that appear under ``applications:``. The application
name must match the AntMedia webapp context name exactly (case-sensitive).

An application is enabled when it has an entry under ``applications:`` and disabled when that
entry is absent. Using the web UI to disable an application removes its entry from the file.

Global settings
---------------

These settings apply to all applications unless overridden at the application level.

.. list-table::
   :widths: 30 55 15
   :header-rows: 1

   * - Key
     - Description
     - Default
   * - ``licenseKey``
     - Your Scotty license key.
     - —
   * - ``mode``
     - Ad-insertion mode: ``ssai``, ``sgai``, or ``both``.
     - ``both``
   * - ``ssaiTagFormat``
     - SSAI HLS tag format (see :ref:`SSAI tag formats` below).
     - ``EXT_X_CUE_OUT_IN``
   * - ``sgaiAdAssetUri``
     - URI for the ad asset playlist used in SGAI mode. The placeholders ``{duration}`` and
       ``{eventId}`` are replaced at runtime with the cue duration in seconds and the SCTE-35
       event ID respectively.
     - —
   * - ``sgaiResumeOffset``
     - ``X-RESUME-OFFSET`` in seconds: how many seconds after the interstitial start the main
       content resumes. Set to ``0`` for the ad to play to completion before resuming.
     - ``0``
   * - ``sgaiRestrict``
     - Comma-separated ``X-RESTRICT`` restrictions applied to the interstitial.
       Valid values: ``SKIP``, ``JUMP``, or both.
     - ``SKIP,JUMP``

.. _SSAI tag formats:

SSAI tag formats
^^^^^^^^^^^^^^^^

The ``ssaiTagFormat`` setting controls which HLS tags Scotty injects for SSAI:

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

   * - Value
     - Tags injected
   * - ``EXT_X_CUE_OUT_IN``
     - ``#EXT-X-CUE-OUT:<duration>``, ``#EXT-X-CUE-OUT-CONT:<elapsed>/<duration>``,
       ``#EXT-X-CUE-IN`` — the format expected by AWS MediaTailor and most SSAI platforms.
   * - ``EXT_X_DATERANGE_SCTE35``
     - ``#EXT-X-DATERANGE`` with ``SCTE35-OUT`` and ``SCTE35-IN`` attributes carrying the
       raw base64-encoded SCTE-35 binary.
   * - ``EXT_X_SCTE35``
     - ``#EXT-OATCLS-SCTE35`` / ``#EXT-X-SCTE35`` marker tags with the raw binary payload.

Per-application settings
------------------------

These go under ``applications.<appName>``. Any setting not specified falls back to the global
value, then to the built-in default.

.. list-table::
   :widths: 30 55 15
   :header-rows: 1

   * - Key
     - Description
     - Default
   * - ``mode``
     - Override the ad-insertion mode for this application: ``ssai``, ``sgai``, or ``both``.
     - (global)
   * - ``ssaiTagFormat``
     - Override the SSAI tag format for this application.
     - (global)
   * - ``sgaiAdAssetUri``
     - Override the SGAI ad asset URI for this application. Supports ``{duration}`` and
       ``{eventId}`` placeholders.
     - (global)
   * - ``sgaiResumeOffset``
     - Override the ``X-RESUME-OFFSET`` for this application.
     - (global)
   * - ``sgaiRestrict``
     - Override the ``X-RESTRICT`` value for this application.
     - (global)

Per-stream settings
-------------------

Within an application block you can define ``streamNameTemplates`` to apply different settings
to individual streams based on their stream ID. Keys are Java regular expressions matched
against the full stream ID; the **first** matching pattern wins.

.. code-block:: yaml

   applications:
     LiveApp:
       mode: both                          # default for all streams in this app
       sgaiAdAssetUri: "https://ads.example.com/default.m3u8"
       streamNameTemplates:
         "^sports-.*":                     # streams whose ID starts with "sports-"
           sgaiAdAssetUri: "https://ads.example.com/sports.m3u8"
         ".*-test$":                       # streams whose ID ends with "-test"
           mode: ssai

Any per-application setting can be overridden inside a stream template. Settings absent from
the matching template fall back to the application-level value, then to the global value.

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

   * - Behaviour
     - Detail
   * - Order matters
     - Patterns are evaluated top-to-bottom; the first match is used.
   * - Full-string match
     - The regex must match the **entire** stream ID. Anchors ``^`` / ``$`` are
       recommended for clarity but the match is always against the whole string.
   * - Runtime behaviour
     - Stream templates are resolved when a stream starts. Changing templates requires a
       configuration reload; streams already in progress retain their original settings until
       they are restarted.

Overridable settings per stream template
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

All per-application settings can appear inside a stream template:
``mode``, ``ssaiTagFormat``, ``sgaiAdAssetUri``, ``sgaiResumeOffset``, ``sgaiRestrict``.