Skip to content

Latest commit

 

History

History
421 lines (284 loc) · 6.94 KB

api.md

File metadata and controls

421 lines (284 loc) · 6.94 KB

spotify-controller API

spotify-controller has both a REST-based API as well as a socket.io API. Both run on Port 8801.

REST API

All requests are HTTP GET.

  • /version:

    Returns the version of spotify-controller currently running.

    {version: 0.1.0}

  • /control_status:

    Returns whether remote control is currently enabled or not in spotify-controller.

    {
	control_status: true
}

  • /state:

    Returns the current playback state and track information.

    {
playbackInfo: {
	album: 'Living Hope',
	albumArtist: 'Phil Wickham',
	artist: 'Phil Wickham',
	discNumber: 1,
	duration: 327000,
	hasArtwork: 1,
	name: 'Living Hope',
	playCount: 0,
	playbackPosition: 0.0430000014603138,
	playerState: 'Paused',
	popularity: 58,
	trackId: 'spotify:track:6nVm313QmsPlNllntTart1',
	trackNumber: 2
},
state: {
	track_id: 'spotify:track:6nVm313QmsPlNllntTart1',
	volume: 63,
	position: 0,
	state: 'paused'
	}

  • /play:

    Starts playback.

    {
	status: 'playing'
}

  • /playTrack/[track]:

    Plays back a specific track. [track] is the Spotify URI.

    {
	status: 'playing-track'
}

  • /playTrackInContext/[track]/[album]:

    Plays the track in the context of an album. [track] is the Spotify URI for the track. [album] is the Album URI.

    {
	status: 'playing-track-in-context'
}

  • /pause:

    Pauses playback.

    {
	status: 'paused'
}

  • /playToggle:

    Toggles playback between play/pause.

    {
	status: 'play-pause-toggled'
}

  • /movePlayerPosition/[seconds]:

    Moves the player position of the currently playing track forward or backward, in seconds.

    {
	status: 'player-position-changed'
}

  • /setPlayerPosition/[seconds]:

    Sets the player position of the currently playing track to the number of seconds specified.

    {
	status: 'player-position-changed'
}

  • /next:

    Goes to next track.

    {
	status: 'next'
}

  • /previous:

    Goes to previous track.

    {
	status: 'previous'
}

  • /volumeUp:

    Turns volume up.

    {
	status: 'volume-up'
}

  • /volumeDown:

    Turns volume down.

    {
	status: 'volume-down'
}

  • /setVolume/[volume]:

    Sets volume level (0-100).

    {
	status: 'setvolume'
}

  • /rampVolume/[volume]/[changePercent]/[rampTime]:

    Ramps volume level (0-100). First argument is the volume level as an integer. Second argument is the percentage to change the volume in each step. Third argument is the total time to take to finish the volume ramp.

    {
	status: 'rampvolume'
}

  • /mute:

    Mutes volume.

    {
	status: 'volume-mute'
}

  • /unmute:

    Mutes volume.

    {
	status: 'volume-unmute'
}

  • /repeatOn:

    Turns on repeating.

    {
	status: 'repeat-on'
}

  • /repeatOff:

    Turns off repeating.

    {
	status: 'repeat-off'
}

  • /repeatToggle:

    Toggles repeating on/off.

    {
	status: 'repeat-toggle'
}

  • /shuffleOn:

    Turns on shuffling.

    {status: shuffle-on'}

  • /shuffleOff:

    Turns off shuffling.

    {status: shuffle-off'}

  • /shuffleToggle:

    Toggles shuffling on/off.

    {
	status: 'shuffle-toggle'
}

Note

It is possible to disable remote control within the context menu of the spotify-controller application. If this is done, you will receive this response when using the REST API:

{
	status: 'not-allowed'
}

Errors may also be sent like this:

{
	error: 'error message'
}

socket.io API

Upon connection, the server will emit the control_status event to let the client know whether or not remote control is available. This will be emitted any time it is changed. It can also be requested by the client at any time by emitting a control_status event. A boolean is returned, with true meaning it is enabled, and false being disabled.

  • version:

    Returns the version of spotify-controller currently running.

    '0.1.0'

  • control_status:

    Returns whether remote control is currently enabled or not in spotify-controller. This will also be emitted on-demand if remote control is disabled at spotify-controller.

    true

  • error:

    Emitted whenever there is an error. Contains the error message as a string.

  • state:

    Returns the current playback state and track information. This is automatically emitted to all connected clients any time there is a playback state change.

    {
playbackInfo: {
	album: 'Living Hope',
	albumArtist: 'Phil Wickham',
	artist: 'Phil Wickham',
	discNumber: 1,
	duration: 327000,
	hasArtwork: 1,
	name: 'Living Hope',
	playCount: 0,
	playbackPosition: 0.0430000014603138,
	playerState: 'Paused',
	popularity: 58,
	trackId: 'spotify:track:6nVm313QmsPlNllntTart1',
	trackNumber: 2
},
state: {
	track_id: 'spotify:track:6nVm313QmsPlNllntTart1',
	volume: 63,
	position: 0,
	state: 'paused'
	}

  • ramping_state:

    Returns the current volume ramping state. True or False. If the volume is currently ramping, you cannot change the volume through volumeUp, volumeDown, or setVolume until the ramp finishes.

  • play:

    Starts playback.

  • playTrack:

    Plays back a specific track. First argument is the Spotify URI as a string.

  • playTrackInContext:

    Plays the track in the context of an album. First argument is the Track Spotify URI. The second argument is the Album URI.

  • pause:

    Pausess playback.

  • playToggle:

    Toggles playback between play/pause.

  • movePlayerPosition:

    Moves the player position of the currently playing track forward or backward based on the first argument, in seconds.

  • setPlayerPosition:

    Sets the player position of the currently playing track to the number of seconds specified in the first argument.

  • next:

    Goes to next track.

  • previous:

    Goes to previous track.

  • volumeUp:

    Turns volume up.

  • volumeDown:

    Turns volume down.

  • setVolume:

    Sets volume level (0-100). First argument is the volume level as an integer.

  • rampVolume:

    Ramps volume level (0-100). First argument is the volume level as an integer. Second argument is the percentage to change the volume in each step. Third argument is the total time to take to finish the volume ramp.

  • mute:

    Mutes volume.

  • unmute:

    Mutes volume.

  • repeatOn:

    Turns on repeating.

  • repeatOff:

    Turns off repeating.

  • repeatToggle:

    Toggles repeating on/off.

  • shuffleOn:

    Turns on shuffling.

  • shuffleOff:

    Turns off shuffling.

  • shuffleToggle:

    Toggles shuffling on/off.