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)