NAME

       simadb_cli - simadb_cli is a command line interface editor for the sima user DB.

SYNOPSIS

       simadb_cli --add_similarity=similarity_string [--check_names] [--dbfile=db_file]
                  [--reciprocal] [--host=mpd_host] [--port=mpd_port]

       simadb_cli --remove_artist=artist [--dbfile=db_file] [--reciprocal]

       simadb_cli --remove_similarity="main artist,similar artist" [--dbfile=db_file]
                  [--reciprocal]

       simadb_cli --purge_hist [--dbfile=db_file]

       simadb_cli --view_artist="artist name" [--dbfile=db_file]

       simadb_cli --view_all [--dbfile=db_file]

       simadb_cli {--bl_curr_trk | --bl_curr_art | --bl_curr_alb | --bl_art=artist_name}
                  [--dbfile=db_file] [--host=mpd_host] [--port=mpd_port]

       simadb_cli --remove_bl=row_id [--dbfile=db_file]

       simadb_cli --view_bl [--dbfile=db_file]

       simadb_cli {{-h | --help} | --version}

DESCRIPTION

       This manual page documents briefly the simadb_cli commands.

       simadb_cli is a command line interface to get and edit users similarities and blacklist
       database used with MPD_sima. The default database file (see the section called “FILES”)
       can be overridden if you want.

       Consider reading the section called “A WORD ABOUT SIMA DATA BASE” to understand the
       structure and relation of similarities within the database.

EXAMPLE

   Similarity edition
       Here follows some simple examples on how to deal with similarity database.

       Pay attention, the following examples set one-way similarities in the DB! Read more about
       it in the section called “A WORD ABOUT SIMA DATA BASE”.

       Adding a similarity between two artists.  In the following example "Pelican" will point to
       "Russian Circles" with a match score of 88% (ie. "Russian Circles" 88% similar to Pelican,
       not reciprocal), it will also check against MPD the presence of both artists in the music
       library.

       simadb_cli --add "Pelican,Russian Circles:80" --check_names

       Similarity string use comma "," as artists separator and semi colon ":" for
       artist/similarity score separator, cf.  the section called “SIMILARITY FORMAT”.

       Adding a similarity between multiple artists.  In the following example "Rage Against The
       Machine" will point to "Tool" and "Audioslave" as similar artists and controls artists
       names are actually in MPD music library.

       simadb_cli --add "Rage Against The Machine,Tool:70,Audiosalve:80" --check_names

       Viewing similarit(y|ies) for an artist.  In the following example we are looking for
       entries for "Rage Against The Machine"

       simadb_cli --view_artist "Rage Against The Machine"

   Black list edition
       Adding to black list.  You can add a single track, an album or an artist to the black
       list. The element to black list is chosen from the currently playing track. Use
       --bl_curr_trk to prevent simadb_cli to queue this track, --bl_curr_alb or --bl_curr_art
       respectively for the album and the artist.

       Remember you need access to your MPD server to retrieve information to black list.
       Defaults are localhost:6600 or found in environment variables but you may set it up from
       command line:

       simadb_cli --bl_curr_art -S mympd.example.org

       To black list a specific artist (not currently playing) you can use --bl_ar="Artist name
       to black list".

OPTIONS

       The program follows the usual GNU command line syntax, with long options starting with two
       dashes ("-"). A summary of options is included below.

       -h, --help
           Print help and exit.

       --version
           Print version and exit.

       -a similarity_string, --add_similarity=similarity_string
           Add similarity to the database.
           For more details about the similarity_string see the section called “SIMILARITY
           FORMAT”.

       -c, --check_names
           Use with --add_similarity in order to check artists names used in similarity_string.
           simadb_cli will control presence of artists names in MPD library. Default is to look
           for MPD server on localhost:6600 or environment variables MPD_HOST and MPD_PORT if
           set.
           You can as well give simadb_cli host/port on the command line using respectively -S
           and -P.

       --bl_art=artist_name
           Use to black list artist_name. simadb_cli is checking artist_name is actually in MPD
           music library (cf -S and -P options to set MPD host/address if necessary).

           If artist_name is not found the script print out a list of matching artists.

       --bl_curr_trk | --bl_curr_art | --bl_curr_alb
           Use to black list the currently playing track|artist|album. You need access to your
           MPD server, use -S and -P to set MPD host/address if necessary.

       -d db_file, --dbfile=db_file
           Use the specific file db_file as database.
           Default is too use XDG_DATA_HOME (see the section called “FILES”).

       --purge_hist
           Purge history, you may supply an alternative DB file with --dbfile option.

       -r, --reciprocal
           Use with an editing options in order to edit reciprocal similarity as well.
           --add_similarity and --remove_{artist|similarity} are supporting reciprocal edition.

           N.B: this option has to appear after the editing option on the command line.

           See the section called “A WORD ABOUT SIMA DATA BASE” for further information about
           reciprocity notion.

       --remove_artist=artist
           Use to remove an artist entry (as main artist) with its associated similarities. To
           remove artist where it appears as a similar artist use the --reciprocal option.

       --remove_bl=row_id
           Use to remove a black list entry. To get the row_id to suppress use --view_bl option.

       --remove_similarity="main artist,similar artist"
           Use to remove a single similarity between a main artist and an associated similarity.
           Give the main artist first, use comma (",") to separate it from similar artist.
           Use of --reciprocal is possible here, see the section called “A WORD ABOUT SIMA DATA
           BASE”.

           This option is useful in case you want to remove only a specific similarity between
           two artists, to remove completely an artist use --remove_artist instead.

       -v "artist name", --view_artist="artist name"
           Get entries for "artist name" in the data base (print to stdout).

       --view_bl
           Get all entries in the black list.

       --view_all
           Get all entries in the data base (print to stdout).

       -P mpd_port, --port=mpd_port
           Use the specific port number mpd_port on MPD server. This overrides MPD_PORT
           environment variable.
           Default is 6600.

       -S mpd_host, --host=mpd_host
           Use the specific host mpd_host as MPD server.
           mpd_host can be an IP or a fully qualified domain name as long as your system can
           resolve it. This overrides MPD_HOST environment variable.
           Default is localhost.

FILES

       ${XDG_DATA_HOME}/mpd_sima/sima.db
           SQLite DB file. Usually XDG_DATA_HOME is set to ${HOME}/.local/share.

SIMILARITY FORMAT

       The similarity_string has to be formatted following a special pattern in order for
       simadb_cli to extract similarity relations between artists names. Usually a similarity
       entry is defined as a main artist, lets say main_art, followed by a list of similar
       artists which you want to be related to that main_art, each artist of that list with a
       specific similarity value, a match score, quantifying the similarity relation with the
       main_art. The match score value is an integer in [0 ,100] with 100 corresponding to a
       perfect match.

       similarity_string is then to be formatted as follow:

       main_art,first artist:<score>,second artist:<score>

       Each artist group are separated with commas (",") and inside each group the artist name
       and the match score is colon (":") separated. Obviously the first artist group, as the
       main artist, does not have a match score.

       Lets see how it works with an example. I consider "Led Zeppelin" to be similar to "Tool"
       with a match score of 25, I also want to have "Audioslave" related to "Led Zeppelin" with
       a score of 20. Then the similarity_string will be the following:

       Led Zeppelin,Tool:25,Audiosalve:20

       See the section called “A WORD ABOUT SIMA DATA BASE” for more details about how
       similarities are handled

A WORD ABOUT SIMA DATA BASE

       The similarity database is defined from the point of view of a main artist which is
       declared related to a list of similar artists. That means when you define main_art to be
       similar to sim_art A and sim_art B the reciprocal won't be true, sim_art A and sim_art B
       are not similar to main_art. At least this is the default behavior when you edit entries
       with simadb_cli, this is also the way last.fm is working concerning similar artists. This
       documentation is using that particular terminology to specify which kind of artist we are
       dealing with : "main artist" or "similar artist".
       The --reciprocal option allows one to add reciprocal relation where sim_art A and sim_art
       B become respectively the main_art. Using --reciprocal you will then edit two more entries
       in the database. To summarize here is what you'll end up with in your data base adding
       similarity with this string main_art,sim_art A:34,sim_art B:45.

       simadb_cli --reciprocal --add_similarity=main_art,sim_art A:34,sim_art B:45

       main_art similar to sim_art A:34 and sim_art B:45
       sim_art A similar to main_art:34
       sim_art B similar to main_art:45

       Without the reciprocal option you would have add only the first similarity. Usually using
       the reciprocal option is the desired behavior, at least what users have in mind when
       thinking of similarity relation between to artists but keep in mind that it may lead to
       have MPD_sima more sensible to loop over the same two artist (ASSERTION TO BE CONFIRMED).

BUGS

       The upstream BTS can be found at http://codingteam.net/project/sima/bugs.

FEEDBACK

       The maintainer would be more than happy to ear from you, don't hesitate to send feedback
       on the forge, via the upstream BTS, the forum or the chat room, all available on the forge
       at http://codingteam.net/project/sima.

       XMPP users are welcome to join the dedicated chat room at sima@conference.codingteam.net.

SEE ALSO

       mpc(1), mpd(1)

       /usr/share/doc/mpd-sima/

AUTHOR

       Jack Kaliko <efrim@azylum.org>
           Wrote this man page and is currently leading MPD_sima project.

COPYRIGHT

       Copyright © 2009-2012 Jack Kaliko

       This manual page was written for the Debian system (and may be used by others).

       Permission is granted to copy, distribute and/or modify this document under the terms of
       the GNU General Public License, Version 3 published by the Free Software Foundation.

       On Debian systems, the complete text of the GNU General Public License can be found in
       /usr/share/common-licenses/GPL.