.. _Installation:

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

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

- AntMedia Server 2.17 or later
- A valid Scribe license key
- A `Speechmatics <https://speechmatics.com>`_ API key (when using Speechmatics)

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

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

.. code-block:: bash

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

This downloads ``Scribe-1.1.2.jar`` to the AntMedia plugins directory, sets the correct file
ownership, and restarts the ``antmedia`` service.

Installing the HLS manifest filter
------------------------------------

Scribe injects subtitle tracks into HLS playlists using a Servlet Filter registered in each
application's ``WEB-INF/web.xml``. This step is required for subtitles to be visible to players.

The easiest way to install the filter is through the Scribe Web UI:

1. Open ``http://<your-server>:5080/rest/scribe/ui/``
2. Click on the application name in the left sidebar (e.g. ``LiveApp``)
3. Click **"Install Filter"** — Scribe will update ``web.xml`` and reload the application automatically

You can also install via the REST API:

.. code-block:: bash

   curl -X POST http://localhost:5080/rest/scribe/app/LiveApp/install

To remove the filter:

.. code-block:: bash

   curl -X DELETE http://localhost:5080/rest/scribe/app/LiveApp/install

.. note::
   Each AntMedia application needs its own filter installation. If you add a new application
   later, install the filter for it using the same steps above.

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

1. Copy ``Scribe-1.1.2.jar`` to ``/usr/local/antmedia/plugins/``

2. Create the configuration file ``/usr/local/antmedia/conf/scribe.properties`` and add at
   minimum your license key, API key, and the name of the application you want to transcribe:

   .. code-block:: yaml

      licenseKey: "YOUR-LICENSE-KEY"
      provider: "speechmatics"
      speechmaticsApiKey: "YOUR-SPEECHMATICS-API-KEY"

      applications:
        LiveApp:
          speechmaticsLanguage: "en"

   Replace ``LiveApp`` with the name of your AntMedia application (case-sensitive).

3. Restart AntMedia:

   .. code-block:: bash

      systemctl restart antmedia

4. Install the HLS manifest filter for each application you want to enable:

   .. code-block:: bash

      curl -X POST http://localhost:5080/rest/scribe/app/LiveApp/install

   Or use the Web UI as described in :ref:`Installing the HLS manifest filter` above.

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

After restarting, publish a stream to the configured application. You should see log entries
from ``Scribe`` in ``/usr/local/antmedia/log/ant-media-server.log`` and ``.vtt`` subtitle
files appearing alongside the HLS segments in the streams directory.

Players that request ``{streamId}.m3u8`` or ``{streamId}_adaptive.m3u8`` will receive the
manifest with subtitle tracks injected automatically — no special URL is required.