Alexa.SeekController Interface 3
The Alexa.SeekController
interface provides directives to navigate to a specific position in a media item. You should implement this interface for your devices and services that can seek to a specific position. If a device or service can only fast forward or rewind a media item, implement the Alexa.PlaybackController
interface instead.
For the list of languages that the Alexa.SeekController
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Utterances
The Alexa.SeekController
interface uses the pre-built voice interaction model. After the user says one of the following utterances, Alexa sends a corresponding directive to your skill.
The following examples show some user utterances:
Alexa, skip thirty seconds on device.
Alexa, go back ten seconds on device.
Alexa, fast forward thirty seconds.
Alexa, rewind forty seconds.
Alexa, springe dreißig Sekunden auf dem Gerät vor.
Alexa, springe zehn Sekunden auf dem Gerät zurück.
Alexa, spul dreißig sekunden vor.
Alexa, spul dreißig sekunden zurück
Alexa, saute trente secondes sur l'appareil.
Alexa, retourne dix secondes sur l'appareil.
Alexa, avance de trente secondes.
Alexa, retour en arrière de trente secondes.
Alexa, डिवाइस पर तीस सेकंड छोड़ें।
Alexa, डिवाइस पर दस सेकेंड पीछे जाएं।
Alexa, fast forward करो दस seconds
Alexa, पीछे जाना दस seconds
Alexa, salta trenta secondi sul dispositivo.
Alexa, torna indietro di dieci secondi sul dispositivo.
Alexa, vai avanti di trenta secondi.
Alexa, manda indietro di trenta secondi.
アレクサ、デバイスで30秒スキップして
アレクサ、デバイスで10秒戻して
アレクサ、三十秒早送り
アレクサ、三十秒巻き戻し
Alexa, pular trinta segundos no dispositivo.
Alexa, saltar trinta segundos no dispositivo.
Alexa, voltar dez segundos atrás no dispositivo.
Alexa, avançar trinta segundos.
Alexa, voltar trinta segundos.
Alexa, sáltate treinta segundos en el dispositivo.
Alexa, retrocede diez segundos en el dispositivo.
Alexa, adelanta treinta segundos.
Alexa, rebobina treinta segundos.
Alexa, skip dertig seconden op device.
Alexa, ga tien seconden terug op device.
Alexa, spoel dertig seconden vooruit.
Alexa, spoel veertig seconden terug.
Reportable properties
The Alexa.SeekController
interface uses the positionMilliseconds
property as the primary property. The positionMilliseconds
property is an integer that represents the current absolute time position in a media item. The valid range is 0 — 86400000, inclusive. You identify that you support the property in your discovery response.
The following example show the positionMilliseconds
property.
{
"name":"positionMilliseconds",
"value": 5000
}
Discovery
You describe endpoints that support Alexa.SeekController
by using the standard discovery mechanism described in Alexa.Discovery
.
For the Alexa.SeekController
interface, include the positionMilliseconds
property and set retrievable
and proactivelyReported
to false
. Set retrievable
to true
as appropriate for other interfaces that you implement in your skill.
Use TV
, STREAMING_DEVICE
, GAME_CONSOLE
, or other appropriate display category. For the full list of display categories, see display categories.
Discover response example
The following example shows a Discover.Response
message for a device that supports the Alexa.SeekController
.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "device name, displayed in the Alexa app",
"displayCategories": ["TV"],
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.SeekController",
"version": "3",
"properties": {
"supported": [{
"name": "positionMilliseconds"
}],
"proactivelyReported": false,
"retrievable": false
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
Alexa sends the following Alexa.SeekController
interface directives to your skill.
AdjustSeekPosition directive
You can send the AdjustSeekPosition
directive to request a relative adjustment to the playback position of a media item.
AdjustSeekPosition directive example
The following example shows an AdjustSeekPosition
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.SeekController",
"name": "AdjustSeekPosition",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "videoDevice-001",
"cookie": {
"key": "value"
},
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
}
},
"payload": {
"deltaPositionMilliseconds": -30000
}
}
}
AdjustSeekPosition directive payload
The following table shows the payload details for the AdjustSeekPosition
directive.
Field | Description | Type | Required |
---|---|---|---|
|
The number of milliseconds, relative to the current seek position, to move forward or backward in playback in the media item. Use a positive number to seek forward and a negative number to seek backward. If the required position falls outside the duration of the media item, set the position to the beginning if |
Integer |
Yes |
AdjustSeekPosition response
If you handle a AdjustSeekPosition
directive successfully, respond with an Alexa.Response
event. In the context object, include the value of the positionMilliseconds
property.
Apply the deltaPositionMilliseconds
, specified in the AdjustSeekPosition
directive, to the current playback position and set the results in the positionMilliseconds
property. The value of positionMilliseconds
should never be negative. If the delta would cause the new playback position to be less than 0, return 0.
For example, if playback is at 00:05:30 (5 minutes and 30 seconds or 330000 milliseconds) and a user says, "rewind 30 seconds", Alexa sends an AdustSeekPosition
directive with a deltapositionMilliseconds
value of –30000. The AdjustSeekPosition
response includes the positionMilliseconds
with a value of 300000, which is equal to the previous position minus the delta.
The following example shows a AdjustSeekPosition
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.SeekController",
"name": "positionMilliseconds",
"value": 300000,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
AdjustSeekPosition directive error handling
If you can't handle a AdjustSeekPosition
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event.
For general errors, respond with a generic Alexa.ErrorResponse
event.
StateReport event
StateReport
to respond to the AdjustSeekPosition
directive is deprecated. Use the AdjustSeekPosition
response to reply instead.Related topics
Last updated: Aug 23, 2024