Player Service API

Overview ¶

Goals

Player Service API for global player is designed to provide a way for PlayNetwork applications to query state and control global player. The purpose of the api is to enable maximum control (allowed by player) through web interface easily.

Lookup any player state variable
Set any player variable that can be set
Generate any event that can be handled by player

API Hosts

Production server: http://gpcontrol.apps.playnetwork.com
Staging server: http://test-gpcontrol.apps.playnetwork.com

Message Format

All messages are formated as JSON.

Common Status Codes

200 - OK
401 - Not Authorized: invalid apikey
400 - Bad Request: invalid player, varname, event, etc.

Misc

API Blueprint: https://github.com/apiaryio/api-blueprint
aglio: https://github.com/danielgtaylor/aglio

Docs & Version ¶

Docs ¶

Retrieve this document.

Get Docs
GET`/v1/docs`

Example URI

GET /v1/docs

Response 200

HideShow

Headers

Content-Type: text/html

Body

this document.

Version ¶

Retrieve the latest supported API version. This request is primarily informative for the developer to ensure the appropriate resources are being accessed.

Get Version
GET`/v1/version`

Example URI

GET /v1/version

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    name    : "player-svc",
    version : "1.1.0"
}

Variables & Events ¶

NOTE: The server passes the variable names and events through without verification.

Supported variable names ¶

Supported variable names
GET`/v1/supported varnames`

Example URI

GET /v1/supported varnames

Request

HideShow

Body

"ACTIVE ZONES"
"ALLOW"
"AndroidExternalPath"
"ConceptName"
"ContentServer"
"ContentServerProtocol"
"ContentServerSharedSecret"
"ContentServerUrlExpirationDays"
"CurrentArtist"
"CurrentPlaylistDateRange"
"CurrentPlaylistId"
"CurrentPlaylistName"
"CurrentProgramName"
"CurrentSongTitle"
"CurrentTrackId"
"DeviceApiLogger_BaseName"
"DeviceApiLogger_LogLevel"
"DeviceApiLogger_MessageTimestampFormat"
"DeviceApiLogger_PublishEndpointTimeout"
"DeviceApiLogger_PublishEndpointUrl"
"DeviceApiLogger_PublishIntervalInMs"
"DeviceID"
"EquipmentDevice"
"EquipmentFirmware"
"EquipmentHardware"
"EquipmentType"
"FailedDownloads"
"FileLogger_BaseName"
"FileLogger_LoggerDir"
"FileLogger_Retention"
"FutureTracks"
"HardwareManufacturer"
"HardwareModel"
"HttpCopyFilter"
"HttpUseSudo"
"LUKSDevicePath"
"LUKSMountPath"
"LoaderState"
"Logger_AllowedLevels"
"Logger_CleanupInterval"
"MPlayerOptions"
"MPlayerPath"
"MPlayerWorkDir"
"Mac_address"
"NETWORK DOWNLOAD DAY OF WEEK"
"NETWORK DOWNLOAD WINDOW END"
"NETWORK DOWNLOAD WINDOW START"
"NPMaxUpcomming"
"NPUrl"
"NPUrlBase"
"OperatingSystem"
"OperatingSystemVersion"
"PlayerCommand"
"PlayerDataVariables"
"Playlists"
"PlaylistsExtended"
"ProxyAuthPassword"
"ProxyAuthScheme"
"ProxyAuthUsername"
"ProxyHost"
"ProxyPort"
"RemainingDownloads"
"RequestedDns1"
"RequestedDns2"
"RequestedGateway"
"RequestedIpAddress"
"RequestedNetMask"
"RequestedNetworkMode"
"SFileLastContentUpdateTimeStamp"
"SFileLastDeviceUpdateTimeStamp"
"SFileLastSoftwareUpdateTimeStamp"
"SFileLocalPath"
"SFileProcessTracks"
"SFileUpdateInterval"
"SFileUpdateStartupDelay"
"ScheduleServer"
"ScheduleServerProtocol"
"ScheduleServerSharedSecret"
"ScheduleServerUrlExpirationDays"
"ScheduleServerUser"
"ServerTimeFormat"
"SettingsDatabase"
"SoftwareType"
"StorageFreeSpace"
"Time"
"TimeDrift"
"TimeFormat"
"TimeZone"
"TrackExtension"
"TrackHistory"
"TrackQueueMinutes"
"TrackQueueThreshold"
"UseProxy"
"UseProxyAuth"
"Version"
"Version"
"Volume"
"Volume"
"WebCommandUrl"
"androidEncryptedPath"
"decryptionBufferLookAheadMins"
"encfsDataFile"
"encfsDataFile"
"encfsEncryptedPath"
"encfsMountPath"
"luksDataFile"
"luksName"
"quoteHttp"
"unencryptedMountPath"
"MediaAssetStatistic" # returns json for values {"count":{"missing": 0,"total": 11,"available": 11}}

Zone specific variable names ¶

Zone specific variable names
GET`/v1/zone specific varnames`

Example URI

GET /v1/zone specific varnames

Request

HideShow

Body

"CurrentSongTitle"
"CurrentTrackId"
"CurrentArtist"
"CurrentPlaylistName"
"CurrentPlaylistId"
"CurrentPlaylistDateRange"
"CurrentProgramName"
"CurrentState"
"Volume"

Supported Event IDs ¶

Supported event ids
GET`/v1/supported event ids`

Example URI

GET /v1/supported event ids

Request

HideShow

Body

10 : PAUSE
    { "zoneId" : 1|2 }

11 : SKIP
    { "zoneId" : 1|2 }

12 : SET_PLAYLIST
    {
        "playlistId" : playlistId ,
        "zoneId"     : 1|2
    }

13 : ADVANCE_PROGRAM
    { "zoneId" : 1|2 }

14 : SET_VOLUME
    {
        "volume" : 65 , // valid values: 0 ... 100
        "zoneId" : 1|2
    }

15 : PLAY_TRACK_NOW
    {
        "trackId" : trackId ,
        "zoneId"  : 1|2
    }

16 : GET_PLAYLIST
    {
        "playlistId" : playlistId ,
        "zoneId"     : 1|2
    }

17 : ADD_TRACKS
    //this event put the list of the track on top of the track queue to play
    {
        "trackIds" : [ id1, id2, id3, etc ] ,
        "zoneId"   : 1|2
    }

18 : SET_NETWORK
    {
        "addressType"       : "static"        ,
        "address"           : "192.168.1.2"   ,
        "netmask"           : "255.255.252.0" ,
        "gateway"           : "192.168.1.1"   ,
        "dns1"              : "10.129.4.2"    ,
        "dns2"              : "8.8.8.8"       , // optional
        "useProxy"          : true|false      ,
        "proxyHost"         : "192.168.1.3"   , // optional
        "proxyPort"         : "8080"          , // optional
        "useProxyAuth"      : true|false      ,
        "proxyAuthScheme"   : "Basic"         , // optional
        "proxyAuthUsername" : "userid"        , // optional
        "proxyAuthPassword" : "password"        // optional
    }

19 : LOAD
    { "loaderState": 0|1|2 }

100 : STOP_PLAYER
101 : RESTART_PLAYER
102 : REBOOT_PLAYER

110 : TEST_EVENT_110
120 : TEST_EVENT_120

GP Routes ¶

Currently being used by Device Provisioning - superseded by /v1/devices

Get Variable ¶

Retrieve player’s variable.

Get Variable
GET`/v1/gp/{macaddr}/variable {?apikey}{?varname}{?zoneId}`

Example URI

GET /v1/gp/00:00:00:aa:11:bc/variable ?apikey=?varname=DeviceID?zoneId=1

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
apikey: string (required)
your playnetwork apikey
varname: string (required) Example: DeviceID
the player’s variable to retrieve
zoneId: number (optional) Example: 1
Zone for playback on the Curio Player X5; default will be 1

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'DeviceID',
    values    : [ '189120' ],
    messageId : '2d347563-be87-4800-bd03-924d6d766451',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Set Variable ¶

Set player variable (only config variable at this point)

Set Variable
PUT`/v1/gp/{macaddr}/variable {?apikey}{?varname}`

Example URI

PUT /v1/gp/00:00:00:aa:11:bc/variable ?apikey=?varname=WebCommandUrl

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
apikey: string (required)
your playnetwork apikey
varname: string (required) Example: WebCommandUrl
the player’s variable to set

Request

HideShow

Headers

Content-Type: application/json

Body

{
    configVarVal : "http://gpcontrol.apps.playnetwork.com",
    zoneId       : 1|2   // optional
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'WebCommandUrl',
    values    : [ 'http://gpcontrol.apps.playnetwork.com' ],
    messageId : '09f89b86-5dd9-47de-a856-b1c50757a689',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Gen Event ¶

Request the player to perform an action

Gen Event
PUT`/v1/gp/{macaddr}/event {?apikey}{?eventid}`

Example URI

PUT /v1/gp/00:00:00:aa:11:bc/event ?apikey=?eventid=11

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
apikey: string (required)
your playnetwork apikey
eventid: number (required) Example: 11
the player’s event/action to perform

Request

HideShow

Headers

Content-Type: application/json

Body

{
    zoneId : 1|2   // optional
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'GenEvent',
    message   : 'OK',
    result    : 'Success',
    messageId : 'fe44220b-dc36-4e87-9d64-421dc5f5cf0e',
    eventId   : '11',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Device Routes ¶

Devices ¶

Retrieve a list of device IDs of players currently connected on the server

Get Devices
GET`/v1/devices {?apikey}{?skip}{?count}`

Example URI

GET /v1/devices ?apikey=?skip=?count=

URI Parameters

HideShow

apikey: string (required)
your playnetwork apikey
skip: int (optional)
the # of IDs to be dropped from front of the list
count: int (optional)
the # of IDs to be returned from the list

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    '00:11:22:33:44:55',
    '00:11:22:33:44:56',
    '00:11:22:33:44:57'
]

Count ¶

Retrieve the number of players currently connected on the server

Get Count
GET`/v1/devices/count {?apikey}`

Example URI

GET /v1/devices/count ?apikey=

URI Parameters

HideShow

apikey: string (required)
your playnetwork apikey

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    count : 42
}

Vars ¶

Retrieve player’s variable. Additional key/val (optional) in request.query will be included.

Get Var
GET`/v1/devices/{macaddr}/vars/{varname} {?apikey}`

Example URI

GET /v1/devices/00:00:00:aa:11:bc/vars/DeviceID ?apikey=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
varname: string (required) Example: DeviceID
the player’s variable to retrieve
apikey: string (required)
your playnetwork apikey
key1: string (optional)
key1/val1 will be included in parameters
key2: string (optional)
key2/val2 will be included in parameters

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'DeviceID',
    values    : [ '189120' ],
    messageId : '2d347563-be87-4800-bd03-924d6d766451',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Zone Specific Vars ¶

Retrieve player’s zone specific variable

Get zone specific var
GET`/v1/devices/{macaddr}/zones/{zoneId}/vars/{varname} {?apikey}`

Example URI

GET /v1/devices/00:00:00:aa:11:bc/zones/1/vars/CurrentSongTitle ?apikey=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
zoneId: number (required) Example: 1
Zone for playback on the Curio Player X5; default will be 1
varname: string (required) Example: CurrentSongTitle
the player’s variable to retrieve
apikey: string (required)
your playnetwork apikey

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'CurrentSongTitle',
    values    : [ 'You Are My Starship ' ],
    messageId : '815ef907-f486-400c-a6a8-533bbdb44b28',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Zone Specific NowPlaying ¶

Retrieve track info that is currently playing for a specific zone

Get zone specific nowplaying
GET`/v1/devices/{macaddr}/zones/{zoneId}/nowplaying {?apikey}`

Example URI

GET /v1/devices/00:00:00:aa:11:bc/zones/1/nowplaying ?apikey=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
zoneId: number (required) Example: 1
Zone for playback on the Curio Player X5; default will be 1
apikey: string (required)
your playnetwork apikey

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    trackToken : '665830',
    title      : 'Bubbly',
    artist     : 'Paul McCartney'
}

Playlists ¶

Retrieve player’s specific Playlist

Get Playlist
GET`/v1/devices/{macaddr}/vars/Playlists/{token} {?apikey}`

Example URI

GET /v1/devices/00:00:00:aa:11:bc/vars/Playlists/2131744 ?apikey=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
token: string (required) Example: 2131744
playlist token
apikey: string (required)
your playnetwork apikey

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'Playlist',
    values    : [ { playPrograms: [Object],
                    title: 'Adults ',
                    start: '2014-07-05T00:00:00',
                    token: 2131744,
                    end: '2020-05-01T23:59:59' } ],
    messageId : '2d347563-be87-4800-bd03-924d6d766451',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Programs ¶

Retrieve player’s specific Program

Get Programs
GET`/v1/devices/{macaddr}/vars/Programs/{token} {?apikey}`

Example URI

GET /v1/devices/00:00:00:aa:11:bc/vars/Programs/1030861 ?apikey=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
token: string (required) Example: 1030861
program token
apikey: string (required)
your playnetwork apikey

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'Program',
    values    : [ { token: 1030861,
                    title: 'Urban Adult',
                    tracks: [Object] } ],
    messageId : '2d347563-be87-4800-bd03-924d6d766451',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

PlayPrograms ¶

Retrieve player’s specific PlayProgram.

Get PlayPrograms
GET`/v1/devices/{macaddr}/vars/playprograms/{token} {?apikey}{?playlistId}{?channelId}`

Example URI

GET /v1/devices/00:00:00:aa:11:bc/vars/playprograms/1030861 ?apikey=?playlistId=2131744?channelId=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
token: string (required) Example: 1030861
PlayProgram token
apikey: string (required)
your playnetwork apikey
playlistId: string (optional) Example: 2131744
playlist token
channelId: string (optional)
channel token

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'UpdateVarVals',
    result    : 'Success',
    varname   : 'PlayProgram',
    values    : [ { groupType: 'RotationAndSelect',
                    tracks: [Object],
                    start: '1900-02-01T00:00:00',
                    token: 1030861,
                    end: '1900-02-01T00:00:00' } ],
    messageId : '2d347563-be87-4800-bd03-924d6d766451',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Events ¶

Request the player to perform an action

Gen Event
PUT`/v1/devices/{macaddr}/events/{eventId} {?apikey}`

Example URI

PUT /v1/devices/00:00:00:aa:11:bc/events/11 ?apikey=

URI Parameters

HideShow

macaddr: string (required) Example: 00:00:00:aa:11:bc
MAC Address of a specific Curio Player X5 device
eventId: number (required) Example: 11
the player’s event/action to perform
apikey: string (required)
your playnetwork apikey

Request

HideShow

Headers

Content-Type: application/json

Body

{
    zoneId : 1|2   // optional
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    command   : 'GenEvent',
    message   : 'OK',
    result    : 'Success',
    messageId : 'fe44220b-dc36-4e87-9d64-421dc5f5cf0e',
    eventId   : '11',
    zoneId    : 1,
    mac       : '10:00:00:21:e4:bd'
}

Overview ¶

Goals ¶

API Hosts ¶

Message Format ¶

Common Status Codes ¶

Misc ¶

Docs & Version ¶

Docs ¶

Get DocsGET/v1/docs

Example URI

Headers

Body

Version ¶

Get VersionGET/v1/version

Example URI

Headers

Body

Variables & Events ¶

Supported variable names ¶

Supported variable namesGET/v1/supported varnames

Example URI

Body

Zone specific variable names ¶

Zone specific variable namesGET/v1/zone specific varnames

Example URI

Body

Supported Event IDs ¶

Supported event idsGET/v1/supported event ids

Example URI

Body

GP Routes ¶

Get Variable ¶

Get VariableGET/v1/gp/{macaddr}/variable {?apikey}{?varname}{?zoneId}

Example URI

Headers

Body

Set Variable ¶

Set VariablePUT/v1/gp/{macaddr}/variable {?apikey}{?varname}

Example URI

Headers

Body

Headers

Body

Gen Event ¶

Gen EventPUT/v1/gp/{macaddr}/event {?apikey}{?eventid}

Example URI

Headers

Body

Headers

Body

Device Routes ¶

Devices ¶

Get DevicesGET/v1/devices {?apikey}{?skip}{?count}

Example URI

Headers

Body

Count ¶

Get CountGET/v1/devices/count {?apikey}

Example URI

Headers

Body

Vars ¶

Get VarGET/v1/devices/{macaddr}/vars/{varname} {?apikey}

Example URI

Headers

Body

Zone Specific Vars ¶

Get zone specific varGET/v1/devices/{macaddr}/zones/{zoneId}/vars/{varname} {?apikey}

Example URI

Headers

Body

Zone Specific NowPlaying ¶

Get zone specific nowplayingGET/v1/devices/{macaddr}/zones/{zoneId}/nowplaying {?apikey}

Example URI

Headers

Body

Playlists ¶

Get PlaylistGET/v1/devices/{macaddr}/vars/Playlists/{token} {?apikey}

Example URI

Headers

Goals

API Hosts

Message Format

Common Status Codes

Misc

Get Docs
GET`/v1/docs`

Get Version
GET`/v1/version`

Supported variable names
GET`/v1/supported varnames`

Zone specific variable names
GET`/v1/zone specific varnames`

Supported event ids
GET`/v1/supported event ids`

Get Variable
GET`/v1/gp/{macaddr}/variable {?apikey}{?varname}{?zoneId}`

Set Variable
PUT`/v1/gp/{macaddr}/variable {?apikey}{?varname}`

Gen Event
PUT`/v1/gp/{macaddr}/event {?apikey}{?eventid}`

Get Devices
GET`/v1/devices {?apikey}{?skip}{?count}`

Get Count
GET`/v1/devices/count {?apikey}`

Get Var
GET`/v1/devices/{macaddr}/vars/{varname} {?apikey}`

Get zone specific var
GET`/v1/devices/{macaddr}/zones/{zoneId}/vars/{varname} {?apikey}`

Get zone specific nowplaying
GET`/v1/devices/{macaddr}/zones/{zoneId}/nowplaying {?apikey}`

Get Playlist
GET`/v1/devices/{macaddr}/vars/Playlists/{token} {?apikey}`

Get Programs
GET`/v1/devices/{macaddr}/vars/Programs/{token} {?apikey}`

Get PlayPrograms
GET`/v1/devices/{macaddr}/vars/playprograms/{token} {?apikey}{?playlistId}{?channelId}`

Gen Event
PUT`/v1/devices/{macaddr}/events/{eventId} {?apikey}`