= deejayd - JSON-RPC Protocol =

Deejayd protocol follows JSON-RPC 1.0 specification available
[http://json-rpc.org/wiki/specification 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 : 0 (not activated) or 1 (activated)
  * playlistplayorder : inorder | random | onemedia | random-weighted
  * webradio : _int_ id of the current webradio list
  * webradiolength : _int_ number of recorded webradio
  * queue : _int_ id of the current queue
  * queuelength : _int_ length of the current queue
  * queuetimelength : _int_ time length of the current queue
  * queueplayorder : 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 : 0 (not activated) or 1 (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 (inorder, onemedia, random or random-weighted)
           * repeat (0 or 1) 

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
  * 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 : 0 or 1 (actually always 1 because it does not need optionnal
               dependencies)
  * queue : 0 or 1 (actually always 1 because it does not need optionnal
               dependencies)
  * webradio : 0 or 1 (needs gst-plugins-gnomevfs to be activated)
  * video : 0 or 1 (needs video dependencies, X display and needs to be
            activated in configuration)
  * dvd : 0 or 1 (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 value 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.add` ====

Add a webradio. 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) : string

Expected return value : ''`['ack']`''



==== `webradio.clear` ====

Remove all recorded webradios.

Arguments :
  * ''This command does not accept any argument.''

Expected return value : ''`['ack']`''



==== `webradio.remove` ====

Remove webradios with id in "ids".

Arguments :
  * {{{ids}}} (Mandatory) : int-list

Expected return value : ''`['ack']`''



==== `webradio.get` ====

Return the content of this mode.

Arguments :
  * {{{first}}} (Optional) : int
  * {{{length}}} (Optional) : int

Expected return value : ''`['mediaList']`''





=== `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']`''