Publish OnTextData Module and Code

This package includes a simple module, ModulePublishOnTextData, that injects onTextData events into a live stream. It's useful for testing a live closed caption implementation. This module takes caption data from a flat text file and injects an onTextData event into the stream every 6.5 seconds. Again, this module is only for testing purposes and is an example of how to inject onTextData events into a live stream.

Note: Wowza Media Server 3.1.1.08 or later is required.

Background

An onTextData event is an AMF (Action Message Format) event that's traditionally associated with Real Time Messaging Protocol (RTMP) and Adobe® HTTP Dynamic Streaming (HDS). These events are used to carry closed caption or subtitle information. An onTextData event usually includes the following fields:

• text. Carries the UTF-8 encoded text for the event.
• lang. Three-letter language ID for the event. (Example: eng)
• trackid (optional). When doing video on demand streaming, this is the ID of the text track in the video file. For live streaming, this field is either omitted or set to 99.

Using the Wowza Media Server® server-side API, it's possible to inject onTextData events into a live stream using the IMediaStream.sendDirect() API call (there are details below). This enables a publisher that passes closed caption data in the form of timed text events or SMPTE events to use the Wowza Media Server server-side API to inject onTextData into a live stream.

To install

1. Copy [package]/lib/wms-plugin-publishontextdata.jar to the [install-dir]/lib folder.


2. Copy [package]/content/ontextdata.txt to the [install-dir]/content folder.


3. Set up an application for live streaming. It's best to set up the application for Apple HTTP Live Streaming (Cupertino) so that you can easily test the closed captions using an iOS-based device. To do this, add cupertinostreamingpacketizer to the <LiveStreamPacketizers> list in [install-dir]/conf/[application]/Application.xml.


4. Add and configure ModulePublishOnTextData in [install-dir]/conf/[application]/Application.xml:
   
   
   1. Add the ModulePublishOnTextData module to the end of the <Modules> list:

      <Module>
      	<Name>ModulePublishOnTextData</Name>
      	<Description>ModulePublishOnTextData</Description>
      	<Class>com.wowza.wms.plugin.closedcaption.test.ModulePublishOnTextData</Class>
      </Module>
      

   2. Add the following properties to the application-level <Properties> container at the bottom of the file (be sure to get the correct <Properties> container - there are several in the Application.xml file):

      <Property>
      	<Name>publishOnTextDataFile</Name>
      	<Value>${com.wowza.wms.context.VHostConfigHome}/content/ontextdata.txt</Value>
      </Property>
      <Property>
      	<Name>publishOnTextDataPublishInterval</Name>
      	<Value>6500</Value>
      	<Type>Integer</Type>
      </Property>
      <Property>
      	<Name>publishOnTextCharsetTest</Name>
      	<Value>false</Value>
      	<Type>Boolean</Type>
      </Property>
      

      Where:

      • publishOnTextDataFile: Path to the ontextdata.txt text file.
      • publishOnTextDataPublishInterval: Specifies how often events are injected, in milliseconds.
      • publishOnTextCharsetTest: If set to true, the module will publish test onTextData events that cover the full UTF-8 character set from 0x20-0xFF.

   
   
5. Start Wowza Media Server and publish a live stream to the server. For this example, we'll use the stream name myStream.


6. Check the log to see that the module is started and publishing
7. Use this in conjunction with the Wowza functionality to convert onTextData to CEA-608.
8. Play the live stream on an Apple iOS device using the following URL:

   http://[wowza-ip-address]:1935/[application]/myStream/playlist.m3u8

   Note: Captions will only display if closed captioning is turned on. To turn on closed captioning on an iOS device, go to Settings > Video and turn on the Closed Captioning option.

Notes

To add onTextData events to a live stream, use the sendDirect(handler, param...) method. The code to add an onTextData event to a stream looks like this:

AMFDataObj amfData = new AMFDataObj();

amfData.put("text", new AMFDataItem(onTextData.text));
amfData.put("language", new AMFDataItem("eng"));
amfData.put("trackid", new AMFDataItem(99));

stream.sendDirect("onTextData", amfData);