Remote Control API

Port used is 7814

API is not stable and subject to change.

API point is /api1/. So for example full URL would be for example http://localhost:7814/api1/play (no trailing slash)

Identifiers used

• Playlist ID: Identifies a unique playlist. (str)
• Track ID: Identifies a unique track database entry. May appear multiple times in a playlist. (int)
• Album ID: Identifies a block within a playlist. Only unique in the context of a single playlist. (int)
• Position: An index position within a playlist. (int)

API

Meta

• version This should increment on breaking changes. Returns json:

{"version": 1}  

Playback control

• play
• pause
• next
• back
• seek/<n> where <n> is an int (time in ms) in range 0 to duration of playing track. [Added in v6.6.0]
• seek1k/<n> where <n> is an int in range 0 to 1000.
• setvolume/<n> where <n> is an int in range 0 to 100.
• setvolumerel/<n> Relative adjustment where <n> is an int in range -100 to 100. [Added in v6.6.0]
• start/<Playlist ID>/<Position> Begins playback in playlist at track index position in playlist.

Toggle modes

• shuffle
• repeat

Playlists

• playlists Returns json:

{"playlists": 
  [ {"name": "Myplaylist",
     "id": "1234",
     "count": 123
    }, ...
  ]
}

• id is a Playlist ID
• count is number of tracks in the playlist

Track at position

• trackposition/<Playlist ID>/<Position>

Returns json of base track data class:

 {"title": "",
  "artist": "",
  "album": "",
  "album_artist": "",
  "duration": 180000, 
  "id": 123,
  "position": 12,
  "album_id": 12,
  "track_number": "5",
  "can_download": true,
  "has_lyrics": false
  }

• id is a Track ID
• duration is in ms
• track_number may be alphanumeric
• can_download is true if you can download using file point

All tracks

• tracklist/<Playlist ID> Returns list of track classes (as above)

{"tracks": 
  [ ...
  ]
}

Albums

• albums/<Playlist ID> Same format as "All tracks", except only the first track of every album block is included.

{"albums": 
  [ ...
  ]
}

Album Tracks

• albumtracks/<Playlist ID>/<Album ID> Same format as "All tracks", Except only the tracks in given album will be returned.

Status

• status

{ "status": "stopped",
  "inc": 12345,
  "shuffle": false,
  "repeat": false,
  "playlist": "123",
  "playlist_length": 123,
  "id": 123,
  "title": "",
  "artist": "",
  "album": "",
  "progress": 120000,
  "auto_stop": false,
  "volume": 50,
  "position": 1,
  "album_id": 123,
  "track": {...}

• status can be stopped, playing or paused.
• id is a Track ID of currently playing track.
• progress is absolute time in ms.
• volume is an int in range 0–100.
• playlist is a Playlist ID.
• playlist_length is a count of tracks in the playing playlist.
• position is index position in the playing playlist.
• inc is an integer that increases when server side playlist or track data is modified. Therefore if this variable changes then you should consider any cached client side data to be invalidated.

Image Thumbnails

• pic/small/<Track ID>
• pic/medium/<Track ID>

Returns image file as JPG. Small is max 75x75. Medium is max 1000x1000. Size and aspect ratio may vary.

Lyrics

• lyrics/<Track ID>

Returns JSON

{"track_id": 1234,
 "lyrics_text": "Song lyrics go here, or empty string if none"
}

Streaming

• file/<Track ID> Return raw audio file. Network tracks not supported. CUE sheets not supported. You can check the can_download track property.
• playinghit/<Track ID> Causes play time to increment. Hit continuously while playing. Period must be less than 5 seconds. A period of 3 seconds is suggested.