.. _Installation:

Installation
============

Requirements
------------

- AntMedia Server 2.17 or later
- A valid Scotty license key

Quick install
-------------

Run the following command on your AntMedia server as root or with ``sudo``:

.. code-block:: bash

   curl -fsSL https://downloads.raskenlund.com/scotty/antmediaserver/install.sh | sudo bash

This downloads ``Scotty-1.0.0.jar`` to the AntMedia plugins directory, sets the correct file
ownership, and restarts the ``antmedia`` service. A skeleton ``scotty.properties`` config file
is created at ``/usr/local/antmedia/conf/scotty.properties`` if one does not already exist.

You can pass your license key directly to avoid editing the config file manually:

.. code-block:: bash

   curl -fsSL https://downloads.raskenlund.com/scotty/antmediaserver/install.sh | sudo bash -s -- --licenseKey=YOUR-LICENSE-KEY

Manual install
--------------

1. Copy ``Scotty-1.0.0.jar`` to ``/usr/local/antmedia/plugins/``

2. Copy ``scotty.properties.dist`` to ``/usr/local/antmedia/conf/scotty.properties`` and add
   your license key at minimum:

   .. code-block:: yaml

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

3. Restart AntMedia:

   .. code-block:: bash

      systemctl restart antmedia

4. Open the Web UI at ``http://<your-server>:5080/rest/scotty/ui/`` and use the
   **Applications** section to install the servlet filter for each application you want
   Scotty to annotate (see :ref:`Servlet filter` below).

.. _Servlet filter:

Servlet filter
--------------

Scotty injects HLS tags by intercepting M3U8 responses through a servlet filter.
The filter must be registered in each AntMedia application's ``WEB-INF/web.xml``.

The easiest way to do this is via the Web UI (see :ref:`Web UI`). Alternatively, add the
following to the application's ``WEB-INF/web.xml`` **after** the ``HlsManifestModifierFilter``
entry:

.. code-block:: xml

   <filter>
       <filter-name>ScottyManifestFilter</filter-name>
       <filter-class>io.ztream.scotty.hls.ScottyManifestFilter</filter-class>
       <async-supported>true</async-supported>
   </filter>
   <filter-mapping>
       <filter-name>ScottyManifestFilter</filter-name>
       <url-pattern>/streams/*</url-pattern>
   </filter-mapping>

After editing ``web.xml`` manually, restart the application (or the full AntMedia service).

Verifying the installation
---------------------------

After restarting, publish a stream to a configured application. You should see log entries
from ``Scotty`` in ``/usr/local/antmedia/log/ant-media-server.log``. When a SCTE-35 cue point
arrives in the stream, the corresponding HLS tags will appear in the ``.m3u8`` playlist
for that stream.