Amazon VGT2 Las Vegas: Utilizing Timed Metadata with Amazon Interactive Video Service – Part 1

Introduction

Welcome to the first part of our two-part series designed to inspire and equip developers to harness the Amazon Interactive Video Service (Amazon IVS) Timed Metadata feature. In this tutorial, we will construct a fully functional end-to-end demonstration of an Amazon IVS live stream that delivers an engaging experience for viewers. This guide serves as a straightforward introduction to the technology, allowing developers to grasp how the functionality operates.

While Amazon IVS and its underlying services are built to be highly scalable and secure, please note that this demonstration is not intended for production environments. If you’re seeking a comprehensive starter kit for your production setup, consider checking out this blog post on configuring streaming for Amazon IVS. This series is geared towards those wanting to create a learning environment for the Timed Metadata feature, with Part One concentrating on the feature itself and Part Two addressing the infrastructure necessary for a fully interactive experience.

Required Tools

Linux/Unix environment (this demo is created using Apple OS X)
Python 3.x
Boto3 Python module

Getting Started

To utilize the Amazon IVS Timed Metadata feature, you need two essential components: an active Amazon IVS channel and code that communicates with the Amazon IVS REST API. These two elements allow you to send data payloads to all viewers of the channel at once, eliminating the need for synchronization from alternative metadata delivery methods.

This feature is particularly useful for aligning interactivity with the content being broadcast. For instance, you could conduct a poll with the audience regarding the specific content presented. The channel host can pose a question, prompting the Timed Metadata feature to display a dialog box for viewers to respond.

It is important to note that the Timed Metadata feature only transmits data to viewers; it does not capture their responses. To create a complete solution, developers must implement a workflow to gather these responses. I’ve put together a simplified version to share with you. Let’s jump right in.

Solution Overview

Walk-through

In this example, we will leverage the Python Boto3 library to interact with the Amazon IVS REST API. The PutMetadata command is utilized to send a JSON-formatted dictionary of data. The video player will have a listener for the Timed Metadata event, triggering a specified function.

First, we will create a dictionary of data to transmit. For this tutorial, I’ve selected a random line from a text document to serve as the “question.” To keep it simple, I opted for a true or false question with a third, randomly chosen option to demonstrate that you can include any “answers” in the dictionary. The dictionary will also contain a poll_id and current_time to identify the chosen question and its dispatch time, as repeats may occur.

Finally, I’ll use the json.dumps command to convert the dictionary into a JSON string before sending it to the Amazon IVS API through the Boto3 Python library.

Step 1: Create the Amazon IVS Channel

Refer to one of the following guides to establish a new Amazon IVS Channel:

Tips:

Create the Amazon IVS channel in the same region as your AWS CLI profile. You can also use the “region_name” variable in the “session.Client()” within the metadata.py file.
Keep a record of the channel ARN.

Step 2: Stream to the Amazon IVS Channel

Consult one of these guides to stream to your newly created Amazon IVS Channel:

Tip: Make sure to note the playback URL.

Step 3: Set Up the Web Page Player

First, confirm the channel’s health using the test player in the Amazon IVS console. Then, you will need custom code to extract the Timed Metadata payload for injection. Let’s set up the Player to monitor your efforts.

Begin by downloading the player.html file here.

Tip: Right-click and select “Save Link As.”

In the player.html file, you need to modify one variable to direct the video.js player to your new stream. Look for:

const STREAM_URL = "CHANGEME!!"

Replace “CHANGEME!!” with the Playback URL from the Playback Configuration section of the Amazon IVS console. Ensure the URL ends with an .m3u8 file extension.

Next, host this file on a web server, as the web page will not function correctly if simply opened as a local file. One option is to host it on an Amazon S3 bucket and make the file public. Alternatively, you can enable static website hosting with Amazon S3 and place the file in that bucket. If you’re developing in a Linux or Unix environment with Python 3 installed, you can use Python’s built-in web server. Run the following command in the directory of the HTML file:

python3 -m http.server 5001

Now, point your preferred web browser (Firefox or Chrome recommended) to the URL where you hosted the player.html document. If using Python 3 http.server, it should be: http://127.0.0.1:5001/player.html.

You should see a web page similar to this.

Step 4: Set Up the Python Script

IMPORTANT: Amazon IVS is a new service that requires updating the AWS Command Line Interface and the Boto3 Python SDK for functionality. If the following command does not work, please follow the provided directions to update your AWS CLI and Boto3.

Ensure you have a version compatible with Amazon IVS by running:

aws ivs help

Now that you have a player ready to listen for Timed Metadata commands, let’s begin injecting those commands. First, you need two additional files:

metadata.py – Download the Python script here
facts.txt – Download the text document from this link (or create your own).

Tip: Right-click and select “Save Link As.”

Next, open the metadata.py script. Note that the facts.txt file contains a list of factual sentences that are randomly selected. Feel free to modify this file with your own facts, ensuring each fact ends with a new line.

For simplicity, I’ve implemented a “hash” of each line to generate a poll_id on the fly. Additionally, you’ll notice that this is set up in a loop that cycles every 10 seconds. This may not reflect how someone would use this in production, but it allows for the demonstration of new facts every 10 seconds to illustrate the Timed Metadata feature in action.

As you transition from this demo to production, I recommend replacing these examples with a more sophisticated data extraction method to create the dictionary sent to your Amazon IVS Channel. Stay tuned for future AWS Media Blog posts exploring more complex Amazon IVS workflows.