= deejayd - XML Protocol =

All data between the client and server is encoded in UTF-8.

== Commands Format ==

{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <command name="cmdName1">
        <arg name="argName1" type="simple">value</arg>
        <arg name="argName2" type="multiple">
            <value>value1</value>
            <value>value2</value>
        </arg>
    </command>
    <command name="cmdName2">
        <arg name="argName1" type="simple">value</arg>
        <arg name="argName2" type="multiple">
            <value>value1</value>
            <value>value2</value>
        </arg>
    </command>
</deejayd>
ENDXML
}}}

{{{ENDXML}}} is used as command delimiter.

For certain commands, you may need to pass several values as an argument. If
so, you have to set the argument type to {{{multiple}}} instead of {{{single}}}.

== Response Format ==

{{{ENDXML}}} is also used as an answer delimiter.

There are 6 response types :
  * '''`error`''' : Error notification.
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <error name="cmdName">error text</error>
</deejayd>
ENDXML
}}}
  * '''`Ack`''' : Acknowledgement of a command.
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <response name="cmdName" type="Ack" />
</deejayd>
ENDXML
}}}
  * '''`KeyValue`''' : A list of key, value pairs.
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <response name="cmdName" type="KeyValue">
        <parm name="parmName0" value="parmValue0" />
        <parm name="parmName1" value="parmValue1" />
    </response>
</deejayd>
ENDXML
}}}
  * '''`FileAndDirList`''' : A list of files and directories.
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <response directory="optionnal_described_dirname" name="cmdName" type="FileAndDirList">
        <directory name="dirName" />
        <file type="song or video">
            <parm name="parmName0" value="parmValue0" />
            <parm name="parmName1" value="parmValue1" />
        </file>
    </response>
</deejayd>
ENDXML
}}}
  * '''`MediaList`''' : A list of media (song, webradio,playlist or video) with information for each media :
    * artist, album, title, id, etc. if it is a song
    * title, url, id, etc. if it is a webradio
    * title, id, length, subtitle, audio, etc. if it is a video
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <response name="cmdName" type="MediaList">
        <media type="song or video or webradio or playlist">
            <parm name="parmName0" value="parmValue0" />
            <parm name="parmName1" value="parmValue1" />
        </media>
        <media type="song or video or webradio or playlist">
            <parm name="parmName1" value="parmValue1" />
            <listparm name="audio">
                <dictparm>
                    <dictitem name="lang" value="lang1" />
                    <dictitem name="idx" value="0" />
                </dictparm>
                <dictparm>
                    <dictitem name="lang" value="lang2" />
                    <dictitem name="idx" value="1" />
                </dictparm>
            </listparm>
            <listparm name="subtitle">
                <dictparm>
                    <dictitem name="lang" value="lang1" />
                    <dictitem name="idx" value="0" />
                </dictparm>
            </listparm>
        </media>
    </response>
</deejayd>
ENDXML
}}}
  * '''`DvdInfo`''' : Format dvd content.
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <response name="cmdName" type="DvdInfo">
        <dvd longest_track="1" title="DVD Title">
            <track ix="1" length="track length">
                <audio ix="0" lang="lang code" />
                <subtitle ix="0" lang="lang code" />
                <subtitle ix="1" lang="lang code" />
                <chapter ix="1" length="chapter length" />
            </track>
        </dvd>
    </response>
</deejayd>
ENDXML
}}}
Responses may be combined in the same physical message :
{{{
<?xml version="1.0" encoding="utf-8"?>
<deejayd>
    <response name="cmdName" type="Ack" />
    <response name="cmdName" type="MediaList">
        <media type="song or video or webradio or playlist">
            <parm name="parmName0" value="parmValue0" />
            <parm name="parmName1" value="parmValue1" />
        </media>
        <media type="song or video or webradio or playlist">
            <parm name="parmName1" value="parmValue1" />
            <listparm name="audio">
                <dictparm>
                    <dictitem name="lang" value="lang1" />
                    <dictitem name="idx" value="0" />
                </dictparm>
                <dictparm>
                    <dictitem name="lang" value="lang2" />
                    <dictitem name="idx" value="1" />
                </dictparm>
            </listparm>
            <listparm name="subtitle">
                <dictparm>
                    <dictitem name="lang" value="lang1" />
                    <dictitem name="idx" value="0" />
                </dictparm>
            </listparm>
        </media>
    </response>
</deejayd>

}}}

== Available Commands ==

=== `close` ===

Close the connection with the server

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

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

=== `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
  * 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
  * 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
  * dvd : _int_ id of the current dvd
  * random : 0 (not activated) or 1 (activated)
  * repeat : 0 (not activated) or 1 (activated)
  * 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 : ''`KeyValue`''

=== `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 : ''`KeyValue`''

=== `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}}} (Simple and Mandatory) : string

Expected return value : ''`Ack`''

=== `getMode` ===

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 : ''`KeyValue`''

=== `audioUpdate` ===

Update the audio library.
  * audio_updating_db : the id of this task. It appears in the status until the
    update are completed.

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

Expected return value : ''`KeyValue`''

=== `videoUpdate` ===

Update the video library.
  * video_updating_db : the id of this task. It appears in the status until the
    update are completed.

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

Expected return value : ''`KeyValue`''

=== `getdir` ===

List the files of the directory supplied as argument.

Arguments :
  * {{{directory}}} (Simple and Optional) : string

Expected return value : ''`FileAndDirList`''

=== `search` ===

Search files where "type" contains "txt" content.

Arguments :
  * {{{type}}} (Simple and Mandatory) : enum_str
  * {{{txt}}} (Simple and Mandatory) : string

Expected return value : ''`FileAndDirList`''

=== `getvideodir` ===

Lists the files in video dir "directory".

Arguments :
  * {{{directory}}} (Simple and Optional) : string

Expected return value : ''`FileAndDirList`''

=== `playToggle` ===

Toggle play/pause.

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

Expected return value : ''`Ack`''

=== `goto` ===

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

Arguments :
  * {{{id}}} (Simple and Mandatory) : regexp
  * {{{id_type}}} (Simple and Optional) : enum_str
  * {{{source}}} (Simple and Optional) : string

Expected return value : ''`Ack`''

=== `stop` ===

Stop playing.

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

Expected return value : ''`Ack`''

=== `next` ===

Go to next song or webradio.

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

Expected return value : ''`Ack`''

=== `previous` ===

Go to previous song or webradio.

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

Expected return value : ''`Ack`''

=== `setVolume` ===

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

Arguments :
  * {{{volume}}} (Simple and Mandatory) : enum_int

Expected return value : ''`Ack`''

=== `seek` ===

Seeks to the position "time" (in seconds) of the current song (in
    playlist mode).

Arguments :
  * {{{time}}} (Simple and Mandatory) : int

Expected return value : ''`Ack`''

=== `setOption` ===

Set player options "name" to "value", "value" should be 0 or 1.
       Available options are :
       * random
       * qrandom (queue random)
       * repeat
       You can pass several options in the same command

Arguments :
  * {{{option_name}}} (Simple and Mandatory) : enum_str
  * {{{option_value}}} (Simple and Mandatory) : enum_int

Expected return value : ''`Ack`''

=== `current` ===

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

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

Expected return value : ''`MediaList`''

=== `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)

Arguments :
  * {{{option_name}}} (Simple and Mandatory) : string
  * {{{option_value}}} (Simple and Mandatory) : int

Expected return value : ''`Ack`''

=== `playlistInfo` ===

Return the content of the playlist "name". If no name is given, return
    the content of the current playlist.

Arguments :
  * {{{name}}} (Simple and Optional) : string
  * {{{first}}} (Simple and Optional) : int
  * {{{length}}} (Simple and Optional) : int

Expected return value : ''`MediaList`''

=== `playlistList` ===

Return the list of recorded playlists.

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

Expected return value : ''`MediaList`''

=== `playlistAdd` ===

Load files or directories passed as arguments ("path") at the position
    "pos" in the playlist "name". If no playlist name is provided, adds files
    in the current playlist.

Arguments :
  * {{{path}}} (Multiple and Mandatory) : string
  * {{{pos}}} (Simple and Optional) : int
  * {{{name}}} (Simple and Optional) : string

Expected return value : ''`Ack`''

=== `playlistRemove` ===

Remove songs with ids passed as argument ("id"), from the playlist
    "name". If no name are given, remove songs from current playlist.

Arguments :
  * {{{id}}} (Multiple and Mandatory) : int
  * {{{name}}} (Simple and Optional) : string

Expected return value : ''`Ack`''

=== `playlistClear` ===

Clear the current playlist.

Arguments :
  * {{{name}}} (Simple and Optional) : string

Expected return value : ''`Ack`''

=== `playlistMove` ===

Move song with id "id" to position "new_position".

Arguments :
  * {{{ids}}} (Multiple and Mandatory) : int
  * {{{new_pos}}} (Simple and Mandatory) : int

Expected return value : ''`Ack`''

=== `playlistShuffle` ===

Shuffle the current playlist.

Arguments :
  * {{{name}}} (Simple and Optional) : string

Expected return value : ''`Ack`''

=== `playlistErase` ===

Erase playlists passed as arguments.

Arguments :
  * {{{name}}} (Multiple and Mandatory) : string

Expected return value : ''`Ack`''

=== `playlistLoad` ===

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

Arguments :
  * {{{name}}} (Multiple and Mandatory) : string
  * {{{pos}}} (Simple and Optional) : int

Expected return value : ''`Ack`''

=== `playlistSave` ===

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

Arguments :
  * {{{name}}} (Simple and Mandatory) : string

Expected return value : ''`Ack`''

=== `webradioList` ===

Return the list of recorded webradios.

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

Expected return value : ''`MediaList`''

=== `webradioAdd` ===

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 :
  * {{{url}}} (Simple and Mandatory) : string
  * {{{name}}} (Simple and Mandatory) : string

Expected return value : ''`Ack`''

=== `webradioRemove` ===

Remove webradios with id equal to "id".

Arguments :
  * {{{id}}} (Multiple and Mandatory) : int

Expected return value : ''`Ack`''

=== `webradioClear` ===

Remove all recorded webradios.

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

Expected return value : ''`Ack`''

=== `queueInfo` ===

Return the content of the queue.

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

Expected return value : ''`MediaList`''

=== `queueAdd` ===

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

Arguments :
  * {{{path}}} (Multiple and Mandatory) : string
  * {{{pos}}} (Simple and Optional) : int

Expected return value : ''`Ack`''

=== `queueLoadPlaylist` ===

Load playlists passed in arguments ("name") at the position "pos" in
    the queue.

Arguments :
  * {{{name}}} (Multiple and Mandatory) : string
  * {{{pos}}} (Simple and Optional) : int

Expected return value : ''`Ack`''

=== `queueRemove` ===

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

Arguments :
  * {{{id}}} (Multiple and Mandatory) : int

Expected return value : ''`Ack`''

=== `queueClear` ===

Remove all songs from the queue.

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

Expected return value : ''`Ack`''

=== `setvideo` ===

Set the current video directory to "directory".

Arguments :
  * {{{type}}} (Simple and Optional) : enum_str
  * {{{value}}} (Simple and Optional) : str

Expected return value : ''`Ack`''

=== `videoInfo` ===

Set the current video directory to "directory".

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

Expected return value : ''`MediaList`''

=== `dvdLoad` ===

Load the content of the dvd player.

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

Expected return value : ''`Ack`''

=== `dvdInfo` ===

Get the content of the current dvd.

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

Expected return value : ''`DvdInfo`''

=== `setSubscription` ===

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

Arguments :
  * {{{signal}}} (Simple and Mandatory) : enum_str
  * {{{value}}} (Simple and Mandatory) : enum_int

Expected return value : ''`Ack`''

