Alexa.SeekController Interface (VSK Fire TV)

When users say to skip ahead or rewind by a specific duration (such as "Alexa, fast forward 5 minutes" or "Alexa, skip ahead 60 seconds"), the Alexa.SeekController interface sends an AdjustSeekPosition directive to your app or Lambda.

Note that directives sent by the SeekController interface (such as the AdjustSeekPosition directive) are different from the fast-forward and rewind operations within the PlaybackController Interface because they include a specific duration for the offset.

Warning: With app-only integrations, instead of using SeekController, it's recommended that you use Android MediaSession for transport controls instead. Media sessions provides the same features with less latency and a more consistent customer experience. See Step 2: Integrate with MediaSession for details.

Utterances for AdjustSeekPosition directives
Handling AdjustSeekPosition Directives
Example AdjustSeekPosition Directive
Payload Definitions
- Experience Types
Response Example
Declaring Capability Support for this Interface

Utterances for AdjustSeekPosition directives

Alexa sends AdjustSeekPosition directives to your app (for app-only integrations) or to your Lambda (for cloudside integrations) when users say the following utterances.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	Fast forward thirty seconds	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	Rewind forty seconds	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	Avance de trente secondes Saute trente secondes	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	rebobina treinta segundos retrocede diez segundos	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	Avance de trente secondes Saute trente secondes	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	Rembobine de trente secondes Retour en arrière de trente secondes	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	spul/spring [Duration] lang? vor/vorwärts spring [Duration] vorwärts auf [AppName] spul [DeviceBrand] vor spring [Duration] auf [DeviceBrand] vor überspring [Duration] auf [DeviceType]	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	spul zurück spring zurück spul/spring für? [Duration] lang? zurück spring nach hinten für [Duration] spul [AppName] zurück spul [AppName] [Duration] zurück spul [Duration] auf [AppName] zurück spring rückwärts auf [AppName] für [Duration] spul auf? [DeviceBrand] zurück spul [DeviceBrand] [Duration] zurück	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	[Duration] के लिए आगे/forward जाओ [Episode] में fast forward Duration कर दें [Duration] के लिये [Episode] forward कर दें[MediaType] में [Duration] आगे जाओ[AppName] पर [Duration] आगे जाओ	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	1. पीछे जाना दस seconds 2. rewind करो forty seconds	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	manda avanti l' episodio di trenta secondi vai avanti di trenta secondi manda avanti di trenta secondi	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	manda indietro di trenta secondi manda indietro il video di trenta secondi	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification		The media fast-forwards for the requested duration.
Rewind [duration] Required for certification		The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification		The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	rebobinar/voltar [durastion]	The media rewinds for the requested duration.

Feature	Sample Utterances	Expected Response
Fast Forward [duration] Required for certification	adelanta treinta segundos salta diez minutos en la película	The media fast-forwards for the requested duration.
Rewind [duration] Required for certification	rebobina treinta segundos retrocede diez segundos	The media rewinds for the requested duration.

As with other directives, when you receive a Discovery directive, you must specify the SeekController directives that your video skill supports.

Handling AdjustSeekPosition Directives

AdjustSeekPosition directives include a property in the payload called deltaPositionMilliseconds. The value of deltaPositionMilliseconds can be positive (seek forward) or negative (go backwards in the stream).

For example, "Skip 5 minutes" would yield a deltaPositionMilliseconds value of 300000, whereas "Rewind 10 minutes" would yield a deltaPositionMilliseconds value of -600000.

In other words, a negative value indicates rewind, and a positive value indicates fast forward. You must fulfill the user's request by going forward by the specified offset.

Example AdjustSeekPosition Directive

The following is an example AdjustSeekPosition directive:

App-only Integrations
Cloudside Integrations

EXTRA_DIRECTIVE_NAMESPACE: Alexa.SeekController
EXTRA_DIRECTIVE_NAME: AdjustSeekPosition
EXTRA_DIRECTIVE_PAYLOAD_VERSION: 3
EXTRA_DIRECTIVE_PAYLOAD: payload

payload contains the following:

{
    "payload": {
    "experience": {
        "mode": "VOICE_OPTIMIZED",
         },
        "deltaPositionMilliseconds": 300000
    }
}

{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "VSKTV",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "4bef62cc-208d-4382-a43e-ce9e4825c1cb",
            "name": "AdjustSeekPosition",
            "namespace": "Alexa.SeekController",
            "payloadVersion": "3"
        },
        "payload": {
           "experience": {
              "mode": "VOICE_OPTIMIZED",
                  },
            "deltaPositionMilliseconds": 300000
        }
    }
}

Payload Definitions

The following table describes the payload properties.

Payload Descriptions
Field	Description	Data Type
`deltaPositionMilliseconds` required	The relative milliseconds to seek on the playback on a media player. A positive or negative integer value could be used to seek forward or backwards in relation to the current seek position. Accepted values include any integer value between `-86400000` and `86400000` (-/+ 24 hrs.). If the required position falls outside the duration of the media item, it should be set to the beginning or the end of it depending on if `deltaPositionMilliseconds` was negative or positive respectively. Example: `86400000`	integer
`experience` optional	An object that optimizes the display of search results. With the `experience` object, you can change the search results based on the device your customer used to search. See Experience Types for more details about the `experience` object and its values.	Object containing `mode`

Experience Types

Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote.

The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.

VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.
DEFAULT: The default displays of all search results list format, regardless of the device used for the search.

To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

If your app handled the directive successfully, your BroadcastReceiver class should send a success intent back with a success status, like this:

if (response != null && sendResponse) {
  Intent success = new Intent().putExtra(VSKIntentConstants.EXTRA_DIRECTIVE_STATUS, didSucceed);
  try {
    response.send(context, 0, success);
  } catch(PendingIntent.CanceledException e) {
    //we probably took too long to respond, log error
  }
}

For more details, see Step 7: Add a Broadcast Receiver. Also see the AlexaDirectiveReceiver class in the sample app for a more specific code example.

After you receive an AdjustSeekPosition directive and run the request, send a response back to Alexa that indicates the position state in milliseconds. The payload contains a name and value property as shown in the following example. The positionMilliseconds represents the absolute achieved seek position in milli seconds from -86400000 to 86400000.

Example

{
    "context": {
        "properties": []
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "eab7fe6e-f65d-4dbb-aeea-5bae61439f4d",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

If you cannot complete the customer request for some reason, reply with an error. See Error Handling for more details.

Declaring Capability Support for this Interface

App-only Integrations
Cloudside Integrations

To receive SeekController directives in your app, you must indicate support for this interface when you declare your capabilities. See the following for more information on declaring capabilities with app-only integrations:

To indicate that your video skill supports the Alexa.SeekController interface, you must indicate support for it in your response to the Discover directive sent through the Alexa.Discovery interface. More details are provided in Alexa.Discovery.

Last updated: Jun 09, 2021