Smart Home MediaState Trait Schema

action.devices.traits.MediaState - This trait is used for devices which are able to report media states.

The MediaState trait is used by the Assistant for these purposes:

  • To know what's playing on each device, whether or not playback was initiated by the Assistant. This information helps the Assistant better understand user intents. For example, users will say "Pause the Tonight Show" when their actual intent is "Pause the device currently playing the Tonight Show'.
  • For portability between media players—if the Assistant knows what's playing and the position of current playback, the Assistant can transfer that playback to another device as a user moves between rooms, or save the playback for later on an arbitrary device.

You can specify what level and aspect of media states your solution provides by configuring the attributes in this trait. This trait is typically used together with the TransportControl traits

Device ATTRIBUTES

Different playback modes may result in different state levels on the same device. For media playback initiated on-device, you may have full details, whereas playback via an auxiliary input only generates PlayingState.

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
supportActivityState Boolean

(Default: false)

Indicate if the device can report the activity state.

supportPlaybackState Boolean

(Default: false)

Indicate if the device can report the current playback state.

Examples

Media device that reports both activity and playback state
{
  "supportActivityState": true,
  "supportPlaybackState": true
}
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.MediaState'
        ],
        name: {
          defaultNames: ['TV'],
          name: 'Family Room TV',
          nicknames: ['TV']
        },
        willReportState: true,
        attributes: {
          supportActivityState: true,
          supportPlaybackState: true
        },
        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-mediastate_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.MediaState")
            .setName(
                Collections.singletonList("TV"),
                "Family Room TV",
                Collections.singletonList("TV"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put("supportActivityState", true)
                    .put("supportPlaybackState", true))
            .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.MediaState"
        ],
        "name": {
          "defaultNames": [
            "TV"
          ],
          "name": "Family Room TV",
          "nicknames": [
            "TV"
          ]
        },
        "willReportState": true,
        "attributes": {
          "supportActivityState": true,
          "supportPlaybackState": true
        },
        "deviceInfo": {
          "manufacturer": "ACME Inc.",
          "model": "TV-R",
          "hwVersion": "PVT-2",
          "swVersion": "1.0.1"
        }
      }
    ]
  }
}
Validator

Device STATES

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

States Type Description
activityState String

Indicate whether the device is active and the user is actively interacting with it.

Supported values:

  • INACTIVE
  • STANDBY
  • ACTIVE
playbackState String

Indicate the current state when playing media.

Supported values:

  • PAUSED
  • PLAYING
  • FAST_FORWARDING
  • REWINDING
  • BUFFERING
  • STOPPED

Examples

Media device that reports both activity and playback state
{
  "activityState": "ACTIVE",
  "playbackState": "PAUSED"
}

Sample QUERY Request and Response

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.js
'use strict';

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

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          online: true,
          activityState: "ACTIVE",
          playbackState: "PAUSED",
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-mediastate_query.json")
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("online", true);
                  put("activityState", "ACTIVE");
                  put("playbackState", "PAUSED");
                  put("status", "SUCCESS");
                }
              });
        }
      });
  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "activityState": "ACTIVE",
        "playbackState": "PAUSED",
        "status": "SUCCESS"
      }
    }
  }
}

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.

None.

Device ERRORS

See the full list of errors and exceptions.