deejayd - JSON-RPC Protocol

Deejayd protocol follows JSON-RPC 1.0 specification available here. All data between the client and server is encoded in UTF-8.

Commands Format

As written in specification, request is like that : 

`{
    "id": "id",
    "method": "method_name",
    "params": [
        "params1",
        "params2"
    ]
}`

Response Format

As written in specification, response is like that : 

{
    "error": null,
    "id": "id",
    "result": "deejayd_response"
}

For deejayd, result parameter has always the same syntax : 

`{
    "type": answer_type,
    "answer": the real answer value
}`

With response types equals to:

  • ack
  • list
  • dict
  • mediaList
  • dvdInfo
  • fileAndDirList

Specific Objects

Mediafilter Objects

Mediafilter object has been serialized in a specific way to be passed as an method argument or receive with an answer. An example is given here. 

`{
    "id": "and",
    "type": "complex",
    "value": [
        {
            "id": "equals",
            "type": "basic",
            "value": {
                "pattern": "artist_name",
                "tag": "artist"
            }
        },
        {
            "id": "or",
            "type": "complex",
            "value": [
                {
                    "id": "contains",
                    "type": "basic",
                    "value": {
                        "pattern": "Rock",
                        "tag": "genre"
                    }
                },
                {
                    "id": "higher",
                    "type": "basic",
                    "value": {
                        "pattern": "4",
                        "tag": "Rating"
                    }
                }
            ]
        }
    ]
}`

Signal Objects

Signal is available for TCP connection only. Signal object has been serialized in a specific way to be send to client. An example is given here. 

`{
    "answer": {
        "attrs": {
            "attr1": "value1"
        },
        "name": "signal_name"
    },
    "type": "signal"
}`

Common Available Commands

General Commands

status

Return status of deejayd. Given informations are :

  • playlist : _int_ id of the current playlist
  • playlistlength : _int_ length of the current playlist
  • playlisttimelength : _int_ time length of the current playlist
  • playlistrepeat : _bool_ false (not activated) or true (activated)
  • playlistplayorder : inorder | random | onemedia | random-weighted
  • webradio : _int_ id of the current webradio list
  • webradiolength : _int_ number of recorded webradio
  • webradiosource : _str_ current source for webradio streams
  • webradiosourcecat : _str_ current categorie for webradio
  • queue : _int_ id of the current queue
  • queuelength : _int_ length of the current queue
  • queuetimelength : _int_ time length of the current queue
  • queueplayorder : _str_ inorder | random
  • video : _int_ id of the current video list
  • videolength : _int_ length of the current video list
  • videotimelength : _int_ time length of the current video list
  • videorepeat : _bool_ false (not activated) or true (activated)
  • videoplayorder : inorder | random | onemedia | random-weighted
  • dvd : _int_ id of the current dvd
  • dvdlength : _int_ number of tracks on the current dvd
  • volume : [0-100] current volume value
  • state : [play-pause-stop] the current state of the player
  • current : _int_:_int_:_str_ current media pos : current media file id : playing source name
  • time : _int_:_int_ position:length of the current media file
  • mode : [playlist-webradio-video] the current mode
  • audio_updating_db : _int_ show when a audio library update is in progress
  • audio_updating_error : _string_ error message that apppears when the audio library update has failed
  • video_updating_db : _int_ show when a video library update is in progress
  • video_updating_error : _string_ error message that apppears when the video library update has failed

Arguments :

  • This command does not accept any argument.

Expected return value : ['dict']

stats

Return statistical informations :

  • audio_library_update : UNIX time of the last audio library update
  • video_library_update : UNIX time of the last video library update
  • videos : number of videos known by the database
  • songs : number of songs known by the database
  • artists : number of artists in the database
  • albums : number of albums in the database

Arguments :

  • This command does not accept any argument.

Expected return value : ['dict']

setOption

Set player options "name" to "value" for mode "source", Available options are :

  • playorder (_str_: inorder, onemedia, random or random-weighted)
  • repeat (_bool_: True or False)

Arguments :

  • source (Mandatory) : string
  • option_name (Mandatory) : string
  • option_value (Mandatory) : string

Expected return value : ['ack']

ping

Does nothing, just replies with an acknowledgement that the

command was received

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

setRating

Set rating of media file with ids equal to media_id for library 'type'

Arguments :

  • ids (Mandatory) : int-list
  • value (Mandatory) : int
  • type (Optional) : string

Expected return value : ['ack']

setmode

Change the player mode. Possible values are :

  • playlist : to manage and listen songs in playlist
  • panel : to manage and listen songs in panel mode (like itunes)
  • video : to manage and wath video file
  • dvd : to wath dvd
  • webradio : to manage and listen webradios

Arguments :

  • mode (Mandatory) : string

Expected return value : ['ack']

availablemodes

For each available source, shows if it is activated or not.

The answer consists in :

  • playlist : _bool_ true or false
  • panel : _bool_ true or false
  • webradio : _bool_ true or false (media backend has to be abble to read url streams)
  • video : _bool_ true or false (needs video dependencies, X display and needs to be activated in configuration)
  • dvd : _bool_ true or false (media backend has to be able to read dvd)

Arguments :

  • This command does not accept any argument.

Expected return value : ['dict']

Player Commands

player.setPlayerOption

Set player option for the current media. Possible options are :

  • zoom : set zoom (video only), min=-85, max=400
  • audio_lang : select audio channel (video only)
  • sub_lang : select subtitle channel (video only)
  • av_offset : set audio/video offset (video only)
  • sub_offset : set subtitle/video offset (video only)
  • aspect_ratio : set video aspect ratio (video only), available values are :
    • auto
    • 1:1
    • 16:9
    • 4:3
    • 2.11:1 (for DVB)

Arguments :

  • option_name (Mandatory) : string
  • option_value (Mandatory) : string

Expected return value : ['ack']

player.goto

Begin playing at media file with id "id" or toggle play/pause.

Arguments :

  • id (Mandatory) : string
  • id_type (Optional) : string
  • source (Optional) : string

Expected return value : ['ack']

player.stop

Stop playing.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

player.next

Go to next song or webradio.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

player.current

Return informations on the current song, webradio or video info.

Arguments :

  • This command does not accept any argument.

Expected return value : ['mediaList']

player.playToggle

Toggle play/pause.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

player.setVolume

Set volume to "volume". The volume range is 0-100.

Arguments :

  • volume (Mandatory) : int

Expected return value : ['ack']

player.seek

Seeks to the position "pos" (in seconds) of the current media set relative argument to true to set new pos in relative way

Arguments :

  • pos (Mandatory) : int
  • relative (Optional) : bool

Expected return value : ['ack']

player.previous

Go to previous song or webradio.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

Audio Library Commands

audiolib.search

Search files in library where "type" contains "pattern" content.

Arguments :

  • pattern (Mandatory) : string
  • type (Mandatory) : string

Expected return value : ['mediaList']

audiolib.taglist

List all the possible values for a tag according to the optional filter argument.

Arguments :

  • tag (Mandatory) : string
  • filter (Optional) : filter

Expected return value : ['list']

audiolib.update

Update the library.

  • 'type'_updating_db : the id of this task. It appears in the status until the update are completed.

Arguments :

  • force (Optional) : bool

Expected return value : ['dict']

audiolib.getDir

List the files of the directory supplied as argument.

Arguments :

  • directory (Optional) : string

Expected return value : ['fileAndDirList']

Video Library Commands

videolib.search

Search files in library where "type" contains "pattern" content.

Arguments :

  • pattern (Mandatory) : string
  • type (Mandatory) : string

Expected return value : ['mediaList']

videolib.update

Update the library.

  • 'type'_updating_db : the id of this task. It appears in the status until the update are completed.

Arguments :

  • force (Optional) : bool

Expected return value : ['dict']

videolib.getDir

List the files of the directory supplied as argument.

Arguments :

  • directory (Optional) : string

Expected return value : ['fileAndDirList']

Playlist Mode Commands

playlist.move

Move songs with id in "ids" to position "pos".

Arguments :

  • ids (Mandatory) : int-list
  • pos (Mandatory) : int

Expected return value : ['ack']

playlist.addPath

Load files or directories passed as arguments ("paths") at the position "pos" in the current playlist.

Arguments :

  • paths (Mandatory) : list
  • pos (Optional) : int

Expected return value : ['ack']

playlist.shuffle

Shuffle the current playlist.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

playlist.get

Return the content of this mode.

Arguments :

  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

playlist.clear

Clear the current playlist.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

playlist.addIds

Load files with id passed as arguments ("ids") at the position "pos" in the current playlist.

Arguments :

  • ids (Mandatory) : int-list
  • pos (Optional) : int

Expected return value : ['ack']

playlist.remove

Remove songs with ids passed as argument ("ids") from the current playlist

Arguments :

  • ids (Mandatory) : int-list

Expected return value : ['ack']

playlist.loads

Load playlists passed as arguments "name" at the position "pos".

Arguments :

  • pl_ids (Mandatory) : int-list
  • pos (Optional) : int

Expected return value : ['ack']

playlist.save

Save the current playlist to "pls_name" in the database.

  • playlist_id : id of the recorded playlist

Arguments :

  • pls_name (Mandatory) : string

Expected return value : ['dict']

Panel Mode Commands

panel.setSort

Sort active medialist in panel mode

Arguments :

  • sort (Mandatory) : sort

Expected return value : ['ack']

panel.get

Return the content of this mode.

Arguments :

  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

panel.activeList

Return active list in panel mode

  • type : 'playlist' if playlist is choosen as active medialist 'panel' if panel navigation is active
  • value : if 'playlist' is selected, return used playlist id

Arguments :

  • This command does not accept any argument.

Expected return value : ['dict']

panel.tags

Return tag list used in panel mode.

Arguments :

  • This command does not accept any argument.

Expected return value : ['list']

panel.setSearch

Set search filter in panel mode

Arguments :

  • tag (Mandatory) : string
  • value (Mandatory) : string

Expected return value : ['ack']

panel.clearFilter

Clear filters for panel mode

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

panel.setActiveList

Set the active list in panel mode

Arguments :

  • type (Mandatory) : string
  • value (Optional) : string

Expected return value : ['ack']

panel.clearSearch

Clear search filter in panel mode

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

panel.removeFilter

Remove a filter for panel mode

Arguments :

  • tag (Mandatory) : string

Expected return value : ['ack']

panel.clearAll

Clear search filter and panel filters

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

panel.setFilter

Set a filter for panel mode

Arguments :

  • tag (Mandatory) : string
  • values (Mandatory) : list

Expected return value : ['ack']

Video Mode Commands

video.sort

Sort active medialist in video mode

Arguments :

  • sort (Mandatory) : sort

Expected return value : ['ack']

video.set

Set content of video mode

Arguments :

  • value (Mandatory) : string
  • type (Optional) : string

Expected return value : ['ack']

video.get

Return the content of this mode.

Arguments :

  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

Webradio Mode Commands

webradio.getSourceCategories

Return list of categories for webradio source 'source_name'

Arguments :

  • source_name (Mandatory) : string

Expected return value : ['list']

webradio.localAdd

Add a webradio in 'local' source. Its name is "name" and the url of the webradio is "url". You can pass a playlist for "url" argument (.pls and .m3u format are supported).

Arguments :

  • name (Mandatory) : string
  • url (Mandatory) : list

Expected return value : ['ack']

webradio.localRemove

Remove webradios with id in "ids" from the 'local' source.

Arguments :

  • ids (Mandatory) : int-list

Expected return value : ['ack']

webradio.localClear

Remove all recorded webradios from the 'local' source.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

webradio.get

Return the content of this mode.

Arguments :

  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

webradio.setSourceCategorie

Set categorie to 'categorie' for current source

Arguments :

  • categorie (Mandatory) : string

Expected return value : ['ack']

webradio.getAvailableSources

Return list of available sources for webradio mode as source_name: has_categories

Arguments :

  • This command does not accept any argument.

Expected return value : ['dict']

webradio.setSource

Set current source to 'source_name'

Arguments :

  • source_name (Mandatory) : string

Expected return value : ['ack']

Dvd Mode Commands

dvd.reload

Load the content of the dvd player.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

dvd.get

Get the content of the current dvd.

Arguments :

  • This command does not accept any argument.

Expected return value : ['dvdInfo']

Queue Commands

queue.move

Move songs with id in "ids" to position "pos".

Arguments :

  • ids (Mandatory) : int-list
  • pos (Mandatory) : int

Expected return value : ['ack']

queue.addIds

Load files with id passed as arguments ("ids") at the position "pos" in the queue.

Arguments :

  • ids (Mandatory) : int-list
  • pos (Optional) : int

Expected return value : ['ack']

queue.get

Return the content of this mode.

Arguments :

  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

queue.clear

Clear the queue.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

queue.addPath

Load files or directories passed as arguments ("paths") at the position "pos" in the queue.

Arguments :

  • paths (Mandatory) : list
  • pos (Optional) : int

Expected return value : ['ack']

queue.remove

Remove songs with ids passed as argument ("ids") from the queue

Arguments :

  • ids (Mandatory) : int-list

Expected return value : ['ack']

queue.loads

Load playlists passed as arguments "name" at the position "pos"

in the queue.

Arguments :

  • pl_ids (Mandatory) : int-list
  • pos (Optional) : int

Expected return value : ['ack']

Queue Commands

queue.move

Move songs with id in "ids" to position "pos".

Arguments :

  • ids (Mandatory) : int-list
  • pos (Mandatory) : int

Expected return value : ['ack']

queue.addIds

Load files with id passed as arguments ("ids") at the position "pos" in the queue.

Arguments :

  • ids (Mandatory) : int-list
  • pos (Optional) : int

Expected return value : ['ack']

queue.get

Return the content of this mode.

Arguments :

  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

queue.clear

Clear the queue.

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

queue.addPath

Load files or directories passed as arguments ("paths") at the position "pos" in the queue.

Arguments :

  • paths (Mandatory) : list
  • pos (Optional) : int

Expected return value : ['ack']

queue.remove

Remove songs with ids passed as argument ("ids") from the queue

Arguments :

  • ids (Mandatory) : int-list

Expected return value : ['ack']

queue.loads

Load playlists passed as arguments "name" at the position "pos"

in the queue.

Arguments :

  • pl_ids (Mandatory) : int-list
  • pos (Optional) : int

Expected return value : ['ack']

Recorded Playlist Commands

recpls.get

Return the content of a recorded playlist.

Arguments :

  • pl_id (Mandatory) : int
  • first (Optional) : int
  • length (Optional) : int

Expected return value : ['mediaList']

recpls.create

Create recorded playlist. The answer consist on

  • pl_id : id of the created playlist
  • name : name of the created playlist
  • type : type of the created playlist

Arguments :

  • name (Mandatory) : string
  • type (Mandatory) : string

Expected return value : ['dict']

recpls.list

Return the list of recorded playlists.

Arguments :

  • This command does not accept any argument.

Expected return value : ['mediaList']

recpls.staticAdd

Add songs in a recorded static playlist. Argument 'type' has to be 'path' (default) or 'id'

Arguments :

  • pl_id (Mandatory) : int
  • values (Mandatory) : list
  • type (Optional) : string

Expected return value : ['ack']

recpls.magicRemoveFilter

Remove a filter from recorded magic playlist.

Arguments :

  • pl_id (Mandatory) : int
  • filter (Mandatory) : filter

Expected return value : ['ack']

recpls.erase

Erase recorded playlists passed as arguments.

Arguments :

  • pl_ids (Mandatory) : int-list

Expected return value : ['ack']

recpls.magicSetProperty

Set a property for a magic playlist.

Arguments :

  • pl_id (Mandatory) : int
  • key (Mandatory) : string
  • value (Mandatory) : string

Expected return value : ['ack']

recpls.magicGetProperties

Get properties of a magic playlist

  • use-or-filter: if equal to 1, use "Or" filter instead of "And" (0 or 1)
  • use-limit: limit or not number of songs in the playlist (0 or 1)
  • limit-value: number of songs for this playlist (integer)
  • limit-sort-value: when limit is active sort playlist with this tag
  • limit-sort-direction: sort direction for limit (ascending or descending)

Arguments :

  • pl_id (Mandatory) : int

Expected return value : ['dict']

recpls.magicClearFilter

Remove all filter from recorded magic playlist.

Arguments :

  • pl_id (Mandatory) : int

Expected return value : ['ack']

recpls.magicAddFilter

Add a filter in recorded magic playlist.

Arguments :

  • pl_id (Mandatory) : int
  • filter (Mandatory) : filter

Expected return value : ['ack']

Http Specific Commands

General Commands

serverInfo

Return deejayd server informations :

  • server_version : deejayd server version
  • protocol_version : protocol version

Arguments :

  • This command does not accept any argument.

Expected return value : ['dict']

Commands specific to webui

web.buildPanel

Build panel list

Arguments :

  • updated_tag (Optional) : string

Expected return value : ['dict']

web.writecover

Record requested cover in the temp directory

Arguments :

  • mid (Mandatory) : int

Expected return value : ['dict']

web.buildSourceRDF

Build rdf file with current medialist of the specified mode return dict with specific informations (like a description)

Arguments :

  • mode (Mandatory) : string

Expected return value : ['dict']

TCP Specific Commands

General Commands

close

Close the connection with the server

Arguments :

  • This command does not accept any argument.

Expected return value : ['ack']

Signal subscription commands

signal.setSubscription

Set subscribtion to "signal" signal notifications to "value" which should be 0 or 1.

Arguments :

  • signal (Mandatory) : string
  • value (Mandatory) : bool

Expected return value : ['ack']