Developer Console
Sign In
Sign In
Developer Console

Video Skills Kit (VSK) for Fire TV Overview

The Video Skills Kit (VSK) for Fire TV allow customers to use natural language commands to search for and play your app's content, control media playback, and more. For example, when you implement the VSK in your app, customers can say phrases like "Play Bosch from app name" or "Play Bosch," and your app will play the media. The VSK works together with catalog integration to surface your content in multiple ways across Fire TV.

Video Tutorial

The following is a high-level video tutorial about integrating the VSK into your Fire TV app using the app-only integration:

Voice Capabilities with Catalog Integration

A prerequisite to integrating your app with the VSK is to first ingest your catalog and then integrate with Fire TV's universal search and browse (also referred to as "launcher integration"). When you complete this catalog integration, your customers receive app launch capabilities and implicit quick play. For example, customers can say the following:

  • App launch: "Open app name"
  • Implicit quick play: "Watch video name"

Implicit means the app isn't specified in the request, so Fire TV looks in all catalogs for the matching video. If the customer says the request with an app open (in the foreground), Fire TV first looks within this app's catalog.

Voice Capabilities with VSK Integration

By integrating the VSK with your app, you can give your customers many more voice capabilities, allowing customers to more easily discover, find, and engage with content in your app (without relying on a remote). When you integrate with the VSK, Alexa delivers the requests directly to your app (in the form of JSON-based information blocks called "directives") so that you can process the requests with your own app's logic. This gives you more control and capability about how to interact with customer's requests (called "utterances").

When you integrate with the VSK, there are two primary VSK interfaces you interact with: SearchAndPlay (which includes "watch/play …" requests) and SearchAndDisplayResults (which includes "search/find …" requests). The API reference describes the full list of utterances supported by these interfaces and the directives they send to your app. In addition the app launch and implicit quick play (already provided with catalog integration), here are a few examples of requests that customers can say when you integrate the VSK.

Feature Utterance or Example
Watch title (explicit) "Watch video name on app name"
Search by genre "Find genre name"
Search by actor "Search for actor name movies"
Watch by franchise "Watch franchise on app name"
Search by production company (explicit) "Search for production company on app name"
Watch by sports type "Watch sports type"
Watch by season and episode "Watch TV show season 2, episode 3
App foreground/background state contextual search disambiguation User: "Watch comedies"
App in foreground: (Alexa) "Here are some comedies"
App in background: (Alexa) "I can do that on app 1 or app 2, which would you like?"
Multi-turn capability (following disambiguation) (User) "app 2"
(Alexa multi-turn) "Okay, here's genre name on app 2"
Feature gate by user state Add or remove app capabilities based on user or app state changes

The above table provides only a few examples of the supported utterances. See SearchAndPlay and SearchAndDisplayResults for a more comprehensive list of utterances and the directives sent. Or if you just want to browse utterances by directive, see the Utterances Reference.

Expectations in Handling Directives

As you integrate your app with the VSK, you should understand what directives your Fire TV app will receive and how you're expected to handle them. A directive is a set of data and instructions, expressed in JSON, sent from Alexa to your app. For example, the directive might be to search for a TV show or play a movie. If a user says, "Watch Batman," Alexa sends your app a SearchAndPlay directive with the following payload:

{
  "searchText": {
    "transcribed": "batman"
  },
  "entities": [
    {
      "externalIds": {
        "ENTITY_ID": "123"
      },
      "type": "Franchise",
      "uri": "entity://avers/franchise/Batman",
      "value": "Batman"
    }
  ]
}

transcribed is a reduced version of the phrase the customer used in the request. uri is your catalog's identifier for the media. type indicates that this media is part of a franchise ("franchises" are movies with sequels). The payload objects are defined in detail in the corresponding API Reference.

Alexa sends these directives to your app, and you're expected to react to the directive (e.g., show results for a request, or play the requested video). This documentation will describe the directives but not provide detailed instruction on how to handle the directives in your app — that logic is something you need to develop on your own.

VSK Implementation Options: App-only or Cloudside

You can implement the VSK into your Fire TV app in two different ways:

  • App-only integration: Receive directives delivered directly in your app. A service on Fire TV called the VSK Agent routes directives from Alexa to your app by way of broadcast intents. A BroadcastReceiver in your app handles the intents. (This implementation, which uses intents and BroadcastReceivers, follows a pattern similar to catalog integration.)
  • Cloudside integration: Receive directives to a Lambda function in AWS and then send the directives (or the result after processing the directive) to your app through a messaging service (usually Amazon Device Messaging). Your app authorizes the incoming message and then handles the request.

Cloudside integration was the original way to integrate the VSK. However, cloudside integration involved many AWS components (Lambda, IAM, ADM, CloudWatch, etc.) and required a lengthy development time. The app-only implementation (more recently released) requires much less development time and doesn't involve any AWS components. All your integration is done natively within Android.

Additionally, app-only implementations provide a significant performance improvement because there are no middle steps with messages sent to Lambda and ADM. Everything happens directly within your app and the VSK Agent on Fire TV. Because of the speed and ease of implementation, app-only integrations are now the default recommended path for partners.

Cloudside integrations will still be supported and available for partners who have already implemented the VSK this way, or for partners who prefer the cloudside approach. Cloudside implementations might still be a good option for partners who have complicated logic or complex processing and lookups that would be better handled with an external Lambda function rather than coded directly within your Android app. Cloudside implementations might also be preferable for partners who want to externalize their handling logic outside of their app to integrate with services or systems that have constraints about being accessed on Fire TV.

Sample Apps

Both app-only and cloudside integrations have sample apps (based on Android TV Leanback library) demonstrating the integration (see the app-only sample app and the cloudside sample app). Given that VSK implementations can be lengthy, many partners want to explore how the VSK works (and see directives hitting the app or Lambda) in an immediate way to better understand expectations. The sample apps provide a quick way to explore VSK-integrated apps and also serve as a reference for the integration. In this documentation, instructions related to sample apps often appear in callouts like this:

Sample App Notes

This is a note about the sample app. Often this note will indicate if some coding is required in the current step, or if the coding is already done in the sample app.

What You'll Need

To complete the VSK integration, you'll need the following:

  • Fire TV device. You can use any Fire TV device to test the integration. You can use the microphone button on the Fire TV device's remote control to make voice requests to the TV. (If your remote control doesn't have a microphone, you can pair an Echo to your Fire TV.) The recommended Fire TV is Fire TV Stick 4K, but any Fire TV device will work.
  • Android app. You need a native Android app that can play streaming media. If you don't have an app, or if you want to explore the VSK through a sample app, sample apps are available.
  • Catalog integration. You need to integrate your catalog before you can complete the VSK integration. If you haven't started this yet, you can use the sample app's catalog during development.
  • Amazon developer account. You need an Amazon developer account (it's free). If you don't already have an account, go to developer.amazon.com, click Sign In in the upper-right corner, and then click Create your Amazon Developer account.

Supported Countries

VSK support varies by country. When the VSK is supported in a country, it means Alexa can understand user's requests in that country's language, including many local entities (e.g., sports teams or movie titles specific to that country). See Supported Countries for Video Skills on Devices for more details.

Glossary

Alexa introduces many new terms that might be unfamiliar. You can find definitions of terms in the Glossary.

Next steps

To take the next step, start by reading a high-level description of the App-only integration, which is the recommended VSK integration.

Last updated: Mar 05, 2021