.. _Usecases:

Use-cases
=========

Open captions driven by REST API calls
--------------------------------------

On Linux operating systems Wowza installation ships with OpenJDK that does not include fonts. On Linux
you need to manually install `fontmanager` and at least one font `openttf-dejavu` to make open captions work.

.. code-block:: bash
    sudo apt-get install fontconfig
    sudo apt-get install ttf-dejavu

To get the REST API up and running, you need to add the below HTTP provider to your ``VHost.xml`` file:

.. code-block:: xml

    <HTTPProvider>
        <BaseClass>io.ztream.scribe.HttpProviderCaptionApi</BaseClass>
        <RequestFilters>captions*</RequestFilters>
        <AuthenticationMethod>none</AuthenticationMethod>
    </HTTPProvider>

You need to add ``ModuleLiveOpenCaptions`` module to your ``Application.xml``

.. code-block:: xml

    <Modules>
        ...
        <Module>
            <Name>ModuleLiveOpenCaptions</Name>
            <Description>ModuleLiveOpenCaptions</Description>
            <Class>io.ztream.scribe.ModuleLiveOpenCaptions</Class>
        </Module>

    </Modules>

You have to enable transcoder in the application via the Engine Manager UI or directly in the xml:

.. code-block:: xml

    <Transcoder>
        <!-- To turn on transcoder set to: transcoder -->
        <LiveStreamTranscoder>transcoder</LiveStreamTranscoder>

You also need to set the ``raskenlund.804.license`` application property:

.. code-block:: xml

    <Property>
        <Name>raskenlund.804.license</Name>
        <Value>W804-1038-xxxx-xxxx-xxxx</Value>
        <Type>String</Type>
    </Property>

Assuming your application is called ``live`` and your incoming stream is called ``myStream``, you can
trigger a test caption using curl:

.. code-block:: bash

    curl --location --request POST "http://localhost:1935/captions/v1/applications/live/streams/myStream/caption"
    \ --header "Content-Type: application/json" --data-raw "{
    \"captions\": [
        {
            \"textData\": \"Hello World, this is the captioning module\",
            \"language\": \"en\"
        }
    ],
    \"delay\": 0
    \}"

CEA608 captions driven by REST API calls
----------------------------------------

To get the REST API up and running, you need to add the below HTTP provider to your ``VHost.xml`` file:

.. code-block:: xml

    <HTTPProvider>
        <BaseClass>io.ztream.scribe.HttpProviderCaptionApi</BaseClass>
        <RequestFilters>captions*</RequestFilters>
        <AuthenticationMethod>none</AuthenticationMethod>
    </HTTPProvider>

You need to add ``ModuleOnTextDataToCEA608`` module to your ``Application.xml``

.. code-block:: xml

    <Module>
        <Name>ModuleOnTextDataToCEA608</Name>
        <Description>ModuleOnTextDataToCEA608</Description>
        <Class>io.ztream.scribe.ModuleOnTextDataToCEA608</Class>
    </Module>

You need to set the ``raskenlund.804.license`` application property:

.. code-block:: xml

    <Property>
        <Name>raskenlund.804.license</Name>
        <Value>W804-1038-xxxx-xxxx-xxxx</Value>
        <Type>String</Type>
    </Property>

You need to configure the below timed text settings in the application:

.. code-block:: xml

    <TimedText>
        <VODTimedTextProviders></VODTimedTextProviders>
        <!-- Properties for TimedText -->
        <Properties>
            <Property>
                <Name>captionLiveIngestType</Name>
                <Value>onTextData</Value>
                <Type>String</Type>
            </Property>
            <Property>
                <Name>captionLiveIngestLanguages</Name>
                <Value>eng,nld,nor,hun</Value>
                <Type>String</Type>
            </Property>
        </Properties>
    </TimedText>

WebVTT captions driven by REST API calls
----------------------------------------

Please follow the setup for the CEA608 captions, except that you should not add ``ModuleOnTextDataToCEA608``
to the application, but configure the below timed text property instead:

.. code-block:: xml

    <TimedText>
        <VODTimedTextProviders></VODTimedTextProviders>
        <!-- Properties for TimedText -->
        <Properties>
            <Property>
                <Name>cupertinoLiveCaptionsUseWebVTT</Name>
                <Value>true</Value>
                <Type>Boolean</Type>
            </Property>

Speech To Text with AWS Transcribe
----------------------------------
You need to add ``ModuleLiveTranscribe`` module to your ``Application.xml``

.. code-block:: xml

    <Module>
        <Name>ModuleLiveTranscribe</Name>
        <Description>ModuleLiveTranscribe</Description>
        <Class>io.ztream.scribe.ModuleLiveTranscribe</Class>
    </Module>

And you must enable transcoder in the application via the Engine Manager UI or directly in the xml. If you
do not need video transcoding, you can use the "audioonly" template so that video transcoding is disabled:

.. code-block:: xml

    <Transcoder>
        <!-- To turn on transcoder set to: transcoder -->
        <LiveStreamTranscoder>transcoder</LiveStreamTranscoder>
        <Templates>audioonly.xml</Templates>

Please make sure that at least one ``Encode`` in your active transcoder profiles have the
audio codec set to something other than ``PassThru``. If no audio is being transcoded, the plugin
is not able to capture audio frames and send them to AWS, which will time out the
transcoding session after 15 seconds without audio data.

WebVTT tracks in Adaptive Live Streaming HLS playlists
------------------------------------------------------

When adding WebVTT captions to a live stream, by default Wowza publishes the WebVTT track
in each rendition's own ``playlist.m3u8`` but the adaptive playlist that starts with ``ngrp:``
does not contain the text track.

To fix this problem the Scribe module contains a custom Module that can be configured in the
``Application.xml`` file and make it responsible for returning the patched playlists.

.. code-block:: xml

    <Root version="1">
        <Application>
            <Modules>
                <Module>
                    <Name>ModuleAMLSTWebVTT</Name>
                    <Description>ModuleAMLSTWebVTT</Description>
                    <Class>io.ztream.scribe.ModuleAMLSTWebVTT</Class>
                </Module>

With this module enabled, replace the ``ngrp`` prefix with ``amlst`` in the playlist URL, e.g.
``https://domain.tld/application/amlst:streamname_all/playlist.m3u8`` to ensure that each rendition has a reference
to the WebVTT caption track.

.. note::

  This Module assumes that the ``StreamName`` parameter of the Stream Name Group in the transcoder template
  uses the underscore character to identify the group, e.g. ``${SourceStreamName}_all`` or ``${SourceStreamName}_test``.
  Stream Name Groups that do not follow this naming convention will be ignored when retrieving the subtitles list for
  the group.

  Here is an example ``StreamNameGroup`` section of a transcoder template

  .. code-block:: xml

    <StreamNameGroup>
      <Name>all</Name>
      <StreamName>${SourceStreamName}_all</StreamName>
      ...
    </StreamNameGroup>