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.

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. Incoming AMF metadata can be of different types—integer, string, or date, for example. For a streaming workflow that involves playing the content using HLS, we recommend using the dictionary type, which creates a JSON string that is easiest to convert to ID3. 

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

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.

Convert AMF data into ID3 tags


Create a transcoder to receive the source

AMF data enters Wowza Streaming Cloud through an RTMP stream that flows into a transcoder. Before enabling the property that converts AMF data to ID3 tags, you need to create a transcoder if you haven’t already.

Tips:
  • If you have already created a transcoder with associated outputs and targets in Wowza Streaming Cloud, use a GET query to fetch the details of the transcoder, including the ID of the stream target. For next steps, skip to Update stream target properties.
    curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]"
  • If you have already created a live stream in Wowza Streaming Cloud, use a GET query to fetch the details of the live stream, including the ID of the stream target. For next steps, skip to Update stream target properties.
    curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]"
  1. Create a transcoder using the Wowza Streaming Cloud REST API. Set the protocol to RTMP so that you can ingest AMF data.

    Example request and response

    Notes:
    • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
    • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.
    The following request creates a transcoder that uses any RMTP-enabled encoder, such as Wowza Streaming Engine, a mobile broadcast app created with Wowza GoCoder SDK, or a third-party encoder, as the source.
     
    curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{   
      "transcoder": { 
        "billing_mode": "pay_as_you_go",      
        "broadcast_location": "us_west_california",      
        "name": "My transcoder with AMF data",      
        "protocol": "rtmp",      
        "transcoder_type": "transcoded",
        "delivery_method": "push"
      } 
    }' "https://api.cloud.wowza.com/api/[version]/transcoders"
    
    The response includes information about the transcoder, including the transcoder ID, which you will need to associate the transcoder with output renditions and stream targets. The response does not contain outputs, and it should look something like this:
     
    {
        "transcoder": {
            "id": "abcs0prm",
            "name": "My transcoder with AMF data",
            "transcoder_type": "transcoded",
            "billing_mode": "pay_as_you_go",
            "broadcast_location": "us_west_california",
            ...
            "protocol": "rtmp",
            "delivery_method": "push",
            "source_port": 1935,
            "domain_name": "[wowzasubdomain].entrypoint.cloud.wowza.com",
            "application_name": "app-a7db",
            "stream_name": "b9c6870b",
            ...
            "created_at": "2018-08-13T18:54:38.000Z",
            "updated_at": "2018-08-13T18:54:38.000Z",
            "direct_playback_urls": {
                "rtmp": ["name and url returned here"],
                "rtsp": ["name and url returned here"],
                "wowz": ["name and url returned here"]
            },
            "outputs": [],
        }
    }
    
  2. Complete the transcoder by adding output renditions and stream targets.

    When you add a stream target, ensure that you use a Wowza stream target or custom stream target with the provider akamai_cupertino. A Wowza stream target allows delivery through the Wowza CDN, while a custom stream target allows delivery through a third party CDN. Note the stream target ID for the next section.

    For instructions, see one of the following articles, depending on whether you're creating an adaptive-bitrate or passthrough transcoder:

Update stream target properties

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.

  1. Configure the convertAMFData property for the stream target using the stream target ID. When you set convertAMFData to true, Wowza Streaming Cloud listens for AMF data events coming from the source encoder or camera, parses the data events, maps the events to ID3 tags, and sends 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.

    Example request and response

    The following request enables the convertAMFData property for a specified stream target.
     
    curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{
        "property": {
          "key": "convertAMFData",
          "section": "hls",
          "value": true
        }
    }' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties"
    The response looks something like this:
     
    {
        "property": {
            "section": "hls",
            "key": "convertAMFData",
            "value": true,
        }
    }
  2. 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.

    Example requests

    Reset a transcoder:
    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/reset"
    Reset a live stream:
    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/reset"

Playback options


When a player that supports ID3 tags receives an Apple 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