Timed Metadata


In this section, you will learn how to use Rest API to insert timed metadata into live stream. Live Streaming, insert timed metadata

  1. Insert Timed Metadata into Live Stream
  2. Module Summary


Use Rest API to insert timed metadata into live stream.

Amazon Interactive Video Service uses timed metadata to enable customers to bring interactive experiences into video applications. ID3 timed metadata is used to send customized data within a live stream at specific point of time. ID3v2 tag name can be up to 4 characters, and tag value can be up to 256KB. By using timed metadata API to insert customized data into the live stream, you can develop time-synced interactive applications such as mobile trivia app, quick survey to gather user feedback, or distributing sports statistics information. Each of the clients would receive this data synchronously with the video, so the experience is consistent at different locations.

  1. Open Postman application,

    1. Select HTTP request type to POST,
    2. Input HTTP POST request URL as https://ivs.us-west-2.amazonaws.com/PutMetadata
    3. Use the same credentials as in step 2 - Create IVS Channel using API, in AccessKey, SecretKey and Session Tocken field (Session Token is only required if you are using temporary security credentials).
    4. AWS Region is us-west-2, and Service Name is ivs.
  2. Click Body section header, select raw and select JSON from the dropdown box to the right.

    You can copy and paste the following code and replace the channelArn value with your channel’s ARN value.

    {
        "channelArn": "arn:aws:ivs:us-west-2:xxxxxx:channel/X54kdkG1M12G",
        "metadata": "{\"question\": \"What pet do you have?\",\"answers\": [ \"Cat\", \"Dog\", \"Bird\", \"No Pet\" ],\"correctIndex\":2}"
    }
    

Note: You can send any string in the “metadata” field and the live streaming backend will pass it to the player. It is player’s implementation to parse the string and to create associated user presentations and make use of the data. In this example, the front end player is expect the metadata in the question and answer format to simulate a trivia game.

  1. Open a new tab https://codepen.io/amazon-ivs/pen/43773681607df81d127d24f7a3250337 on Chrome.

  2. On the top right corner of the UI, click Change View, and select Editor View. The HTML, CSS and JS sub-panels show up in the UI.

  3. Click Change View again, in Editor Layout, select first left-to-right layout.

  4. Find JS sub panel (You can double click the title bar to expand), scroll down the JavaScript code block and find const playbackUrl=. Replace the quoted URL with your channel’s Playback URL found in channel info.

  5. Click Run button on the top and your channel should start play.

  6. Check your channel and make sure it is live broadcasting. Click Send in your Postman application on the newly constructed PutMetadata API. You will see a successful response status of 204 No Content. This is player before showing metadata. This is the player showing received metadata and presented as a popup UI.

  7. The following screen shot shows areas you can find in the player UI. The hightlight video-player HTML video elemental is the player definition in HTML. The highlighted javascript in JS window shows the client side metadata handling function. To the right in the broswer web console (You can show the web console by click Home icon on the top right cornor of Chrome browser to the right of the address textfield, select More Tools, Developer Tools. The highlight shows the raw metadata the client player receives from the live stream. Web broswer player SDK integration


Module Summary

In this module, you learnt how to use Rest API to insert timed metadata into your live stream, and learnt how applications can take advantage of these data to add interactive user experiences.

Congratulations! Now you have finished this workshop! Click for Cleanup Module.