Ingest and convert timed metadata with the Wowza Video REST API

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

In this article, learn how to ingest AMF data into Wowza Video, convert AMF data into ID3 tags using the Wowza Video 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.

About AMF data ingested into a Wowza Video transcoder

Wowza Video 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 Video.

Wowza Streaming Engine can send single bitrate streams that contain AMF metadata to a Wowza Video transcoder. For instructions on these workflows, see More resources.

Info

In order for Wowza Video 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 Video 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 Video REST API.

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

Copy

Copied

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
    "property": {
      "key": "convertAMFData",
      "section": "hls",
      "value": true
    }
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/[stream_target_id]/properties"

Sample response

Copy

Copied

{
  "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

Copy

Copied

curl -X PUT \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_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 Video hosted page.

Set up a live stream in Wowza Video that uses Wowza Player for playback and includes a hosted page.
Set up a source that sends AMF data, and configure the associated stream target in Wowza Video to convert the AMF data to ID3 tags.
Start the source and the live stream.
Open the hosted page URL, play the stream, and view the console log to verify that metadata shows up in the stream.
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.

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