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

If the device can store or report device state information, it should do so using the MediaState trait.

Examples

Device supporting playback commands
{
  "transportControlSupportedCommands": [
    "NEXT",
    "PREVIOUS",
    "PAUSE",
    "STOP",
    "RESUME"
  ]
}

Device COMMANDS

action.devices.commands.mediaClosedCaptioningOn

Turn captions on.

Parameters Type Description
closedCaptioningLanguage String

Language or locale for closed captioning.

userQueryLanguage String

Language or locale for user query.

action.devices.commands.mediaClosedCaptioningOff

Turn captions off.

Parameters
No properties.

action.devices.commands.mediaNext

Skip to next media item.

action.devices.commands.mediaPause

Pause media playback.

action.devices.commands.mediaPrevious

Skip to previous media item.

action.devices.commands.mediaResume

Resume media playback.

action.devices.commands.mediaRepeatMode

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

action.devices.commands.mediaSeekRelative

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

action.devices.commands.mediaSeekToPosition

Seek to an absolute position.

Parameters Type Description
absPositionMs Integer

Millisecond of the absolute position to seek to.

Required:

  • absPositionMs

action.devices.commands.mediaShuffle

Shuffle the current playlist.

action.devices.commands.mediaStop

Pause media playback.

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.