.. _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>com.raskenlund.caption.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>com.raskenlund.caption.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.803.license`` application property:

.. code-block:: xml

    <Property>
        <Name>raskenlund.803.license</Name>
        <Value>W803-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>com.raskenlund.caption.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>com.raskenlund.caption.ModuleOnTextDataToCEA608</Class>
    </Module>

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

.. code-block:: xml

    <Property>
        <Name>raskenlund.803.license</Name>
        <Value>W803-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>