Build Smart Home Skills for Entertainment Devices
Smart home skills created for home entertainment/AV devices give customers voice access to their smart TV, cable boxes and other entertainment devices. For example, with the appropriately-configured smart home skill, a customer can say, "Alexa, increase the volume on the TV" and hear the volume increase on their TV.
This document provides a overview of the technical requirements as well as specific directives and error messages for smart home skills that target entertainment devices.
Get started
If this is your first time creating a smart home skill, you should review the existing documentation as a prerequisite to this document. You will need to be familiar how to create a smart home skill and write the code for a Lambda function that handles requests from the Smart Home Skill API. For more information see:
Skill implementation
The next sections provide details about implementing a smart home skill for entertainment devices.
Smart home skills for entertainment devices
When you create a skill for entertainment devices, you need to make sure you receive messages for the entertainment device control in the Smart Home Skill API. To do this, select v3, and one of the English language options in the developer console when you create your skill.
For more information and detailed steps, see Steps to Create a Smart Home Skill.
Message Format
Alexa sends your skill a directive as a result of a customer request and you send back an event indicating the request was successful or an error message. Alexa can then respond appropriately to the customer. Entertainment device control in the leverages message formats defined by payload version 3 of the API. Each device is an endpoint described by a list of interface capabilities in the discovery response. Each interface provides directives that are sent by Alexa to the skill and events that can be sent from the skill back to Alexa. An interface also defines reportable properties that you might send in a response event to describe the current state of the entertainment device. For example, for a device that can change channels, you would implement the Alexa.Discovery interface and the Alexa.ChannelController interface, which defines channel as a reportable property.
Discovery for Entertainment Devices
When you describe devices, you will also describe the capabilities associated with each device, and properties that you support for each capability.
If your endpoint supports the PlaybackController interface, you must specify the operations the endpoint supports in a supportedOperations string array in your discovery response.
In addition, you should provide the displayCategory for the device, which enables it to display properly in the Alexa app. For entertainment endpoints this could be one of the following:
- SPEAKER - Indicates the endpoint is a speaker or speaker system.
- TV - Indicates the endpoint is a television.
The following code example shows how you might describe an entertainment device. For more information on device discovery messages, see Alexa.Discovery.
If you are discovering an endpoint that supports EqualizerController, see the Discovery section of EqualizerController for the configuration requirements in a discovery response.
Example Discovery Response for an Entertainment Device
{
"event":{
"header":{
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
"messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
},
"payload":{
"endpoints":[
{
"endpointId":"appliance-001",
"friendlyName":"Living Room Entertainment System",
"description":" Entertainment System by Sample Manufacturer",
"manufacturerName":"Sample Manufacturer",
"displayCategories":[
"TV"
],
"cookie":{
"extraDetail1":"optionalDetailForSkillAdapterToReferenceThisDevice",
"extraDetail2":"There can be multiple entries",
"extraDetail3":"but they should only be used for reference purposes",
"extraDetail4":"This is not a suitable place to maintain current device state"
},
"capabilities":[
{
"type":"AlexaInterface",
"interface":"Alexa.Speaker",
"version":"1.0",
"properties":{
"supported":[
{
"name":"volume"
},
{
"name":"muted"
}
]
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.ChannelController",
"version":"1.0",
"properties":{
"supported":[
{
"name":"channel"
}
]
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.PlaybackController",
"version":"1.0",
"properties":{ },
"supportedOperations" : ["Play", "Pause", "Stop"]
},
{
"type":"AlexaInterface",
"interface":"Alexa.InputController",
"version":"1.0",
"properties":{
"supported":[
{
"name":"input"
}
]
}
}
]
}
]
}
}
}
Interfaces for Entertainment Devices
To act on customer requests, you will need to parse Alexa request messages and compose Alexa.Response events to respond. If an error occurs, you will need to return the correct error message.
Messages are defined in interfaces, which are organized by device capability.
The interfaces that describe entertainment device capabilities are described in the following table.
| Operation | Capability Interface |
|---|---|
| Turn things on and off | Alexa.PowerController |
| Change the channel on a device | Alexa.ChannelController |
| Change the equalizer settings such as adjusting a band, or changing the equalizer mode. | Alexa-EqualizerController |
| Change the input of a playback device | Alexa.InputController |
| Control the playback of device; fast forward, rewind and pause | Alexa.PlaybackController |
| Change the volume in incremental steps | Alexa.StepSpeaker |
| Change the volume to anywhere on a continuous range | Alexa.Speaker |
| Indicate an error has occurred | Alexa.ErrorResponse |