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-URIsurn:media:item:previous
andurn: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.