We want to hear your thoughts on the Google Smart Home platform. Join a user study and receive a gift for your input. Click here to sign up.

Smart Home TransportControl Trait Schema

action.devices.traits.TransportControl - This trait is used for devices which are able to control media playback (for example, resuming music while it is paused).

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
transportControlSupportedCommands Array <String>

A list of strings describing supported transport control commands on this device.

Supported values:

CAPTION_CONTROL
NEXT
PAUSE
PREVIOUS
RESUME
SEEK_RELATIVE
SEEK_TO_POSITION
SET_REPEAT
SHUFFLE
STOP

Required:

  • transportControlSupportedCommands
Examples

Device supporting playback commands

{
  "transportControlSupportedCommands": [
    "NEXT",
    "PREVIOUS",
    "PAUSE",
    "STOP",
    "RESUME"
  ]
}
Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.TV',
        traits: [
          'action.devices.traits.TransportControl'
        ],
        name: {
          defaultNames: ['TV'],
          name: 'Game Room TV',
          nicknames: ['TV']
        },
        willReportState: true,
        attributes: {
          "transportControlSupportedCommands": [
            "CAPTION_CONTROL",
            "NEXT",
            "PAUSE",
            "PREVIOUS",
            "RESUME",
            "SEEK_RELATIVE",
            "SEEK_TO_POSITION",
            "SET_REPEAT",
            "SHUFFLE",
            "STOP"
          ]
        },
        deviceInfo: {
          manufacturer: "ACME Inc.",
          model: "TV-R",
          hwVersion: "PVT-2",
          swVersion: "1.0.1"
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-transportcontrol_sync.json")
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");

  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.TV")
            .addTrait("action.devices.traits.TransportControl")
            .setName(
                Collections.singletonList("TV"), "Game Room TV", Collections.singletonList("TV"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "transportControlSupportedCommands",
                        new String[] {
                          "CAPTION_CONTROL",
                          "NEXT",
                          "PAUSE",
                          "PREVIOUS",
                          "RESUME",
                          "SEEK_RELATIVE",
                          "SEEK_TO_POSITION",
                          "SET_REPEAT",
                          "SHUFFLE",
                          "STOP"
                        }))
            .setDeviceInfo("ACME Inc.", "TV-R", "PVT-2", "1.0.1")
            .build()
      });

  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.TV",
        "traits": [
          "action.devices.traits.TransportControl"
        ],
        "name": {
          "defaultNames": [
            "TV"
          ],
          "name": "Game Room TV",
          "nicknames": [
            "TV"
          ]
        },
        "willReportState": true,
        "attributes": {
          "transportControlSupportedCommands": [
            "CAPTION_CONTROL",
            "NEXT",
            "PAUSE",
            "PREVIOUS",
            "RESUME",
            "SEEK_RELATIVE",
            "SEEK_TO_POSITION",
            "SET_REPEAT",
            "SHUFFLE",
            "STOP"
          ]
        },
        "deviceInfo": {
          "manufacturer": "ACME Inc.",
          "model": "TV-R",
          "hwVersion": "PVT-2",
          "swVersion": "1.0.1"
        }
      }
    ]
  }
}
Validator

Device STATES

None.

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.mediaStop

Parameters

Pause media playback.

Parameters
No properties.
Examples

No parameters

action.devices.commands.mediaNext

Parameters

Skip to next media item.

Parameters
No properties.
Examples

No parameters

action.devices.commands.mediaPrevious

Parameters

Skip to previous media item.

Parameters
No properties.
Examples

No parameters

action.devices.commands.mediaPause

Parameters

Pause media playback.

Parameters
No properties.
Examples

No parameters

action.devices.commands.mediaResume

Parameters

Set repeat playback mode.

Parameters Type Description
isOn Boolean

True to turn on repeat mode, false to turn off repeat mode.

isSingle Boolean

(Default: false)

If specified, true means turning on single-item repeat mode, false means turning on normal repeat mode (for example a playlist).

Required:

  • isOn
Examples

Repeat on

{
  "isOn": true
}

Repeat off

{
  "isOn": false
}

Repeat a single track

{
  "isOn": true,
  "isSingle": true
}

action.devices.commands.mediaSeekRelative

Parameters

Seek to a relative position.

Parameters Type Description
relativePositionMs Integer

Milliseconds of the forward (positive int) or backward (negative int) amount to seek.

Required:

  • relativePositionMs
Examples

Seek 10s forward

{
  "relativePositionMs": 10000
}

Seek 10s backward

{
  "relativePositionMs": -10000
}

action.devices.commands.mediaSeekToPosition

Parameters

Seek to an absolute position.

Parameters Type Description
absPositionMs Integer

Millisecond of the absolute position to seek to.

Required:

  • absPositionMs
Examples

Seek to 30s

{
  "absPositionMs": 30000
}

action.devices.commands.mediaRepeatMode

Parameters

Resume media playback.

Parameters
No properties.
Examples

No parameters

action.devices.commands.mediaShuffle

Parameters

Shuffle the current playlist.

Parameters
No properties.
Examples

No parameters

action.devices.commands.mediaClosedCaptioningOn

Parameters

Turn captions on.

Parameters Type Description
closedCaptioningLanguage String

Language or locale for closed captioning.

userQueryLanguage String

Language or locale for user query.

Examples

Turn on closed captioning in English

{
  "closedCaptioningLanguage": "en"
}

Turn on closed captioning in Korean

{
  "closedCaptioningLanguage": "ko-KR"
}

Turn on closed captioning in Korean with user query in American English

{
  "closedCaptioningLanguage": "ko-KR",
  "userQueryLanguage": "en-US"
}

action.devices.commands.mediaClosedCaptioningOff

Parameters

Turn captions off.

Parameters
No properties.
Examples

Turn off closed captioning

Sample EXECUTE Request and Response

Example: Play next song.

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.mediaNext"
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-transportcontrol_execute.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("online", true);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true
        }
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.