Media Playback Settings and Control

You can retrieve information about and control media playback by manipulating objects under the /media/controls, /media/settings/, and /media/playlist/current/items/current resources.

controls Resource

The controls resource contains information about the current playback state.

URI

/api/V1/media/controls

Supported Methods

  • GET: Gets the current playback status.
  • PUT: Sets the current playback status.

Resource Representations

{
    "status": "stop"
}

Property Name Data Type Description
status string Identifies the playback state. Valid values are: unknown, stop, play, and pause.

settings/repeat Resource

The settings/repeat resource contains information about the current repeat mode.

URI

/api/V1/media/settings/repeat

Supported Methods

  • GET: Gets the current repeat mode.

Resource Representations

{
    "value": "single"
}

Property Name Data Type Description
value string Identifies the repeat mode. Valid values are: unknown, off, single, and all.

settings/shuffle Resource

The settings/shuffle resource contains information about the current shuffle mode.

URI

/api/V1/media/settings/shuffle

Supported Methods

  • GET: Gets the current shuffle mode.

Resource Representations

{
    "value": "all"
}

Property Name Data Type Description
value string Identifies the shuffle mode. Valid values are: unknown, off, and all.

settings/mute Resource

The settings/mute resource contains information about the current mute mode.

URI

/api/V1/media/settings/mute

Supported Methods

  • GET: Gets the current mute mode.
  • PUT: Sets the current mute mode.

Resource Representations

{
    "value": "on"
}

Property Name Data Type Description
value string Identifies the mute mode. Valid values are: unknown, off, and on.

settings/volume Resource

The settings/volume resource contains information about the current volume level.

URI

/api/V1/media/settings/volume

Supported Methods

  • GET: Gets the current volume level.
  • PUT: Sets the current volume level.

Resource Representations

{
    "value": 75
}

Property Name Data Type Description
value integer The volume level. Valid values are: unknown (read only), an integer between 0 and 100.

playlist Resources

The playlist sub-resources contain information about the currently playing item.

URI

/api/V1/media/playlist/current/items/current

Supported Methods

  • GET: Gets information about the currently playing item.
  • POST: Sets the currently playing item. Currently only the pseudo-URIs urn:media:item:previous and urn:media:item:next are supported

Resource Representations

{
    "artistName": "Will Atkinson presents Darkboy",
    "uri": "urn:google:play:164364289",
    "titleName": "Darker Shades Of Black (Blazer Radio Edit)",
    "albumName": "DJ Box - July 2012"
}

To navigate to the next item in the playlist, POST the following object:

{
    "uri": "urn:media:item:next"
}

Property Name Data Type Description
albumName string The name of the album.
artistName string The name of the artist.
titleName string The title of the currently playing item.
uri string The URI of the currently playing item.

Text-to-Speech

You can adjust speech settings and request text to be spoken using the /speak, and /speak/sentence resources.

speak Resource

The speak resource controls speech options.

URI

/api/V1/speak

Supported Methods

  • PUT: Sets the current speech options.

Resource Representations

{
    "pitch": 1.0,
    "rate" : 1.5
}

Property Name Data Type Description
pitch float Sets the pitch. A value of 1.0 means the normal pitch. Greater values increase the pitch.
rate float Sets the speech rate. A value of 1.0 means the normal rate. Lower values slow the speed, higher values increase the speed. A value of 0.5 is half the normal speed and 2.0 is twice the speed.

speak/sentence Resource

The sentence resource allows you to request a sentence to be spoken.

URI

/api/V1/speak/sentence

Supported Methods

  • PUT: Sets the sentence to be spoken.

Resource Representations

{
    "text": "Hello world. This is your future robot overlord speaking."
}

Property Name Data Type Description
text string The text to speak.

Errors

  • 503: Text-to-Speech service is not available.

LEDs

You can request animations and set the color values for LEDs using the /led/ sub-resources.

animation Resource

The animation resource controls LED animations.

URI

/api/V1/led/animation

Supported Methods

  • PUT: Sets the current animation.

Resource Representations

To set a built-in animation:

{
    "type": "builtIn",
    "id": 1
}

To set a custom animation:

{
    "type": "custom",
    "fields": [
      { "ledId": 1000, "red": 255, "green": 0, "blue": 0, "start": 250 },
      { "ledId": 1000, "red": 0, "green": 0, "blue": 0, "start": 500 }
    ],
    "repeat": true
}

Property Name Data Type Description
type string Sets the animation type. Valid values are builtIn (note camelCasing) and custom.
id integer The built-in animation ID to start. Valid values are between 0 and 1. This field is only present for builtIn animations.
fields array An array of LED objects for custom animations.

Field Objects

Property Name Data Type Description
ledId integer Sets the LED ID. Valid values are between 0 and 32 for individual LEDs, 1000 for all LEDs, and 1001 for the status (mute) LED.
red integer The red color value for the LED. Valid values are between 0 and 255.
green integer The green color value for the LED. Valid values are between 0 and 255.
blue integer The blue color value for the LED. Valid values are between 0 and 255.
start integer The animation field start time in milliseconds.

leds/all Resource

The leds/all resource allows setting all perimeter LED values in one call.

URI

/api/V1/led/leds/all

Supported Methods

  • PUT: Sets the given color values for all perimeter LEDs.

leds/status Resource

The leds/status resource allows setting the status (mute) LED color.

URI

/api/V1/led/leds/status

Supported Methods

  • PUT: Sets the given color values for the status (mute) LED.

leds/[ledId] Resource

The leds/[ledId] resource allows setting a specific LED color.

URI

/api/V1/led/leds/[index], where [index] is a value between 0 and 32.

Supported Methods

  • PUT: Sets the given color values for the status (mute) LED.

Resource Representations

{
      "red": 255,
      "green": 255, 
      "blue": 0
}

Property Name Data Type Description
red integer The red color value for the LEDs. Valid values are between 0 and 255.
green integer The green color value for the LEDs. Valid values are between 0 and 255.
blue integer The blue color value for the LEDs. Valid values are between 0 and 255.

leds Resource

The leds resource allows you to set a range of LEDs to a set of specific colors.

URI

/api/V1/led/leds

Supported Methods

  • PUT: Sets the given range to the specified color values.

Resource Representations

{
    "start": 0,
    "count": 3,
    "leds": [
      { "red": 255, "green": 0, "blue": 0 },
      { "red": 0, "green": 255, "blue": 0 },
      { "red": 0, "green": 0, "blue": 255 }
    ]
}

Property Name Data Type Description
start integer The start LED ID. A value between 0 and 32.
count integer The number of sequential LEDs to to modify. start plus count must be equal to or less than 32.
leds array An array of color objects for each LED in the range. The array must contain count entries.

Leds Objects

Property Name Data Type Description
red integer The red color value for the LED. Valid values are between 0 and 255.
green integer The green color value for the LED. Valid values are between 0 and 255.
blue integer The blue color value for the LED. Valid values are between 0 and 255.

Errors

  • 503: LED service is not available.

General API Information

This page contains information that applies to all API services.

Cross Origin/Domain Access

The API specifies full access for all domains using the CORS standard for modern browsers and a crossdomain.xml file for Flash and Silverlight. The OPTIONS method will return the appropriate headers required for cross-origin access.

HTTP Method Overrides

The API supports HTTP method overrides for all calls using the X-HTTP-Method-Override header. This is convenient if the client is unable to set a specific method, such as PUT.

Errors

If an API call encounters an error, a JSON object containing information about the error will be returned along with the corresponding HTTP status code indicating the error type.

Error Response Example

{
    "error": {
        "errors": [{
            "message": "Invalid value '4' for field 'count'.",
            "domain": "global",
            "reason": "badRequest"
        }]
    }
}

Error Response Codes

  • 400: There was an error in the request. This is often due to a missing field or malformed JSON data.
  • 404: Specified resource was not found.
  • 405: The specified HTTP method is not allowed for the given resource.
  • 503: The resource is currently unavailable.