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 the action.devices.traits.TransportControl trait may report the following attributes as part of SYNC:

Attributes Type Description
transportControlSupportedCommands Array <String>

Required.

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

Properties:

Supported values:

  • CAPTION_CONTROL
  • NEXT
  • PAUSE
  • PREVIOUS
  • RESUME
  • SEEK_RELATIVE
  • SEEK_TO_POSITION
  • SET_REPEAT
  • SHUFFLE
  • STOP

Examples

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

Sample SYNC Request and Response

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.

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.

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

Required.

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).

action.devices.commands.mediaSeekRelative

Seek to a relative position.

Parameters Type Description
relativePositionMs Integer

Required.

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

action.devices.commands.mediaSeekToPosition

Seek to an absolute position.

Parameters Type Description
absPositionMs Integer

Required.

Millisecond of the absolute position to seek to.

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.