Published on October 4, 2022 (over 1 year ago)

Building a Recommendation Engine with Amazon Personalize and Mux

Dave Kiss
By Dave Kiss9 min readPartnerships

We’ve all been there: after a long work week, you’re finally ready to just curl up, throw on a show, and veg out for a few solid hours. You load up your favorite streaming app, warm up a bowl of popcorn, pull the blanket up over your shoulders, and start browsing.

And browsing. And browsing.

“What do I want to watch? Is it a comedy night? Horror? Documentaries are cool, but some get boring quickly. I’ve heard about Movie X, maybe I should put that on? What?! Three hours? No way, I’ll be asleep by then. Maybe just a feel good show. Eh. The Office? Again?”

“You know what. I’m just gonna go read.”

Ugh. It cuts deep. And, if you’re anything like me, the analysis paralysis can occur even if I only have a few options available to me. Do I want pizza or tacos? Should we go to this park or that park? Sometimes, it’d be so much easier if someone else would just make the decision for me.

Many applications have started to implement the personalization tech to do just that. By gathering information about what you’ve previously enjoyed in addition to what others like you seem to enjoy, it’s possible for machine learning algorithms to make recommendations that might be a good fit for you or your users, alleviating them from having to make yet another decision in the busy lives that they lead.

So, how might you build viewer recommendations for your Mux videos into your application?

In this article, I’ll show you one way you can start to incorporate a recommendation engine into your application that can suggest to your users which of your Mux videos they should watch next. This will help your viewers stay engaged by surfacing video content they may not have found on their own and promote intelligent discovery of your content based on past viewing behavior.


For this article, we’ll be using Amazon Personalize along with Amazon Kinesis to record viewing activity and build recommenders for what to watch next.

To alleviate most of the manual labor for getting the required AWS resources provisioned and configured, we’re going to be using the AWS CDK library which allows for defining infrastructure as code. You can learn more about AWS CDK in the AWS documentation.

Note: the following infrastructure stack will provision billable resources into your AWS account. Please be aware that you’ll be billed according to current AWS pricing. You can see more information by visiting the Billing page in your AWS account.

Mux has a strong partnership with AWS, and can work with you and our AWS team to provide AWS Credits to offset a POC - reach out to your nearest friend at Mux (support, account lead, for more info.

To get started, clone our recommendation engine starter kit repo from GitHub. You’ll also need to install the AWS CDK library which can be done by running the following command in your terminal:

npm install -g aws-cdk

Now, you’ll need to provide the library with access to your AWS account. You can do so by installing the AWS CLI tool and then running the following command in your terminal and following the instructions on screen:

aws configure

Lastly, if you haven’t previously used the AWS CDK, you’ll need to bootstrap your AWS account which provides a few required resources that the CDK uses during deployments. You can do so by running the following command in your terminal:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

LinkStep 1: Stream your Mux video viewing data to Kinesis

In order to allow Amazon Personalize to make content recommendations, we’ll need to make sure it is aware of the content library that is available for the viewer to watch. To do this, we can hook up our Mux account to a new Amazon Kinesis stream that will receive viewing data in real-time as it happens.

You’ll need to configure your CDK stack with an External ID that can be retrieved while setting up a new streaming export integration within your Mux account.

LinkStep 2: Configure a Lambda function to import your Kinesis data into Amazon Personalize

In the provided CDK stack, you will find a lambda handler function that is wired up to the Kinesis stream which was also provisioned. When data is detected inside of the Kinesis buffer, it will be piped to this handler function and be acted upon according to the code inside of the handler.

For this example, we’re going to take the Viewer’s following data from each view and send it over to Amazon Personalize as information that can be used to model future recommendations:

  • browser
  • longitude and latitude
  • region
  • country
  • device type

There’s one gotcha here: AWS CDK doesn’t currently support provisioning Amazon Personalize Event trackers, so we’ll have to sign in to the AWS console and do that manually.

  1. Visit the main dashboard for Amazon Personalize here

You’ll need to copy this UUID and paste it into the Lambda handler function located at lib/kinesis-handler-lambda/index.ts

Look for the code block that looks like this, and substitute the placeholder value with the Tracking ID value provided to you in the steps above.

/** * 3. Store the interaction */ const interactionResponse = await personalizeClient.send( new PutEventsCommand({ sessionId, trackingId: "974a1b08-cf4e-4670-a79a-6e3ad7925d6f", // Replace this with your own event tracking ID userId, eventList: [{ eventType: "Watch", sentAt: new Date(), itemId: assetId, properties: JSON.stringify({ browser, country, latitude, longitude, viewerDeviceCategory, region }) }] }) );

LinkStep 3: Configure Amazon Personalize recommenders for your content

Now that your viewing data is being sent to Amazon Personalize in real-time, let’s set up recommenders based on patterns that Amazon Personalize will detect within the data.

While not supported in the AWS CDK at this time, setting up recommenders is a simple process within the AWS console. Check out the AWS documentation for the most recent approach to setting up your recommenders.

In order to be minimally effective, you’ll need to have at least 1,000 views imported into Amazon personalize before creating a recommender. If you don’t feel like waiting, skip to the bottom of this article to learn more about how you can backfill your personalization data using historical view data from your Mux account.

LinkStep 4: Get video recommendations in real-time

To retrieve recommendations for what to suggest the viewer watches next, your client application will need to make an HTTP request to an endpoint generated by the AWS CDK stack.

To find out the value of your function’s URL, visit the Lambda dashboard homepage. Find the function name that starts with MuxExampleAwsRecommendati-muxrecommendfunction and click on it to bring up the function overview page.

Under the function overview panel, you will see the value for the Function URL on the right side of the page:

When you make a GET request to this URL, it will invoke the function and attempt to retrieve recommendations from Amazon Personalize based on two query parameters which you’ll need to add to the end of the URL:

  • userId: This is the unique identifying value of the viewer for whom you’re looking to fetch recommendations for
  • assetId: This is the unique identifier for the asset that the viewer had just finished viewing, if any

In the above example, the resulting URL would look something like this:

If you browse the handler code for this function, you’ll see that these query parameters are proxied into the Amazon Personalize GetRecommendations call. We’ve also pre-configured this function to use the BecauseYouWatchedX recommender by default, but you can change that to meet your application criteria if you need something different.

A successful request to your URL will return an array of recommended assets that can be parsed in your application and displayed to your viewer in however fashion you see fit.

LinkBonus: importing historical viewing data into Amazon Personalize

Wouldn’t it be nice to use previous viewing data to help drive recommendations into the future? If you’re using Mux Data, you’ll have access to a minimum of 35 days worth of data retention. It’s possible to write a script that would paginate through the List Video Views endpoint of the Mux Data API and aggregate a list of all of the view IDs currently accessible in your account.

Then, you could loop through each of the view IDs and make a request to the Get Video View endpoint which will provide you with expanded details about a specific viewing session. You can pull out the relevant data and import it into Amazon Personalize on-demand, similar to how we’re importing the streaming view data in our custom lambda function handler.

Running a script like this will provide additional context for your AWS Recommenders and could improve your user’s recommendations.

LinkWrapping up and Recommendations

So that’s it! We’ve covered a lot in this article, but with this information, you should be well-equipped to build a recommendation system of your own – even if you’re not using Mux video. If you have any questions about this approach, reach out to us! We’re on Twitter @MuxHQ or feel free to contact our support squad.

I think it would be a let down if I didn’t end this article with a few recommendations of what you should check out next. You might like reading about implementing our real-time engagement stats, eh?

Written By

Dave Kiss

Was: solo-developreneur. Now: developer community person. Happy to ride a bike, hike a hike, high-five a hand, and listen to spa music.

Leave your wallet where it is

No credit card required to get started.