WebSockets API Reference

Introduction

The most used API transport in Volumio2 is its Websockets API as it allows almost real time communication with multiple clients. Volumio's WebUI gets and sends data (almost) exclusively via WS. Volumio's WS layer is powered by Socket.io.

Scenarios

Websocket communication in Volumio is identifiable in the most basic server/client architecture. The Server is Volumio itself (aka the host where Volumio is running), the client can be one or more WebUIs or other consumers (Apps and so on). In some cases, Volumio hosts can also act as client, to communicate with other hosts on the same network.

Events

Socket.io allows to invoke events triggered by other events, emit and receive communications (on its most basic implementation). As an example, defining which event should be invoked on a client connection looks like:

self.libSocketIO.on('connection', function (connWebSocket) {
  // use connWebSocket here
});

This way, we can define what event should be triggered when a particular message is received:

connWebSocket.on('bringmepizza', function () {
  givehimpizza();
});

Events Documentation

CallMethod on Plugin

Each method of a plugin can be execute through a websocket call. As of now there's no ACL or any security feature but thi s will change in the future. To execute a method the following socket.io command shall be issued:

callMethod

The payload shall be a json with the following structure:

   {
    "endpoint":"category/name",
    "method":"methodName",
    "data": {}
   }

where:

• endpoint is a string used to target the plugin. Its structure is a linux path like string containing the plugin category, a slash and the plugin name. An example: endpoint:'music_service/spop'.
• method is a string containing the name of the method to be executed.
• data is a complex value (can be a string or a Json) and is passed as is to the method.

IMPORTANT: There should be no "-" in this call, due to FE parsing method (it converts / to -). So plugins and functions should not contain "-".

Once the method returns, the result is pushed back to the client with the event 'pushMethod'.

Get Player State CHANGED

GetState

Reply:

{
  "status": "stop",
  "position": 0,
  "dynamictitle": null,
  "samplerate": null,
  "bitdepth": null,
  "channels": null,
  "volume": 100,
  "mute": false,
  "service": null
}

Where

• status is the status of the player
• position is the position in the play queue of current playing track (if any)
• dynamictitle is the title
• samplerate current samplerate
• bitdepth bitdepth
• channels mono or stereo
• volume current Volume
• mute if true, Volumio is muted
• service current playback service (mpd, spop...)

GetSeek

Reply:

{
  "seek": 0,
  "duration": 0,
}

Where seek is the elapsed time (rounded to seconds), and duration is the duration of the current track. If duration is null, then it means that a stream is being played. This object is updated only by the backend once the status changes, from now on the FrontEnd should update the time autonomously.

GetTrackInfo

Reply:

{
  "artist": "artist",
  "title": "title",
  "album": "album",
  "albumart":"http://img2-ak.lst.fm/i/u/174s/2ce29f74a6f54b8791e5fdacc2ba36f5.png"
}

Browse Music Library (TO BE PARTIALLY IMPLEMENTED)

BrowseLibrary objBrowseParameters CHANGED

Where objBrowseParameters are the parameters we want to dig into. This returns the desired level in the music library along with navigation and pagination informations.

{
  navigation: {
    prev: {
      uri: ''
    },
    list: [
      {type: 'song',  title: 'track a', artist: 'artist a', album: 'album', icon: 'music' uri: 'uri'},
      {type: 'folder',  title: 'folder a', icon: 'folder-open-o' uri: 'uri'},
      {type: 'folder',  title: 'folder b', image: '//ip/image' uri: 'uri2'},
      {type: 'playlist',  title: 'playlist', icon: 'bars' uri: 'uri4'}
    ]
  }
}

The browsable items can be;

• Track
• Folder (can also be a category)
• Playlist

Their parameters are:

• Type: track, folder, category
• Title: If this is a song: title, if folder or category is their name.
• Artist and Album: used only if the type is song
• Icon or image: Select the icon to display (naming of Font-Awesome ) , or image (URL served by Volumio Backend or external service)
• Uri: Uri

Get Music Library Available filters

getBrowseFilters CHANGED

This returns available filters (browse by)

{name:'Genres by Name', index: 'index:Genres by Name'},
{name:'Artists by Name', index: 'index:Artists by Name'},
{name:'Albums by Name', index: 'index:Albums by Name'},
{name:'Albums by Artist', index: 'index:Albums by Artist'},
{name:'Tracks by Name', index: 'index:Tracks by Name'}

Get Music Sources (TO BE IMPLEMENTED)

getBrowseSources

This returns a list of available Music Sources

{name:'USB', uri: 'usb'},
{name:'NAS', uri: 'nas'},
{name:'Web Radio', uri: 'web-radio'},
{name:'Spotify', uri: 'spotify'}

Get Current Play Queue

GetQueue CHANGED

Remove Item from queue

volumioRemoveQueueItem N

where N is the track number in the queue, 0 for the first, 9 for the tenth and so on

Add Item to Queue

AddQueueUids uids CHANGED

where uids is the UID of the item we want to add

Set the Volume

volume VolumeInteger

Where VolumeInteger is a numeric (0-100) volume level

To mute/unmute

volume mute
volume unmute

When Volume is already muted, sending another "mute" emit will result in Volume being unmuted

Playlist handling

createplaylist nameplaylist
deleteplaylist nameplaylist 
addtoplaylist uri
removefromplaylist uri
play uri
enqueue uri

Simple Playback Commands CHANGED

• Play: Play
• Pause: Pause
• Stop: Stop
• Previous: Previous
• Next: Next
• Update Spotify Tracklist: spopUpdateTracklist
• Rebuild Volumio Library: RebuildLibrary