1. Introduction
Customers can search and play content in Fire TV using both remote and voice. Universal Search and Browse allows customers to discover content on Fire TV, regardless of whether or not they have applications installed. When a customer searches for content such as a movie or TV Show, Fire TV shows a list of all relevant content titles. Customer can then open a content detail page and see different watch options. Customer can initiate playback from the watch option using remote. Similarly, customer can search/play a movie or TV Show using voice commands without opening the application. Refer Fire TV VSK certification page to understand all supported utterances.
Fire OS applications enable universal search and browse through catalog and launcher integrations. Video Skill Kit (VSK) enables Fire OS applications to add voice-based content search and play. Vega replaces launcher and VSK integrations with a single API called Content Launcher API.
In this article, we will explain how content search and play are handled in both Fire OS and Vega devices.
2. Catalog integration overview
Catalog ingestion is the process of submitting an application’s media metadata to Amazon. All the metadata of application’s media are captured in a catalog file using the XML schema, called Catalog Data Format, defined by Amazon. This catalog file is then uploaded to an S3 bucket for Amazon to ingest. Amazon consolidates the media metadata into a centralized content database eliminating duplicate entries. Content metadata in this database is used for content search and play across various devices including Vega devices.
The diagram below illustrates elements of the catalog. Among all the metadata captured using the schema, “ID” and “LaunchId” are used in the application to identify the content and play. ”ID“ is an unique identifier that allows to launch a specific content title. “LaunchId” is another unique identifier that allows to launch a content title with a specific configuration, such as video quality, audio language, or subtitles.
Partner
└── Works
├── Movie
│ ├── ID
│ ├── ExternalID
│ ├── Titles
│ │ └── Title
│ ├── Offers
│ │ ├── SubscriptionOffer
│ │ │ ├── Regions
│ │ │ └── LaunchDetails
│ │ │ │ └── LaunchId
│ │ └── FreeOffer
│ │ ├── Regions
│ │ └── LaunchDetails
│ │ └── LaunchId
The example below from a catalog shows a movie called Seabound. This movie is offered in both SD and UHD format. It is free to watch in SD format and subscription is needed to watch in UHD format. Movie Seabound is represented by ID “1700000725” , and it has to offers with launchIds “tv.streamz/movie/467200001” and “tv.streamz/movie/467200002”.
...
<Movie>
<ID>1700000725</ID>
<Title locale="en-US">Seabound</Title>
<Offers>
<SubscriptionOffer>
<LaunchDetails>
<Quality>UHD</Quality>
<Subtitle>en-US</Subtitle>
<LaunchId>tv.streamz/movie/46720001</LaunchId>
</LaunchDetails>
</SubscriptionOffer>
<FreeOffer>
<Regions>
<Territories>US</Territories>
</Regions>
<LaunchDetails>
<Quality>SD</Quality>
<Subtitle>en-US</Subtitle>
<LaunchId>tv.streamz/movie/467200002</LaunchId>
</LaunchDetails>
</FreeOffer>
</Offers>
</Movie>
...
3. Fire OS devices
3.1 How Fire OS handles search and play through remote
Catalog is used to search App’s content in Fire TV. Search results on Fire TV show content from applications that have implemented Universal Search and Browse. When a customer selects a content title from the search result, the content details page appears. Below the content, customer can see different ways to watch the content. The viewing option shown here is called “Buy Box.” Refer to Getting Started with Universal Search and Browse on Fire TV to learn more about Buy Box and watch option details.
Catalog integrated Fire OS application must integrate with Amazon Fire TV’s launcher. With this integration, application sends login status when it is launched and whenever the login status changes. Launcher uses this information to identify watch options and update “Buy Box” accordingly. When customer clicks in the watch button to play the content, application gets broadcast intent with selected content’s or from launcher. If catalog includes LaunchId, launcher sends LaunchId to the application, otherwise ID is sent.
In below example, customer launches the title “Seabound” from Fire TV home screen using remote. The diagram shows the relation between catalog entry and the broadcast intent received by the application. Application uses the LaunchId to fetch the URL for Seabound and plays it.
Note : LaunchId is an optional element in catalog. When LaunchId is present in catalog, application will receive LaunchId. If LaunchId is not present, application will receive ID .
3.2 How Fire OS handles search and play through voice
When Fire OS application has voice integration using VSK, customer can search or play content using utterances like “Alexa, Play Seabound on Streamz”. Alexa leverages catalog integration to fetch content details. Refer to Fire OS VSK integration overview for more details about Fire OS VSK.
Fire OS applications have two options to integrate voice : App-only integration and Cloudside integration. Both implementations have the same features (same data schema, capabilities and functionality). But App-only integration is a simplified new approach without any cloud side component to implement. Currently only App-only integration is offered to Fire OS applications. Already launched cloudside integrated applications continue to work.
Alexa converts the user utterances into directives. A directive is a set of data and instructions, expressed in JSON, that Alexa sends to the app. VSK defines various directives for play, In-App search, transport control and UI Controller . Fire OS applications can implement only required directives based on the features they support. For example, if an application does not have search functionality, it can implement only RemoteVideoPlayer.SearchAndPlay, but not RemoteVideoPlayer.SearchAndDisplayResults.
Alexa directives are sent to the application by broadcast message in App-only integration. Directive will have one or more IDs that the application will use to identify and play/search content. ID is fetched by Alexa from application’s ingested catalog. Below example shows mapping between catalog entry and Alexa directive for an utterance to play content “Seabound” in application Streamz.
4. Vega devices
4.1 How Vega handles voice and remote input
Vega Developer Tools provides single API to enable content search and play in Vega devices. Content can be searched and played using remote, touch, or voice through the modality agnostic Content Launcher API. Unlike Fire OS applications, Vega applications will implement single interface using Content Launcher API to support both remote and voice.
Note : Same catalog published for Fire OS devices will be used by Vega devices too. No rework is needed on the catalog xml file you are already submitting.
Catalog integrated applications must implement Content Launcher regardless of VSK integration in Fire OS. Content Launcher will replace both Cloud-side and App-side integrations in Vega. Vega devices will use same catalog published for Fire OS without any change.
Additionally , content launcher integrated App must implement Account Login API to send login status to Fire TV. Login status sent using Account Login API is used by Fire TV to control playback behaviour. Login status is sent on app launch time, status change and whenever Fire TV requests
Follow Account Login integration and Content Launcher integration guides to start the integrations.
Related resources
- Universal Search and Browse in Fire OS
- Video Skill Kit (VSK) for Fire OS
- Content Launcher overview
- Content Launcher integration guide
- Content Launcher and Account Login API reference
- Sample App with Content Launcher
Note: " At this time,Content Launcher and Accoount Login are available to select partners only."