The procotol is very similar to mpd’s protocol with minor differences.
This page describes protocol version 0.1.
Welcome
At the beginning of every session the stats module sends the greeting:
OK MPDCRON PROTOCOL_VERSION
where PROTOCOL_VERSION is the version of the protocol in format major_version.minor_version
Requests
If arguments contain spaces, they should be surrounded by double quotation marks. All data between the client and the server is encoded in UTF-8. The command syntax is:
COMMAND [ARG...]
Responses
A command returns OK on completion or ACK some error on failure.
These denote the end of command execution.
ACK Responses
Syntax:
ACK [<int errorid>] {command} description
where:
-
errorid:
An integer indicating which kind of error occured. -
description:
A short explanation of the error. Maybe void.
Error codes
Name | Number | Explanation |
---|---|---|
ACK_ERROR_ARG | 1 | Argument error |
ACK_ERROR_PASSWORD | 2 | The given password was wrong |
ACK_ERROR_PERMISSION | 3 | The client doesn't have permission for the requested command |
ACK_ERROR_UNKNOWN | 4 | Unknown error |
ACK_ERROR_DATABASE_OPEN | 50 | Opening the database failed |
ACK_ERROR_DATABASE_CREATE | 51 | Creating the database failed |
ACK_ERROR_DATABASE_VERSION | 52 | Database version mismatch |
ACK_ERROR_DATABASE_AUTH | 53 | Setting authorizer failed |
ACK_ERROR_DATABASE_INSERT | 54 | Inserting to the database failed |
ACK_ERROR_DATABASE_SELECT | 55 | Selecting from the database failed |
ACK_ERROR_DATABASE_UPDATE | 56 | Updating the database failed |
ACK_ERROR_DATABASE_PREPARE | 57 | Preparing statement failed |
ACK_ERROR_DATABASE_BIND | 58 | Binding values to the statement failed |
ACK_ERROR_DATABASE_STEP | 59 | Stepping the statement failed |
ACK_ERROR_DATABASE_RESET | 60 | Resetting the statement failed |
ACK_ERROR_INVALID_TAG | 101 | The given tag is invalid |
Command Reference
Expression arguments are direct sqlite statements. See http://www.sqlite.org/lang_expr.html for the expression syntax. For the layout of the databases check the sql statements in the beginning of stats-sqlite.c.
Querying the database
- list EXPRESSION
Lists the songs matching the given expression.
Returns:Name Type Value id Integer The database ID of the song file String URI of the song
Example:
alip@harikalardiyari> echo list '"id=83"' | netcat localhost 6601
OK MPDCRON 0.1
id: 83
file: aerosmith/big_ones/11-the_other_side.ogg
OK
- list_album EXPRESSION
Lists the albums matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the album Album String The name of the album Artist String The name of the artist
Example:
alip@harikalardiyari> echo list_album '"id=83"' |netcat localhost 6601
OK MPDCRON 0.1
id: 83
Album: The Silent Enigma
Artist: Anathema
OK
- list_artist EXPRESSION
Lists the artists matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the artist Artist String The name of the artist
Example:
alip@harikalardiyari> echo list_artist '"id=83"' | netcat localhost 6601
OK MPDCRON 0.1
id: 83
Artist: The Beatles
OK
- list_genre EXPRESSION
Lists the genres matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the genre Genre String The name of the genre
Example:
alip@harikalardiyari> echo list_genre '"id=83"' |netcat localhost 6601
OK MPDCRON 0.1
id: 83
Genre: Vocal
OK
- listinfo EXPRESSION
Lists information of the songs matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the song file String The URI of the song Play Count Integer The play count of the song Love Integer The love count of the song Kill Integer The kill count of the song Rating Integer The rating count of the song
Example:
alip@harikalardiyari> echo listinfo '"id=102"' |netcat localhost 6601
OK MPDCRON 0.1
id: 102
file: aerosmith/ultimate_hits/disc_1/15-love_in_an_elevator.ogg
Play Count: 3
Love: 1
Kill: 0
Rating: 10
OK
- listinfo_album EXPRESSION
Lists information of the albums matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the album Album String The name of the album Artist String The name of the artist Play Count Integer The play count of the album Love Integer The love count of the album Kill Integer The kill count of the album Rating Integer The rating count of the album
Example:
alip@harikalardiyari> echo listinfo_album "\"name='Animals'\"" |netcat localhost 6601
OK MPDCRON 0.1
id: 722
Album: Animals
Artist: Pink Floyd
Play Count: 5
Love: 1000
Kill: 0
Rating: 1000
OK
- listinfo_artist EXPRESSION
Lists information of the artists matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the artist Artist String The name of the artist Play Count Integer The play count of the artist Love Integer The love count of the artist Kill Integer The kill count of the artist Rating Integer The rating count of the artist
Example:
alip@harikalardiyari> echo listinfo_artist '"id=102"' |netcat localhost 6601
OK MPDCRON 0.1
id: 102
Artist: Can
Play Count: 10
Love: 5
Kill: 0
Rating: 100
OK
- listinfo_genre EXPRESSION
Lists information of the genres matching the given expression.
Returns:Name Type Explanation id Integer The database ID of the genre Genre String The name of the genre Play Count Integer The play count of the genre Love Integer The love count of the genre Kill Integer The kill count of the genre Rating Integer The rating count of the genre
Example:
alip@harikalardiyari> echo listinfo_genre "\"name like '%Psych%'\"" | netcat localhost 6601
OK MPDCRON 0.1
id: 89
Genre: Psychadelic Trance
Play Count: 0
Love: 0
Kill: 0
Rating: 0
OK
- listtags EXPRESSION
List tags of songs matching the given expression.
Returns:Name Type Explanation id String The database ID of the song file String The URI of the song Tag String A tag of the song
Note: If the song has no tags no Tag is sent!
Example:
alip@harikalardiyari> echo listtags "\"title='The House At Pooneil Corners'\"" |netcat localhost 6601
OK MPDCRON 0.1
id: 4270
file: jefferson_airplane/ignition/cd4/11-the_house_at_pooneil_corners.ogg
Tag: nowar
OK
- listtags_album EXPRESSION
List tags of albums matching the given expression.
Returns:Name Type Explanation id String The database ID of the album Album String The name of the album Artist String The name of the artist Tag String A tag of the album
Note: If the album has no tags no Tag is sent!
Example:
alip@harikalardiyari> echo listtags_album "\"name='Animals'\"" |netcat localhost 6601
OK MPDCRON 0.1
id: 722
Album: Animals
Artist: Pink Floyd
Tag: best
- listtags_artist EXPRESSION
List tags of artists matching the given expression.
Returns:Name Type Explanation id String The database ID of the artist Artist String The name of the artist Tag String A tag of the artist
Note: If the artist has no tags no Tag is sent!
Example:
alip@harikalardiyari> echo listtags_artist "\"name like '%Syd%'\"" |netcat localhost 6601
OK MPDCRON 0.1
id: 421
Artist: Syd Barrett
Tag: crazy
OK
- listtags_genre EXPRESSION
List tags of genres matching the given expression.
Returns:Name Type Explanation id String The database ID of the genre Genre String The name of the genre Tag String A tag of the genre
Note: If the genre has no tags no Tag is sent!
Example:
alip@harikalardiyari> echo listtags_genre "\"name like '%Trance%'\"" |netcat localhost 6601
OK MPDCRON 0.1
id: 88
Genre: Psychedelic Trance
Tag: best
OK
Updating the database
- hate EXPRESSION
Decreases the love count of songs matching the given expression by one.
Returns:Name Type Explanation changes Integer Number of modified entries
Example:
alip@harikalardiyari> echo hate "\"genre='Pop'\"" | netcat localhost 6601
OK MPDCRON 0.1
changes: 58
OK
-
hate_album EXPRESSION
Decreases the love count of albums matching the given expression by one.
Returns: (same as hate) -
hate_artist EXPRESSION
Decreases the love count of artists matching the given expression by one.
Returns: (same as hate) -
hate_genre EXPRESSION
Decreases the love count of genres matching the given expression by one.
Returns: (same as hate) -
love EXPRESSION
Increases the love count of songs matching the given expression by one.
Returns: (same as hate) -
love_album EXPRESSION
Increases the love count of albums matching the given expression by one.
Returns: (same as hate) -
love_artist EXPRESSION
Increases the love count of artists matching the given expression by one.
Returns: (same as hate) -
love_genre EXPRESSION
Increases the love count of genres matching the given expression by one.
Returns: (same as hate) -
kill EXPRESSION
Increases the kill count of songs matching the given expression by one.
Returns: (same as hate) -
kill_album EXPRESSION
Increases the kill count of albums matching the given expression by one.
Returns: (same as hate) -
kill_artist EXPRESSION
Increases the kill count of artists matching the given expression by one.
Returns: (same as hate) -
kill_genre EXPRESSION
Increases the kill count of genres matching the given expression by one.
Returns: (same as hate) -
unkill EXPRESSION
Decreases the kill count of songs matching the given expression to zero.
Returns: (same as hate) -
unkill_album EXPRESSION
Decreases the kill count of albums matching the given expression to zero.
Returns: (same as hate) -
unkill_artist EXPRESSION
Decreases the kill count of artists matching the given expression to zero.
Returns: (same as hate) -
unkill_genre EXPRESSION
Decreases the kill count of genres matching the given expression to zero.
Returns: (same as hate) -
rate EXPRESSION NUMBER
Adds the given number to the rating of songs matching the given expression.
Use a negative number to decrease the rating.
Returns: (same as hate) -
rate_album EXPRESSION NUMBER
Adds the given number to the rating of albums matching the given expression.
Use a negative number to decrease the rating.
Returns: (same as hate) -
rate_artist EXPRESSION NUMBER
Adds the given number to the rating of artists matching the given expression.
Use a negative number to decrease the rating.
Returns: (same as hate) -
rate_genre EXPRESSION NUMBER
Adds the given number to the rating of genres matching the given expression.
Use a negative number to decrease the rating.
Returns: (same as hate) -
addtag EXPRESSION TAG
Adds the given tag to the songs matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
addtag_album EXPRESSION TAG
Adds the given tag to the albums matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
addtag_artist EXPRESSION TAG
Adds the given tag to the artists matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
addtag_genre EXPRESSION TAG
Adds the given tag to the genres matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
rmtag EXPRESSION TAG
Removes the given tag from the songs matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
rmtag_album EXPRESSION TAG
Removes the given tag from the albums matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
rmtag_artist EXPRESSION TAG
Removes the given tag from the artists matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
rmtag_genre EXPRESSION TAG
Removes the given tag from the genres matching the given expression.
A tag may not be empty or have the character ’:’ (colon) in it.
Returns: (same as hate) -
count EXPRESSION NUMBER
Adds the given number to the play count of songs matching the given expression.
Use a negative number to decrease the play count.
Returns: (same as hate) -
count_album EXPRESSION NUMBER
Adds the given number to the play count of albums matching the given expression.
Use a negative number to decrease the play count.
Returns: (same as hate) -
count_artist EXPRESSION NUMBER
Adds the given number to the play count of artists matching the given expression.
Use a negative number to decrease the play count.
Returns: (same as hate) -
count_genre EXPRESSION NUMBER
Adds the given number to the play count of genres matching the given expression.
Use a negative number to decrease the play count.
Returns: (same as hate)