Ingest and convert timed metadata with the Wowza Streaming Cloud REST API

Timed metadata allows you to add interactivity to streams broadcast through the Wowza Streaming Cloud™ service. Wowza Streaming Cloud can ingest AMF data, a type of metadata that is embedded into WOWZ or RTMP streams, from source encoders, cameras, Wowza Streaming Engine™, or Wowza GoCoder™ SDK broadcast apps. To send the metadata for playback over HLS streams, Wowza Streaming Cloud must first convert AMF data to ID3 tags.

In this article, learn how to ingest AMF data into Wowza Streaming Cloud, convert AMF data into ID3 tags using the Wowza Streaming Cloud REST API, and consider available playback options for timed metadata in HLS streams.

Before you start

You should complete the following tasks:

  • Create a RTMP transcoder or live stream. You'll need the resulting transcoder_id or live_stream_id. See Connect an RTMP encoder to learn how to create transcoder for RTMP.
     

Ingest AMF data into a Wowza Streaming Cloud transcoder


Wowza Streaming Cloud can receive AMF metadata from an encoder or other H.264 source that supports and sends it, but AMF metadata can’t be directly injected into a transcoder in Wowza Streaming Cloud.

Wowza Streaming Engine and Wowza GoCoder SDK broadcast apps can send single bitrate streams that contain AMF metadata to a Wowza Streaming Cloud transcoder. For instructions on these workflows, see More resources.

Alternatively, Wowza Streaming Engine and Wowza GoCoder SDK broadcast apps can send streams that contain AMF data directly to origin servers for ultra low latency stream targets, bypassing Wowza Streaming Cloud transcoders. For instructions on those workflows, see More resources.

Note: In order for Wowza Streaming Cloud to convert AMF metadata to ID3 tags for HLS playback, it must be in the following format:
  • The AMF data must be included in in a top-level AMF data object (AMFDataObj). Within that AMF data object, you can include key:value pairs that include AMF data of additional types, such as string, Boolean, list, or even a nested object.
  • The AMFDataObj object must include two properties: (1) a key called payload whose value is a string of data to be converted and (2) a key called wowzaConverter whose value is basic_string. For a code example showing how to format incoming AMF data, see Inject timed metadata using a Wowza Streaming Engine HTTP provider.

For additional instructions on sending AMF metadata with a third-party encoder, see the manufacturer’s documentation.

1. Update the convertAMFData stream target property

Once you have associated a stream target with an output rendition for the transcoder, or once you have a stream_target_ID from your live stream details, configure a stream target to enable the conversion of AMF data to ID3 tags. If you use multiple stream targets with the transcoder, configure the property for each one. This allows Wowza Streaming Cloud to listen for AMF data events coming from the source encoder or camera, parse the data events, map the events to ID3 tags, and send the ID3 tags in the HLS stream.

For additional information about stream target properties, see Set advanced properties with the Wowza Streaming Cloud REST API.

Note: Unlike Wowza CDN or custom HLS streams that require you to configure the convertAMFData stream target property, backup HLS streams associated with ultra low latency stream targets have the property enabled by default. Wowza Streaming Cloud automatically converts AMF data entering an ultra low latency stream target to ID3 tags in the backup HLS stream, and you can’t disable this behavior. See More resources for more information about this workflow.

You can use the following sample request, making sure to:

  • Set stream_target_id to the id for the stream_target.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
    "property": {
      "key": "convertAMFData",
      "section": "hls",
      "value": true
    }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

Sample response

{
  "property": {
      "section": "hls",
      "key": "convertAMFData",
      "value": true,
  }
}

2. Reset the transcoder or live stream

If you have started the transcoder or live stream at any point before enabling the convertAMFData stream target property, you must reset the transcoder or live stream for the property to take effect. This step isn’t necessary if you haven’t started the transcoder or live stream at all.

You can use the following sample request, making sure to:

  • Use the /live_streams/[live_stream_id]/reset endpoint if you have created a live stream or set the transcoder_id

Sample request

Endpoint Reference

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/reset"


3. Verify the metadata in the stream


To verify that the converted AMF data is showing up as ID3 tags in an HLS stream, you can view the console log of the Wowza Streaming Cloud hosted page.

  1. Set up a live stream in Wowza Streaming Cloud that uses Wowza Player for playback and includes a hosted page.
  2. Set up a source that sends AMF data, and configure the associated stream target in Wowza Streaming Cloud to convert the AMF data to ID3 tags.
  3. Start the source and the live stream.
  4. Open the hosted page URL, play the stream, and view the console log to verify that metadata shows up in the stream. 
  5. Stop the live stream and the source.

Playback options


When a player that supports ID3 tags receives an HLS stream, it can listen for and process the metadata. Wowza™ Player and JW Player both support ID3 timed metadata.

At this time, the GoCoder SDK doesn't pass ID3 tags to native Apple and Android player frameworks, but you can build an HLS player independently that will leverage the timed metadata to invoke an action during playback.

For information on whether and how other third-party players support metadata formatted in ID3 tags, see their documentation.

More resources