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

Introduction

Before we dive in, this blog post marks the initial installment of a two-part series designed to inspire and equip developers with the knowledge to leverage the Timed Metadata feature of Amazon Interactive Video Service (Amazon IVS). In this tutorial, you will create a comprehensive, end-to-end demonstration of an Amazon IVS live stream that offers an interactive experience for viewers. This guide is structured as a straightforward demonstration of the technology, allowing developers to grasp how the functionalities operate.

Although services like Amazon IVS are robust and secure, this demo is not intended for production environments. If you are seeking a starter kit for your production setup, consider checking out this blog post about configuring streaming for Amazon IVS. However, if your goal is to establish a sandbox environment to understand the Timed Metadata feature, then this series is tailored for you. Part one will concentrate on the Timed Metadata feature, and part two will explore the necessary infrastructure to create an immersive interactive experience.

Tools Required

Linux/Unix environment (Apple OS X was utilized for this demo)
Python 3.x
Boto3 Python module

Getting Started

To use the Amazon IVS Timed Metadata feature, you need two essential components: an active Amazon IVS channel and code that interacts with the Amazon IVS REST API. With these two elements of the Amazon IVS Service, you can transmit a payload of data to all viewers of the channel simultaneously, eliminating the need for synchronization from an alternative metadata delivery method.

This feature is particularly beneficial for aligning interactivity with the channel content. For instance, a poll could be presented to viewers regarding the specific content being shown. The channel host could pose a question, and with the Timed Metadata feature, a dialog box could prompt viewers to respond.

It’s important to note that the Timed Metadata feature only transmits data to viewers; it does not capture responses. To create a complete solution, developers would need to devise a workflow to gather those responses. I have prepared a basic version of this to share with you, so let’s get started.

Solution Overview

Walk-through

In this example, I will utilize the Python Boto3 library to interact with the Amazon IVS REST API. The PutMetadata command is employed to deliver data in JSON format. The video player will have a listener for the Timed Metadata event, executing a function upon receiving it.

First, we need to generate a dictionary of data to transmit. For this tutorial, I chose a random line from a text file as the “question.” To keep it simple, I’ve opted for a true or false question, with a third randomly selected option to demonstrate that you can include any “answers” in the dictionary. Additionally, I added a poll_id and current_time to track which question was chosen and when it was sent, in case of repeats.

Finally, I’m using the json.dumps command to convert the dictionary into a JSON-formatted string. I then utilize the Boto3 Python library to send this information to the Amazon IVS API.

Step 1: Create the Amazon IVS Channel

Refer to one of the following resources to create a new Amazon IVS Channel:

Tips:

Ensure that the Amazon IVS channel is created in the same region as your AWS CLI profile. You may also use the region_name variable inside the session.Client() in the metadata.py file.
Make sure to note the channel ARN.

Step 2: Stream to the Amazon IVS Channel

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

Tip: Remember to note the playback URL.

Step 3: Set Up the Web Page Player

First, confirm that the channel is healthy using the test player in the Amazon IVS console. You will need custom code to extract the Timed Metadata payload to be injected. Let’s get the player up and running to monitor your progress.

Begin by downloading the player.html document here.

Tip: Right-click and select Save Link As.

In the player.html document, you need to modify one variable to link 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. The URL should end with an .m3u8 file extension.

Next, host this file on a web server, as the web page will not operate correctly if you simply double-click the file name to open it as a local file. One option is to host the file on an Amazon S3 bucket and make it public. You could also enable static website hosting with Amazon S3 and place the file in that bucket. If you are developing in a Linux or Unix environment with Python 3 installed, you can quickly use Python’s built-in web server by running this command in the directory of the HTML document:

python3 -m http.server 5001

Now, direct your favorite web browser (we recommend Firefox or Chrome) to the URL where you placed the player.html document. If you used 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 necessitates an update of the AWS Command Line Interface and boto3 Python SDK to function properly. If the following command does not work, please follow the instructions to update your AWS CLI and boto3 to proceed. You can use the following command to verify you have a version that supports Amazon IVS:

aws ivs help

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

Tip: Right-click and choose Save Link As.

Next, open the metadata.py script. Notice that there is a facts.txt file containing a list of factual statements selected at random. I encourage you to modify the file with your desired facts for demonstration purposes. Just ensure each fact is on a new line.

I’ve also taken the liberty of generating a hash of each line to create a poll_id dynamically, which keeps the code simple. If you observe closely, you’ll notice this code runs in a loop every 10 seconds. While this may not be how someone would use this in production, it allows you to send new and interesting (cat) facts every 10 seconds, showcasing the Timed Metadata feature in action.

As you transition from this demo to production, I recommend replacing these examples with a more sophisticated method of extracting data to populate the dictionary sent to your Amazon IVS Channel. My intention was to keep this simple for demonstration purposes. Stay tuned for future posts on the AWS Media Blog, where we will delve into more complex Amazon IVS workflows.