Upgrade closed captions for live streams in Wowza Streaming Engine 4.9.2

Wowza Streaming Engine can ingest instream closed caption information from AMF onTextData events, AMF onCaptionInfo events, or CEA-608/708 data. The ingested caption data can be delivered in HLS or RTMP streams as CEA-608/708 captions.

To accommodate ingest and conversion support for CEA-708 captions in Wowza Streaming Engine 4.9.2, we updated the closed caption settings available for live streams. Several properties, modules, and packages were renamed, and the user interface (UI) was enhanced to reflect these updates.

Note: When upgrading Wowza Streaming Engine 4.9.2, your existing captioning features, including support for embedded captions, sidecar files, and real-time captioning, should remain fully functional. The upgrade process is designed to preserve all previously configured settings and ensure compatibility with standard caption formats like CEA-608, CEA-708, and WebVTT.

This guide helps you understand various changes so you can migrate from the legacy closed caption features to the new closed caption experience for live streams in Wowza Streaming Engine 4.9.2.

Before you start

The information in this guide only applies if you're updating to Wowza Streaming Engine 4.9.2 from earlier versions and you've configured onTextData or embedded CEA-608 closed captions sources for your live streams. If you plan on working with Wowza Streaming Engine 4.9.2 and closed captions functionality for live streams, we recommend you review the following resources:

Breaking changes

For the new closed caption configuration available with Wowza Streaming Engine 4.9.2, we modified some modules and packages while renaming and deprecating several legacy captioning properties.

If you're migrating from a previous Wowza Streaming Engine version that only supports CEA-608 captions or you have custom closed caption configurations, you may have to update some properties or Application.xml configuration files manually.

Modified CEA-608 packages

The com.wowza.wms.timedtext.cea608 package was renamed com.wowza.wms.timedtext.cea. In cases where you have custom Java code referencing the legacy package, you may have to update your source code. These two packages were also added:

  • com.wowza.wms.timedtext.cea.cea608
  • com.wowza.wms.timedtext.cea.cea708

Package changes are reflected in the updated Wowza Streaming Engine Java API reference documentation.

Modified CEA-608 modules

The ModuleCEA608ToOnTextData class name is still backward compatible, but it was renamed ModuleCEAToOnTextData to support both CEA-608 and CEA-708 captions. In cases where you're extending the legacy module and using it directly in your Application.xml without relying on the UI, you may need to update your Application.xml configuration files.

Renamed CEA-608 properties

The properties in the following table were tied to the legacy CEA-608 module and were renamed to accommodate CEA-708 caption integration.

You can find these renamed properties when you go to your live application. Click the Properties tab and scroll to the Closed Captions section.

Legacy CEA-608 property Explanation
ccIngestCEA608LogCaptions Renamed to ccIngestCEALogCaptions.
ccIngestCEA608VerboseLogging Renamed to ccIngestCEAVerboseLogging.

These renamed properties can be added in the Custom properties section for your live application in Wowza Streaming Engine.

Legacy CEA-608 property Explanation
ccIngestCEA608EnableTranscoderResults Renamed to ccIngestCEAEnableTranscoderResults.
ccIngestCEA608IdleTimeToFlushDecoder Renamed to ccIngestCEAIdleTimeToFlushDecoder.
ccIngestCEA608LogAsRaw Renamed to ccIngestCEALogAsRaw.
ccIngestCEA608LogAsSCC Renamed to ccIngestCEALogAsSCC.
ccIngestCEA608RemoveExistingCEA608 Renamed to ccIngestCEARemoveExistingCEA.
closedCaptionLiveRemoveExistingCEA608 Renamed to closedCaptionLiveRemoveExistingCEACaptions.

If you upgrade to Wowza Streaming Engine 4.9.2 and you're using some of the legacy CEA-608 properties, they may appear as custom properties on the Properties tab > Custom section for your live application. For property descriptions and additional configuration information, see:

Unmodified CEA-608 properties

The CEA-608 properties in this section weren't modified with the Wowza Streaming Engine 4.9.2 release. You can use them with the legacy ModuleCEA608ToOnTextData or new ModuleCEAToOnTextData modules. However, we recommend the new module and captioning features. For more information, see the Wowza Streaming Manager UI changes

You can set the following properties when you go to your live application. Click the Properties tab and scroll to the Closed Captions section.

  • ccIngestCEA608EnableField1
  • ccIngestCEA608EnableField2
  • ccIngestCEA608MaxWarnMessages
  • cea608CaptionConverterColor
  • closedCaptionLiveMaxDisplayTime

For property descriptions and additional configuration information, see:

Additions and updates

For the new closed captioning configurations available with Wowza Streaming Engine 4.9.2, we added new CEA-708 captioning properties and modified the UI to account for these changes.

New CEA-708 properties

The following properties were added to facilitate the inclusion and configuration of CEA-708 captions in Wowza Streaming Engine 4.9.2. You can find these properties when you go to your live application, click the Properties tab, and scroll to the Closed Captions​ section.

  • ccIngestEnableCEA708
  • closedCaptionLive708AnchorPoint
  • closedCaptionLive708CaptionType
  • closedCaptionLive708DebugLog
  • closedCaptionLive708HorizontalPosition
  • closedCaptionLive708LanguageMapping
  • closedCaptionLive708PenStyle
  • closedCaptionLive708PositionRelative
  • closedCaptionLive708VerticalPosition
  • closedCaptionLive708WindowStyle
  • webVTTPreferredSource

For property descriptions and additional configuration information, see:

Wowza Streaming Manager UI changes

The UI changes summarized in this section were made in the Closed Captions section and are visible when configuring captioning settings for a live stream in Wowza Streaming Engine Manager.

Each of the UI options in the previous image can be described as follows:

  • None: Select this option when ingesting onTextData events and generating WebVTT sidecar files for your outbound live streams. For configuration details, see Configure onTextData captions for WebVTT output in HLS live streams.
  • Ingest onTextData events in live streams: Corresponds to new module ModuleOnTextDataToCEA that replaces legacy ModuleOnTextDataToCEA608. For configuration details, see Ingest and configure AMF onTextData captions for live streams.
    • Output to CEA-608: Ingest onTextData events from a live stream and convert them to CEA-608 captions.
    • Output to CEA-708: Ingest onTextData events from a live stream and convert them to CEA-708 captions.
  • Ingest embedded CEA-608/708 captions in live streams: Corresponds to new module ModuleCEAToOnTextData that replaces legacy module ModuleCEA608ToOnTextData. For configuration details, see Ingest and configure CEA-608/708 captions for live streams.
  • Ingest onCaptionInfo events in live streams: No changes to this UI option. Behind the scenes, it enables the captionLiveIngestType custom property. For configuration details, see Ingest and configure AMF onCaption captions for live streams.
  • (Legacy) Ingest onTextData events in live streams: Corresponds to legacy module ModuleOnTextDataToCEA608. While this option can still be selected in the UI, we recommend using the Ingest onTextData events in live streams radio button and new CEA-608/708 output options.
  • (Legacy) Ingest embedded CEA-608 captions in live streams: Corresponds to legacy module ModuleCEA608ToOnTextData. While this option can still be selected in the UI, we recommend using the Ingest embedded CEA-608/708 captions in live streams radio button and corresponding module.