JSON API

json.pl does not care if you use a HTTP GET or POST request, so use what you prefer. It will reply with some JSON or an HTTP error code.

The Player State Object

Many of the responses return the player state. This is a JSON object with the following keys:

• who: the user that you are currently authenticated as or null
• can_skip: true or false, if you are allowed to skip the currently playing song
• player: an object describing the player with the following values
  • volume: the volume of the player, as an integer between 0 and 100
  • song_start: the Unix timestamp that notes when the current song started playing
  • player_id: a string identifying the current player.
  • song_id: the ID of the currently playing song (but see the now_playing field)
  • local_id, remote_id, and other values are mostly private values and are not guaranteed to be useful to you.
• now_playing: the object describing the current song. See below for a description of the object.
• playlist: an array of objects describing each song in the playlist in the order that they will be played. See below for a description of these objects.

Song Objects

A song object has the following fields:

• track: the track number of the song on its album
• album: the name of the album that this song is from
• artist: the artist performing this song
• title: the song’s title
• length: the length of the song, in seconds
• who: an array of strings, each denoting a person who voted for this song
• song_id: the ID of this song
• path: the song’s path on the filesystem.

Modes

Modes that return the player state object

• No mode or an unrecognized mode
• start: starts the player on the player’s host. Returns a 403 error if you are not authenticated.
• stop: stops the player on the player’s host. Returns a 403 error if you are not authenticated.
• skip: skips the current song. Returns a 403 error if you are not allowed to skip the current song.
• volume: accepts a parameter, value, to set the volume of the current player. Returns a 403 error if you are not logged in.
• vote: takes one or more song_id parameters. Returns a 403 error if you are not logged in.
• unvote:
  • if you are not authenticated: returns a 403 error
  • with no song_id parameter or the first song_id = 0: removes all the votes for the current user
  • if you are an admin and a purge parameter is specified: removes all votes owned by the purge parameter
  • with one or more song_id parameters: deletes the votes for the specified songs
• shuffle_votes: no parameters. if you are logged in, randomly reorders your votes.
• vote_to_top: takes a single song_id parameter. the vote matching this parameter is moved above all your other votes.

Modes that return an array of song objects:

These return an array of song objects, formatted as above, except usually lacking a who field.

• random: returns some random songs. The amount is specified by the optional amount parameter, which defaults to 20.
• recent: returns songs that were recently added to the database. The amount is specified by the optional amount parameter, and defaults to 50.
• history: returns songs that were recently played. The amount is specified by the optional amount parameter, defaulting to 25. This also returns a who parameter (array of voter ids) and a time parameter (Unix timestamp of when the song started).
• search: takes two parameters, field and value, and searches the database column field for the value. This is a substring case-insensitive match. The field may be one of: any, artist, album, path, title, song_id.
• select: same as search, but does not perform a substring match.

Other modes

• browse: takes a parameter, field, which should be either ‘album’ or ‘artist’, and returns an array of strings.