Captioning Live Streams with Wowza Streaming Engine
Adding Closed Captions or Open Captions to your Live video stream becomes a breeze with Scribe: Raskenlund’s Captioning Module for Wowza Streaming Engine. It allows you to inject text from arbitrary sources via its REST-compliant API, and integrate with manual or programmatic subtitle sources, or even with Speech-To-Text (STT) engines and other AI solutions.
Installing and configuring the module
As a first step, we need to copy the
wse-raskenlund-captioning-1.0.0-all.jar file to the lib folder of your Wowza installation, which on Linux servers is typically located under
The module can be configured for different use-cases, in this post we are going to use CEA608 captions ingested from REST API calls. For this you need to add the
com.raskenlund.caption.ModuleOnTextDataToCEA608 module to your application. You can do this by manually editing the
conf/live/Application.xml file or by using the Engine Manager UI.
You can find configuration details for other possible use-cases in the documentation.
Next, we need to add a custom property to the application that contains the license key for the module:
There are some additional configuration changes we need to make in the
Application.xml file which is not exposed on the UI, so please open the
conf/live/Application.xml file with your favorite text editor and add the highlighted lines to the
captionLiveIngestLanguages property should be a comma-separated list of those languages that you are going to use. This is necessary because the REST API allows you to specify the language for each incoming subtitle and the module allows you to select which one or ones you are interested in.
To make the REST API exposed and capable of accepting incoming subtitles, we need to edit the conf/VHost.xml file as well. This file enumerates multiple HostPort tags and you need to pick the one on which you’d like to listen for API calls.
In this post, we are going to use the Default Admin HostPort, which listens on port 8086. This requires you to open up this port on your firewall, which will also expose the other admin functions as well. In the production environment, it is recommended to expose only the minimal required functionality and use TLS.
Once these settings have been changed, please restart Wowza Streaming Engine to make sure the changes are picked up.
Publishing a demo live stream
To demonstrate the module working, we are going to publish a live RTMP stream from OBS. First, let’s disable the default source security in the live application to make things easier:
Next, we are going to publish some content from OBS:
Send in an example caption
Once our stream is live, we can actually go and try out the REST API exposed by the module. You can use command line tools, such as curl to construct the API call, but in this example we’ll use Postman, a popular developer tool to work with the API.
Postman can import the module API specification that is published in OpenAPI 3.0 format along with the documentation. (Using tools like swagger, you can generate a client stub in your favourite programming language too).
The URL to the latest specification file is https://docs.raskenlund.com/wse-raskenlund-captioning/latest/_static/wse-raskenlund-captioning.yaml
Once the API is imported, we need to make small adjustments to the default generated request, because the spec file does not contain the actual mapping that we’ve configured in the VHost.xml file and is also not capable of picking up the example values in the yaml file.
Once the request has been edited, you can press the Send button and you should get the below result within a few milliseconds:
Concurrently, you can start playback in any player, e.g. VLC, and make sure you are explicitly turning on captions. (The list of recognized subtitle tracks might only become available after the player receives the very first subtitle)