<!ENTITY dhemail "kaliko@azylum.org">
<!ENTITY dhusername "&dhfirstname; &dhsurname;">
<!ENTITY dhpackage "mpd-sima">
- <!ENTITY release "0.13.0">
+ <!ENTITY release "0.13.1">
<!-- TITLE should be something like "User commands" or similar (see
http://www.tldp.org/HOWTO/Man-Page/q2.html). -->
<!ENTITY dhtitle "&dhpackage; &release; User Manual">
<year>2012</year>
<year>2013</year>
<year>2014</year>
+ <year>2015</year>
<holder>&dhusername;</holder>
</copyright>
<legalnotice>
.\" Title: mpd-sima
.\" Author: Jack Kaliko <kaliko@azylum.org>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 12/08/2014
-.\" Manual: mpd-sima 0.13.0 User Manual
+.\" Date: 01/28/2015
+.\" Manual: mpd-sima 0.13.1 User Manual
.\" Source: mpd-sima
.\" Language: English
.\"
-.TH "MPD\-SIMA" "1" "12/08/2014" "mpd-sima" "mpd-sima 0.13.0 User Manual"
+.TH "MPD\-SIMA" "1" "01/28/2015" "mpd-sima" "mpd-sima 0.13.1 User Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.HP \w'\fBmpd\-sima\fR\ 'u
\fBmpd\-sima\fR [\fB\-\-daemon\fR] [\fB\-\-config=\fR\fIconf_file\fR] [\fB\-\-var_dir=\fR\fIvar_directory\fR] [\fB\-\-pid=\fR\fIpid_file\fR] [\fB\-\-log=\fR\fIlog_file\fR] [\fB\-\-log\-level=\fR\fIlog_level\fR] [\fB\-\-host=\fR\fImpd_host\fR] [\fB\-\-mpd_port=\fR\fImpd_port\fR]
.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR [\fB\-\-var_dir=\fR\fIvar_directory\fR] [\fB\-\-create\-db>\fR]
+\fBmpd\-sima\fR [\fB\-\-var_dir=\fR\fIvar_directory\fR] [\fB\-\-create\-db\fR]
.HP \w'\fBmpd\-sima\fR\ 'u
\fBmpd\-sima\fR [{\fB\-h\fR\ |\ \fB\-\-help\fR} | \fB\-\-version\fR]
.SH "DESCRIPTION"
.RS 4
Default is to look for MPD server at localhost:6600 (or MPD_HOST/MPD_PORT env\&. var\&. if set)\&.
.sp
-The default behavior is to add one track, this track is to be chosen among titles from artists similar to the artist of the currently played track\&. MPD_sima will add one track when the unplayed queue is one track long\&.
+The default behavior is to add one track, this track is to be chosen among titles from artists similar to the last artist in the queue\&. MPD_sima will add one track when the unplayed queue is one track long\&.
.sp
To change these defaults, use the configuration file
mpd_sima\&.cfg
.RE
.SH "COPYRIGHT"
.br
-Copyright \(co 2009-2014 Jack Kaliko
+Copyright \(co 2009-2015 Jack Kaliko
.br
.PP
This manual page was written for the Debian system (and may be used by others)\&.
<cmdsynopsis>
<command>&dhpackage;</command>
<arg choice="opt"><option>--var_dir=</option><replaceable class="option">var_directory</replaceable></arg>
- <arg choice="opt"><option>--create-db></option></arg>
+ <arg choice="opt"><option>--create-db</option></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>&dhpackage;</command>
<term>DEFAULTS</term>
<listitem>
<para>Default is to look for MPD server at localhost:6600 (or MPD_HOST/MPD_PORT env. var. if set).</para>
- <para>The default behavior is to add one track,
- this track is to be chosen among titles from
- artists similar to the artist of the currently
- played track. MPD_sima will add one track when the
- unplayed queue is one track long.</para>
+ <para>The default behavior is to add one track, this
+ track is to be chosen among titles from artists
+ similar to the last artist in the queue. MPD_sima
+ will add one track when the unplayed queue is one
+ track long.</para>
<para>To change these defaults, use the configuration file <filename>mpd_sima.cfg</filename></para>
</listitem>
</varlistentry>
.\" Title: mpd_sima.cfg
.\" Author: Jack Kaliko <kaliko@azylum.org>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 12/09/2014
-.\" Manual: mpd-sima 0.13.0 User Manual
+.\" Date: 01/28/2015
+.\" Manual: mpd-sima 0.13.1 User Manual
.\" Source: mpd-sima
.\" Language: English
.\"
-.TH "MPD_SIMA\&.CFG" "5" "12/09/2014" "mpd-sima" "mpd-sima 0.13.0 User Manual"
+.TH "MPD_SIMA\&.CFG" "5" "01/28/2015" "mpd-sima" "mpd-sima 0.13.1 User Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
\m[blue]\fB\%https://picard.musicbrainz.org/\fR\m[]\&.
.RE
.PP
-\fBuser_db=\fR\fIfalse\fR
-.RS 4
-Temporarily removed feature
-.RE
-.PP
mpd\-sima\*(Aqs plugin management for internal source plugin and contrib (ie\&. external plugins)\&.
.br
.RE
.SH "COPYRIGHT"
.br
-Copyright \(co 2009-2014 Jack Kaliko
+Copyright \(co 2009-2015 Jack Kaliko
.br
.PP
This manual page was written for the Debian system (and may be used by others)\&.
</para>
</listitem>
</varlistentry>
- <varlistentry> <!-- sima.user_db -->
- <term><option>user_db=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Temporarily removed feature</para>
- <!--<para>Look for user defined similarities in user data base.</para>-->
- </listitem>
- </varlistentry>
</variablelist>
<para>&dhpackage;'s plugin management for internal source plugin
and contrib (ie. external plugins).<sbr /> Plugins list is a
.\" Title: simadb_cli
.\" Author: Jack Kaliko <kaliko@azylum.org>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 12/08/2014
-.\" Manual: mpd-sima 0.13.0 User Manual
+.\" Date: 01/28/2015
+.\" Manual: mpd-sima 0.13.1 User Manual
.\" Source: mpd-sima
.\" Language: English
.\"
-.TH "SIMADB_CLI" "1" "12/08/2014" "mpd-sima" "mpd-sima 0.13.0 User Manual"
+.TH "SIMADB_CLI" "1" "01/28/2015" "mpd-sima" "mpd-sima 0.13.1 User Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
simadb_cli \- simadb_cli is a command line interface editor for the sima user DB\&.
.SH "SYNOPSIS"
.HP \w'\fBsimadb_cli\fR\ 'u
-\fBsimadb_cli\fR \fB\-\-add_similarity=\fR\fIsimilarity_string\fR [\fB\-\-check_names\fR] [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR] [\fB\-\-host=\fR\fImpd_host\fR] [\fB\-\-port=\fR\fImpd_port\fR]
-.HP \w'\fBsimadb_cli\fR\ 'u
\fBsimadb_cli\fR \fB\-\-remove_artist=\fR\fIartist\fR [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR]
.HP \w'\fBsimadb_cli\fR\ 'u
-\fBsimadb_cli\fR \fB\-\-remove_similarity=\fR\fI"main\ artist,similar\ artist"\fR [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR]
-.HP \w'\fBsimadb_cli\fR\ 'u
\fBsimadb_cli\fR \fB\-\-purge_hist\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
.HP \w'\fBsimadb_cli\fR\ 'u
-\fBsimadb_cli\fR \fB\-\-view_artist=\fR\fB\fI"artist\ name"\fR\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
-.HP \w'\fBsimadb_cli\fR\ 'u
\fBsimadb_cli\fR \fB\-\-view_all\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
.HP \w'\fBsimadb_cli\fR\ 'u
\fBsimadb_cli\fR {\fB\-\-bl_curr_trk\fR | \fB\-\-bl_curr_art\fR | \fB\-\-bl_curr_alb\fR | \fB\-\-bl_art=\fR\fIartist_name\fR} [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-host=\fR\fImpd_host\fR] [\fB\-\-port=\fR\fImpd_port\fR]
\fBsimadb_cli\fR
commands\&.
.PP
-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
+simadb_cli is a command line interface to get and edit users blacklist database used with MPD_sima\&. The default database file (see
the section called \(lqFILES\(rq) can be overridden if you want\&.
-.PP
-Consider reading
-the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
-to understand the structure and relation of similarities within the database\&.
.SH "EXAMPLE"
-.SS "Similarity edition"
-.PP
-Here follows some simple examples on how to deal with similarity database\&.
-.PP
-Pay attention, the following examples set one\-way similarities in the DB! Read more about it in
-the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq\&.
-.PP
-\fIAdding a similarity between two artists\&.\fR
-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\&.
-.PP
-\fBsimadb_cli \-\-add "Pelican,Russian Circles:80" \-\-check_names\fR
-.PP
-Similarity string use comma "," as artists separator and semi colon ":" for artist/similarity score separator, cf\&.
-the section called \(lqSIMILARITY FORMAT\(rq\&.
-.PP
-\fIAdding a similarity between multiple artists\&.\fR
-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\&.
-.PP
-\fBsimadb_cli \-\-add "Rage Against The Machine,Tool:70,Audiosalve:80" \-\-check_names\fR
-.PP
-\fIViewing similarit(y|ies) for an artist\&.\fR
-In the following example we are looking for entries for "Rage Against The Machine"
-.PP
-\fBsimadb_cli \-\-view_artist "Rage Against The Machine"\fR
.SS "Black list edition"
.PP
\fIAdding to black list\&.\fR
Print version and exit\&.
.RE
.PP
-\fB\-a \fR\fB\fIsimilarity_string\fR\fR, \fB\-\-add_similarity=\fR\fB\fIsimilarity_string\fR\fR
-.RS 4
-Add similarity to the database\&.
-.br
-For more details about the
-\fIsimilarity_string\fR
-see
-the section called \(lqSIMILARITY FORMAT\(rq\&.
-.RE
-.PP
-\fB\-c\fR, \fB\-\-check_names\fR
-.RS 4
-Use with
-\fB\-\-add_similarity\fR
-in order to check artists names used in
-\fIsimilarity_string\fR\&. simadb_cli will control presence of artists names in MPD library\&. Default is to look for MPD server on localhost:6600 or environment variables
-\fBMPD_HOST\fR
-and
-\fBMPD_PORT\fR
-if set\&.
-.br
-You can as well give simadb_cli host/port on the command line using respectively
-\fB\-S\fR
-and
-\fB\-P\fR\&.
-.RE
-.PP
\fB\-\-bl_art=\fR\fB\fIartist_name\fR\fR
.RS 4
Use to black list
Purge history, you may supply an alternative DB file with \-\-dbfile option\&.
.RE
.PP
-\fB\-r\fR, \fB\-\-reciprocal\fR
-.RS 4
-Use with an editing options in order to edit reciprocal similarity as well\&.
-\fB\-\-add_similarity\fR
-and
-\fB\-\-remove_{artist|similarity}\fR
-are supporting reciprocal edition\&.
-.sp
-\fIN\&.B\fR: this option has to appear after the editing option on the command line\&.
-.sp
-See
-the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
-for further information about reciprocity notion\&.
-.RE
-.PP
-\fB\-\-remove_artist=\fR\fB\fIartist\fR\fR
-.RS 4
-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
-\fB\-\-reciprocal\fR
-option\&.
-.RE
-.PP
\fB\-\-remove_bl=\fR\fB\fIrow_id\fR\fR
.RS 4
Use to remove a black list entry\&. To get the row_id to suppress use
option\&.
.RE
.PP
-\fB\-\-remove_similarity=\fR\fB\fI"main artist,similar artist"\fR\fR
-.RS 4
-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\&.
-.br
-Use of
-\fB\-\-reciprocal\fR
-is possible here, see
-the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq\&.
-.sp
-This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use
-\fB\-\-remove_artist\fR
-instead\&.
-.RE
-.PP
-\fB\-v \fR\fB\fI"artist name"\fR\fR, \fB\-\-view_artist=\fR\fB\fI"artist name"\fR\fR
-.RS 4
-Get entries for
-\fI"artist name"\fR
-in the data base (print to stdout)\&.
-.RE
-.PP
\fB\-\-view_bl\fR
.RS 4
Get all entries in the black list\&.
.RE
.PP
-\fB\-\-view_all\fR
-.RS 4
-Get all entries in the data base (print to stdout)\&.
-.RE
-.PP
\fB\-P \fR\fB\fImpd_port\fR\fR, \fB\-\-port=\fR\fB\fImpd_port\fR\fR
.RS 4
Use the specific port number
is set to
${HOME}/\&.local/share\&.
.RE
-.SH "SIMILARITY FORMAT"
-.PP
-The
-\fIsimilarity_string\fR
-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
-\fImain_art\fR, followed by a list of similar artists which you want to be related to that
-\fImain_art\fR, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the
-\fImain_art\fR\&. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match\&.
-.PP
-\fIsimilarity_string\fR
-is then to be formatted as follow:
-.PP
-\fBmain_art,first artist:<score>,second artist:<score>\fR
-.PP
-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\&.
-.PP
-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
-\fIsimilarity_string\fR
-will be the following:
-.PP
-\fBLed Zeppelin,Tool:25,Audiosalve:20\fR
-.PP
-See
-the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
-for more details about how similarities are handled
-.SH "A WORD ABOUT SIMA DATA BASE"
-.PP
-The similarity database is defined from the point of view of a
-\fImain artist\fR
-which is declared related to a list of
-\fIsimilar artists\fR\&. That means when you define
-\fImain_art\fR
-to be similar to
-\fIsim_art A\fR
-and
-\fIsim_art B\fR
-the reciprocal won\*(Aqt be true,
-\fIsim_art A\fR
-and
-\fIsim_art B\fR
-are not similar to
-\fImain_art\fR\&. 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"\&.
-.br
-The
-\fB\-\-reciprocal\fR
-option allows one to add reciprocal relation where
-\fIsim_art A\fR
-and
-\fIsim_art B\fR
-become respectively the
-\fImain_art\fR\&. Using
-\fB\-\-reciprocal\fR
-you will then edit two more entries in the database\&. To summarize here is what you\*(Aqll end up with in your data base adding similarity with this string
-\fBmain_art,sim_art A:34,sim_art B:45\fR\&.
-.PP
-\fBsimadb_cli \-\-reciprocal \-\-add_similarity=main_art,sim_art A:34,sim_art B:45\fR
-.PP
-main_art similar to sim_art A:34 and sim_art B:45
-.br
-sim_art A similar to main_art:34
-.br
-sim_art B similar to main_art:45
-.PP
-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)\&.
.SH "FEEDBACK/BUGS"
.PP
The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
.RE
.SH "COPYRIGHT"
.br
-Copyright \(co 2009-2014 Jack Kaliko
+Copyright \(co 2009-2015 Jack Kaliko
.br
.PP
This manual page was written for the Debian system (and may be used by others)\&.
<refpurpose>&dhutils; is a command line interface editor for the sima user DB.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis><!-- REGULAR EDIT (ADD) OPTIONS -->
- <command>&dhutils;</command>
- <arg choice="plain"><option>--add_similarity=</option><replaceable class="option">similarity_string</replaceable></arg>
- <arg choice="opt">
- <option>--check_names</option>
- </arg>
- <arg choice="opt">
- <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
- </arg>
- <arg choice="opt">
- <option>--reciprocal</option>
- </arg>
- <arg choice="opt">
- <option>--host=</option><replaceable class="option">mpd_host</replaceable>
- </arg>
- <arg choice="opt">
- <option>--port=</option><replaceable class="option">mpd_port</replaceable>
- </arg>
- </cmdsynopsis>
<cmdsynopsis><!-- EDIT (RM ARTIST) OPTIONS -->
<command>&dhutils;</command>
<arg choice="plain"><option>--remove_artist=</option><replaceable class="parameter">artist</replaceable></arg>
<option>--reciprocal</option>
</arg>
</cmdsynopsis>
- <cmdsynopsis><!-- EDIT (RM SIM) OPTIONS -->
- <command>&dhutils;</command>
- <arg choice="plain"><option>--remove_similarity=</option><replaceable class="parameter">"main artist,similar artist"</replaceable></arg>
- <arg choice="opt">
- <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
- </arg>
- <arg choice="opt">
- <option>--reciprocal</option>
- </arg>
- </cmdsynopsis>
<cmdsynopsis><!-- EDIT (PURGE HIST) OPTIONS -->
<command>&dhutils;</command>
<arg choice="plain"><option>--purge_hist</option></arg>
<option>--dbfile=</option><replaceable class="option">db_file</replaceable>
</arg>
</cmdsynopsis>
- <cmdsynopsis><!-- REGULAR VIEW OPTIONS -->
- <command>&dhutils;</command>
- <arg choice="plain"><option>--view_artist=<replaceable class="parameter">"artist name"</replaceable></option></arg>
- <arg choice="opt">
- <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
- </arg>
- </cmdsynopsis>
<cmdsynopsis><!-- VIEW ALL ENTRIES OPTIONS -->
<command>&dhutils;</command>
<arg choice="plain"><option>--view_all</option></arg>
<para>This manual page documents briefly the
<command>&dhutils;</command> commands.</para>
<para>simadb_cli is a command line interface to get and edit users
- similarities and blacklist database used with MPD_sima. The default
+ blacklist database used with MPD_sima. The default
database file (see <xref linkend="files"/>) can be overridden if
you want.</para>
- <para>Consider reading <xref linkend="simadb" /> to understand the
- structure and relation of similarities within the database.</para>
</refsect1>
<refsect1 id="example">
<title>EXAMPLE</title>
- <refsect2 id="similarity">
- <title>Similarity edition</title>
- <para>Here follows some simple examples on how to deal with similarity database.</para>
- <para>Pay attention, the following examples set one-way similarities in the DB! Read more about it in <xref linkend="simadb" />.</para>
- <para><emphasis>Adding a similarity between two artists.</emphasis> 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.</para>
- <para><command>&dhutils; --add "Pelican,Russian Circles:80" --check_names</command></para>
- <para>Similarity string use comma "," as artists separator and semi colon ":" for
- artist/similarity score separator, cf. <xref linkend="simiformat"/>.</para>
- <para><emphasis>Adding a similarity between multiple artists.</emphasis> 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.</para>
- <para><command>&dhutils; --add "Rage Against The Machine,Tool:70,Audiosalve:80" --check_names</command></para>
- <para><emphasis>Viewing similarit(y|ies) for an artist.</emphasis> In the
- following example we are looking for entries for "Rage Against The Machine"</para>
- <para><command>&dhutils; --view_artist "Rage Against The Machine"</command></para>
- </refsect2>
<refsect2 id="blacklist">
<title>Black list edition</title>
<para><emphasis>Adding to black list.</emphasis> You can add a single
<para>Print version and exit.</para>
</listitem>
</varlistentry>
- <varlistentry> <!-- add similarity -->
- <term><option>-a <replaceable class="parameter">similarity_string</replaceable></option></term>
- <term><option>--add_similarity=<replaceable class="parameter">similarity_string</replaceable></option></term>
- <listitem>
- <para>Add similarity to the database.<sbr />For more details about the <replaceable class="option">similarity_string</replaceable> see <xref linkend="simiformat"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- check_names -->
- <term><option>-c</option></term>
- <term><option>--check_names</option></term>
- <listitem>
- <para>Use with <option>--add_similarity</option> in order to check artists names used in <replaceable class="parameter">similarity_string</replaceable>. &dhutils; will control presence of artists names in MPD library. Default is to look for MPD server on localhost:6600 or environment variables <envar>MPD_HOST</envar> and <envar>MPD_PORT</envar> if set.<sbr />You can as well give &dhutils; host/port on the command line using respectively <option>-S</option> and <option>-P</option>.</para>
- </listitem>
- </varlistentry>
<varlistentry> <!-- black list artist -->
<term><option>--bl_art=<replaceable class="parameter">artist_name</replaceable></option></term>
<listitem>
<para>Purge history, you may supply an alternative DB file with --dbfile option.</para>
</listitem>
</varlistentry>
- <varlistentry> <!-- reciprocal -->
- <term><option>-r</option></term>
- <term><option>--reciprocal</option></term>
- <listitem>
- <para>Use with an editing options in order to edit reciprocal similarity as well. <option>--add_similarity</option> and <option>--remove_{artist|similarity}</option> are supporting reciprocal edition.</para>
- <para><emphasis>N.B</emphasis>: this option has to appear after the editing option on the command line.</para>
- <para>See <xref linkend="simadb"/> for further information about reciprocity notion.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- remove artist -->
- <term><option>--remove_artist=<replaceable class="parameter">artist</replaceable></option></term>
- <listitem>
- <para>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 <option>--reciprocal</option> option.</para>
- </listitem>
- </varlistentry>
<varlistentry> <!-- remove bl id -->
<term><option>--remove_bl=<replaceable class="parameter">row_id</replaceable></option></term>
<listitem>
<para>Use to remove a black list entry. To get the row_id to suppress use <option>--view_bl</option> option.</para>
</listitem>
</varlistentry>
- <varlistentry> <!-- remove similarity -->
- <term><option>--remove_similarity=<replaceable class="parameter">"main artist,similar artist"</replaceable></option></term>
- <listitem>
- <para>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.<sbr />Use of <option>--reciprocal</option> is possible here, see <xref linkend="simadb" />.</para>
- <para>This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use <option>--remove_artist</option> instead.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- view artist -->
- <term><option>-v <replaceable class="parameter">"artist name"</replaceable></option></term>
- <term><option>--view_artist=<replaceable class="parameter">"artist name"</replaceable></option></term>
- <listitem>
- <para>Get entries for <replaceable class="parameter">"artist name"</replaceable> in the data base (print to stdout).</para>
- </listitem>
- </varlistentry>
<varlistentry> <!-- view bl -->
<term><option>--view_bl</option></term>
<listitem>
<para>Get all entries in the black list.</para>
</listitem>
</varlistentry>
- <varlistentry> <!-- view all -->
- <term><option>--view_all</option></term>
- <listitem>
- <para>Get all entries in the data base (print to stdout).</para>
- </listitem>
- </varlistentry>
<varlistentry>
<term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
<term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
</varlistentry>
</variablelist>
</refsect1>
- <refsect1 id="simiformat">
- <title>SIMILARITY FORMAT</title>
- <para>The <replaceable class="parameter">similarity_string</replaceable> 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 <emphasis>main_art</emphasis>, followed by a list of similar artists which you want to be related to that <emphasis>main_art</emphasis>, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the <emphasis>main_art</emphasis>. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match.</para>
- <para><replaceable class="parameter">similarity_string</replaceable> is then to be formatted as follow:</para>
- <para><command>main_art,first artist:<score>,second artist:<score></command></para>
- <para>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.</para>
- <para>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 <replaceable class="parameter">similarity_string</replaceable> will be the following:</para>
- <para><command>Led Zeppelin,Tool:25,Audiosalve:20</command></para>
- <para>See <xref linkend="simadb" /> for more details about how similarities are handled</para>
- </refsect1>
- <refsect1 id="simadb">
- <title>A WORD ABOUT SIMA DATA BASE</title>
- <para>The similarity database is defined from the point of view of a <emphasis>main artist</emphasis> which is declared related to a list of <emphasis>similar artists</emphasis>. That means when you define <emphasis>main_art</emphasis> to be similar to <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> the reciprocal won't be true, <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> are not similar to <emphasis>main_art</emphasis>. 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".<sbr />The <option>--reciprocal</option> option allows one to add reciprocal relation where <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> become respectively the <emphasis>main_art</emphasis>. Using <option>--reciprocal</option> 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 <command>main_art,sim_art A:34,sim_art B:45</command>.</para>
- <para><command>simadb_cli --reciprocal --add_similarity=main_art,sim_art A:34,sim_art B:45</command></para>
- <para>main_art similar to sim_art A:34 and sim_art B:45<sbr />sim_art A similar to main_art:34<sbr />sim_art B similar to main_art:45</para>
- <para>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).</para>
- </refsect1>
- <!--
- <refsect1 id="diagnostics">
- <title>DIAGNOSTICS</title>
- <para>The following diagnostics may be issued
- on <filename class="devicefile">stderr</filename>:</para>
- <variablelist>
- <varlistentry>
- <term><errortext>Bad configuration file. Exiting.</errortext></term>
- <listitem>
- <para>The configuration file seems to contain a broken configuration
- line. Use the <option>-''-verbose</option> option, to get more info.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para><command>&dhpackage;</command> provides some return codes, that can
- be used in scripts:</para>
- <segmentedlist>
- <segtitle>Code</segtitle>
- <segtitle>Diagnostic</segtitle>
- <seglistitem>
- <seg><errorcode>0</errorcode></seg>
- <seg>Program exited successfully.</seg>
- </seglistitem>
- <seglistitem>
- <seg><errorcode>1</errorcode></seg>
- <seg>The configuration file seems to be broken.</seg>
- </seglistitem>
- </segmentedlist>
- </refsect1>
- -->
<xi:include href="feedback.xml" />
<xi:include href="seealso.xml" />
</refentry>
+MPD_sima v0.13.1
+
+ * Fixed default conf file name (back to mpd_sima.cfg)
+ * Cleanup code (removed users similarities)
+
+-- kaliko jack <kaliko@azylum.org> UNRELEASED
+
+
MPD_sima v0.13.0
* Use of MusicBrainzIdentifier by default
"""
-__version__ = '0.13.0'
+__version__ = '0.13.1'
__author__ = 'kaliko jack'
__email__ = 'kaliko@azylum.org'
__url__ = 'git://git.kaliko.me/sima.git'
# Artists: <http://musicbrainz.org/doc/Artist_Name>
# <http://musicbrainz.org/doc/Same_Artist_With_Different_Names>
-__DB_VERSION__ = 2
+__DB_VERSION__ = 3
__HIST_DURATION__ = int(30 * 24) # in hours
import sqlite3
pass
-class SimaDBUpgradeError(SimaDBError):
- """Error on upgrade"""
- pass
-
-
class SimaDB(object):
"SQLite management"
#connection.text_factory = str
return connection
- def upgrade(self):
- """upgrade DB from previous versions"""
- connection = self.get_database_connection()
- try:
- connection.execute('SELECT version FROM db_info')
- except Exception as err:
- if err.__str__() == "no such table: db_info":
- # db version < 2 (MPD_sima 0.6)
- copyfile(self._db_path, self._db_path + '.0.6')
- connection.execute('DROP TABLE tracks')
- connection.commit()
- self.create_db()
- else:
- raise SimaDBUpgradeError('Could not upgrade database: "%s"' %
- err)
- self.close_database_connection(connection)
-
def get_artist(self, artist_name, mbid=None,
with_connection=None, add_not=False):
"""get artist information from the database.
self.close_database_connection(connection)
def _set_mbid(self, artist_id=None, mbid=None, with_connection=None):
- """get artist information from the database.
- if not in database insert new entry."""
+ """"""
if with_connection:
connection = with_connection
else:
if not with_connection:
self.close_database_connection(connection)
- def _get_similar_artists_from_db(self, artist_id):
- connection = self.get_database_connection()
- results = [row for row in connection.execute(
- "SELECT match, name FROM usr_artist_2_artist INNER JOIN"
- " artists ON usr_artist_2_artist.artist2 = artists.id WHERE"
- " usr_artist_2_artist.artist1 = ? ORDER BY match DESC;",
- (artist_id,))]
- self.close_database_connection(connection)
- for score, artist in results:
- yield {'score': score, 'artist': artist}
-
- def _get_reverse_similar_artists_from_db(self, artist_id):
- connection = self.get_database_connection()
- results = [row for row in connection.execute(
- "SELECT name FROM usr_artist_2_artist INNER JOIN"
- " artists ON usr_artist_2_artist.artist1 = artists.id WHERE"
- " usr_artist_2_artist.artist2 = ?;",
- (artist_id,))]
- self.close_database_connection(connection)
- for artist in results:
- yield artist[0]
-
- def get_similar_artists(self, artist_name):
- """get similar artists from the database sorted by descending
- match score"""
- artist_id = self.get_artist(artist_name)[0]
- for result in self._get_similar_artists_from_db(artist_id):
- yield result
-
- def _get_artist_match(self, artist1, artist2, with_connection=None):
- """get artist match score from database"""
- if with_connection:
- connection = with_connection
- else:
- connection = self.get_database_connection()
- rows = connection.execute(
- "SELECT match FROM usr_artist_2_artist WHERE artist1 = ?"
- " AND artist2 = ?",
- (artist1, artist2))
- result = 0
- for row in rows:
- result = row[0]
- break
- if not with_connection:
- self.close_database_connection(connection)
- return result
-
- def _remove_relation_between_2_artist(self, artist1, artist2):
- """Remove a similarity relation"""
- connection = self.get_database_connection()
- connection.execute(
- 'DELETE FROM usr_artist_2_artist'
- ' WHERE artist1 = ? AND artist2 = ?;',
- (artist1, artist2))
- self.clean_database(with_connection=connection)
- self._update_artist(artist_id=artist1, with_connection=connection)
- connection.commit()
- self.close_database_connection(connection)
-
- def _remove_artist(self, artist_id, deep=False, with_connection=None):
- """Remove all artist1 reference"""
- if with_connection:
- connection = with_connection
- else:
- connection = self.get_database_connection()
- if deep:
- connection.execute(
- 'DELETE FROM usr_artist_2_artist'
- ' WHERE artist1 = ? OR artist2 = ?;',
- (artist_id, artist_id))
- connection.execute(
- 'DELETE FROM artists WHERE id = ?;',
- (artist_id,))
- else:
- connection.execute(
- 'DELETE FROM usr_artist_2_artist WHERE artist1 = ?;',
- (artist_id,))
- self.clean_database(with_connection=connection)
- self._update_artist(artist_id=artist_id, with_connection=connection)
- if not with_connection:
- connection.commit()
- self.close_database_connection(connection)
-
def _remove_bl(self, rowid):
"""Remove bl row id"""
connection = self.get_database_connection()
connection.commit()
self.close_database_connection(connection)
- def _insert_artist_match(
- self, artist1, artist2, match, with_connection=None):
- """write match score to the database.
- Does not update time stamp in table artist/*_updated"""
- if with_connection:
- connection = with_connection
- else:
- connection = self.get_database_connection()
- connection.execute(
- "INSERT INTO usr_artist_2_artist (artist1, artist2, match) VALUES"
- " (?, ?, ?)",
- (artist1, artist2, match))
- if not with_connection:
- connection.commit()
- self.close_database_connection(connection)
-
def add_history(self, track):
"""Add to history"""
connection = self.get_database_connection()
connection.commit()
self.close_database_connection(connection)
- def _update_artist(self, artist_id, with_connection=None):
- """write artist information to the database"""
- if with_connection:
- connection = with_connection
- else:
- connection = self.get_database_connection()
- connection.execute(
- "UPDATE artists SET usr_updated = DATETIME('now') WHERE id = ?",
- (artist_id,))
- if not with_connection:
- connection.commit()
- self.close_database_connection(connection)
-
- def _update_artist_match(
- self, artist1, artist2, match, with_connection=None):
- """write match score to the database"""
- if with_connection:
- connection = with_connection
- else:
- connection = self.get_database_connection()
- connection.execute(
- "UPDATE usr_artist_2_artist SET match = ? WHERE artist1 = ? AND"
- " artist2 = ?",
- (match, artist1, artist2))
- if not with_connection:
- connection.commit()
- self.close_database_connection(connection)
-
- def _update_similar_artists(self, artist, similar_artists):
- """write user similar artist information to the database
- """
- # DOC: similar_artists = list([{'score': match, 'artist': name}])
- #
- connection = self.get_database_connection()
- artist_id = self.get_artist(artist, with_connection=connection)[0]
- for artist in similar_artists:
- id2 = self.get_artist(
- artist['artist'], with_connection=connection)[0]
- if self._get_artist_match(
- artist_id, id2, with_connection=connection):
- self._update_artist_match(
- artist_id, id2, artist['score'],
- with_connection=connection)
- continue
- self._insert_artist_match(
- artist_id, id2, artist['score'],
- with_connection=connection)
- self._update_artist(artist_id, with_connection=connection)
- connection.commit()
- self.close_database_connection(connection)
-
def _clean_artists_table(self, with_connection=None):
"""Clean orphan artists"""
if with_connection:
artists_ids = set([row[0] for row in connection.execute(
"SELECT id FROM artists")])
artist_2_artist_ids = set([row[0] for row in connection.execute(
- "SELECT artist1 FROM usr_artist_2_artist")] +
- [row[0] for row in connection.execute(
- "SELECT artist2 FROM usr_artist_2_artist")] +
- [row[0] for row in connection.execute(
"SELECT artist FROM black_list")] +
[row[0] for row in connection.execute(
"SELECT artist FROM albums")] +
self.close_database_connection(connection)
def create_db(self):
- """ Set up a database for the artist similarity scores
+ """ Set up a database
"""
connection = self.get_database_connection()
connection.execute(
' (version INTEGER, name CHAR(36))')
connection.execute(
'CREATE TABLE IF NOT EXISTS artists (id INTEGER PRIMARY KEY, name'
- ' VARCHAR(100), mbid CHAR(36), lfm_updated DATE, usr_updated DATE)')
- connection.execute(
- 'CREATE TABLE IF NOT EXISTS usr_artist_2_artist (artist1 INTEGER,'
- ' artist2 INTEGER, match INTEGER)')
- connection.execute(
- 'CREATE TABLE IF NOT EXISTS lfm_artist_2_artist (artist1 INTEGER,'
- ' artist2 INTEGER, match INTEGER)')
+ ' VARCHAR(100), mbid CHAR(36))')
connection.execute(
'CREATE TABLE IF NOT EXISTS albums (id INTEGER PRIMARY KEY,'
' artist INTEGER, name VARCHAR(100), mbid CHAR(36))')
connection.execute(
'CREATE TABLE IF NOT EXISTS history (last_play DATE,'
' track integer)')
- connection.execute(
- "CREATE INDEX IF NOT EXISTS a2aa1x ON usr_artist_2_artist (artist1)")
- connection.execute(
- "CREATE INDEX IF NOT EXISTS a2aa2x ON usr_artist_2_artist (artist2)")
- connection.execute(
- "CREATE INDEX IF NOT EXISTS lfma2aa1x ON lfm_artist_2_artist (artist1)")
- connection.execute(
- "CREATE INDEX IF NOT EXISTS lfma2aa2x ON lfm_artist_2_artist (artist2)")
connection.commit()
self.close_database_connection(connection)
self._set_dbversion()
-def main():
- db = SimaDB(db_path='/tmp/sima.db')
- db.purge_history(int(4))
- db.clean_database()
-
-
-# Script starts here
-if __name__ == '__main__':
- main()
-
# VIM MODLINE
# vim: ai ts=4 sw=4 sts=4 expandtab
'contrib': "",
'user_db': "false",
'history_duration': 8,
- 'queue_length': 1,
+ 'queue_length': 2,
'var_dir': 'empty',
'musicbrainzid': "true",
},
between artists."""
DB_NAME = 'sima.db'
-class FooAction(Action):
- def check(self, namespace):
- if namespace.similarity: return True
- if namespace.remove_art: return True
- if namespace.remove_sim: return True
-
- def __call__(self, parser, namespace, values, option_string=None):
- opt_required = '"--remove_artist", "--remove_similarity" or "--add_similarity"'
- if not self.check(namespace):
- parser.error(
- 'can\'t use {0} option before or without {1}'.format(
- option_string, opt_required))
- setattr(namespace, self.dest, True)
-
# Options list
# pop out 'sw' value before creating ArgumentParser object.
OPTS = list([
- {
- 'sw':['-a', '--add_similarity'],
- 'type': str,
- 'dest':'similarity',
- 'help': 'Similarity to add formated as follow: ' +
- ' "art_0,art_1:90,art_2:80..."'},
- {
- 'sw': ['-c', '--check_names'],
- 'action': 'store_true',
- 'default': False,
- 'help': 'Turn on controls of artists names in MPD library.'},
{
'sw':['-d', '--dbfile'],
'type': str,
'dest':'dbfile',
'action': utils.Wfile,
'help': 'File to read/write database from/to'},
- {
- 'sw': ['-r', '--reciprocal'],
- 'default': False,
- 'nargs': 0,
- 'action': FooAction,
- 'help': 'Turn on reciprocity for similarity relation when add/remove.'},
- {
- 'sw':['--remove_artist'],
- 'type': str,
- 'dest': 'remove_art',
- 'metavar': '"ARTIST TO REMOVE"',
- 'help': 'Remove an artist from DB (main artist entries).'},
- {
- 'sw':['--remove_similarity'],
- 'type': str,
- 'dest': 'remove_sim',
- 'metavar': '"MAIN ART,SIMI ART"',
- 'help': 'Remove an similarity relation from DB (main artist <=> similar artist).'},
- {
- 'sw':['-v', '--view_artist'],
- 'type': str,
- 'dest':'view',
- 'metavar': '"ARTIST NAME"',
- 'help': 'View an artist from DB.'},
- {
- 'sw':['--view_all'],
- 'action': 'store_true',
- 'help': 'View all similarity entries.'},
{
'sw': ['-S', '--host'],
'type': str,
mpd_cli.disconnect()
return control
- def _parse_similarity(self):
- """Parse command line option similarity"""
- cli_sim = self.options.similarity.strip(',').split(',')
- sim = list([])
- main = cli_sim[0]
- for art in cli_sim[1:]:
- artist = art.split(':')[0]
- score = int(art.split(':')[1])
- sim.append({'artist': artist, 'score': score})
- return (main, sim)
-
- def _print_main_art(self, art=None):
- """Print entries, art as main artist."""
- if not art:
- art = self.options.view
- db = simadb.SimaDB(db_path=self.dbfile)
- art_db = self._get_art_from_db(art)
- if not art_db: return
- sims = list([])
- [sims.append(a) for a in db._get_similar_artists_from_db(art_db[0])]
- if len(sims) == 0:
- return False
- print('"%s" similarities:' % art)
- for art in sims:
- mess = str(' - {score:0>2d} {artist}'.format(**art))
- print(mess)
- return True
-
- def _remove_sim(self, art1_db, art2_db):
- """Remove single similarity between two artists."""
- db = simadb.SimaDB(db_path=self.dbfile)
- similarity = db._get_artist_match(art1_db[0], art2_db[0])
- if similarity == 0:
- return False
- db._remove_relation_between_2_artist(art1_db[0], art2_db[0])
- mess = 'Remove: "{0}" "{1}:{2:0>2d}"'.format(art1_db[1], art2_db[1],
- similarity)
- print(mess)
- return True
-
- def _revert_similarity(self, sim_formated):
- """Revert similarity string (for reciprocal editing - add)."""
- main_art = sim_formated[0]
- similars = sim_formated[1]
- for similar in similars:
- yield (similar.get('artist'),
- [{'artist':main_art, 'score':similar.get('score')}])
-
def bl_artist(self):
"""Black list artist"""
mpd_cli = self._get_mpd_client()
db.clean_database()
print('done.')
- def view(self):
- """Print out entries for an artist."""
- art = self.options.view
- db = simadb.SimaDB(db_path=self.dbfile)
- art_db = self._get_art_from_db(art)
- if not art_db: return
- if not self._print_main_art():
- mess = str('"%s" present in DB but not as a main artist' % art)
- print(mess)
- else: print('')
- art_rev = list([])
- [art_rev.append(a) for a in db._get_reverse_similar_artists_from_db(art_db[0])]
- if not art_rev: return
- mess = str('%s" appears as similar for the following artist(s): %s' %
- (art,', '.join(art_rev)))
- print(mess)
- [self._print_main_art(a) for a in art_rev]
-
- def view_all(self):
- """Print out all entries."""
- db = simadb.SimaDB(db_path=self.dbfile)
- for art in db.get_artists():
- if not art[0]: continue
- self._print_main_art(art=art[0])
-
def view_bl(self):
"""Print out black list."""
# TODO: enhance output formating
for bl_e in db.get_black_list():
print('\t# '.join([str(e) for e in bl_e]))
- def remove_similarity(self):
- """Remove entry"""
- cli_sim = self.options.remove_sim
- pattern = '^([^,]+?),([^,]+?,?)$'
- regexp = re.compile(pattern, re.U).match(cli_sim)
- if not regexp:
- print('ERROR: similarity badly formated: "%s"' % cli_sim, file=stderr)
- print('USAGE: A single relation between two artists is expected here.', file=stderr)
- print('USAGE: "main artist,similar artist"', file=stderr)
- exit(1)
- arts = cli_sim.split(',')
- if len(arts) != 2:
- print('ERROR: unknown error in similarity format', file=stderr)
- print('USAGE: "main artist,similar artist"', file=stderr)
- exit(1)
- art1_db = self._get_art_from_db(arts[0].strip())
- art2_db = self._get_art_from_db(arts[1].strip())
- if not art1_db or not art2_db: return
- self._remove_sim(art1_db, art2_db)
- if not self.options.reciprocal:
- return
- self._remove_sim(art2_db, art1_db)
-
- def remove_artist(self):
- """ Remove artist in the DB."""
- deep = False
- art = self.options.remove_art
- db = simadb.SimaDB(db_path=self.dbfile)
- art_db = self._get_art_from_db(art)
- if not art_db: return False
- print('Removing "%s" from database' % art)
- if self.options.reciprocal:
- print('reciprocal option used, performing deep remove!')
- deep = True
- db._remove_artist(art_db[0], deep=deep)
-
def remove_black_list_entry(self):
""""""
db = simadb.SimaDB(db_path=self.dbfile)
db._remove_bl(int(self.options.remove_bl))
- def write_simi(self):
- """Write similarity to DB.
- """
- self._create_db()
- sim_formated = self._parse_similarity()
- print('About to update DB with: "%s": %s' % sim_formated)
- db = simadb.SimaDB(db_path=self.dbfile)
- db._update_similar_artists(*sim_formated)
- if self.options.reciprocal:
- print('...and with reciprocal combinations as well.')
- for sim_formed_rec in self._revert_similarity(sim_formated):
- db._update_similar_artists(*sim_formed_rec)
-
def main(self):
"""
Parse command line and run actions.
if self.options.dbfile:
self.dbfile = self.options.dbfile
print('Using db file: %s' % self.dbfile)
- if self.options.reciprocal:
- print('Editing reciprocal similarity')
if self.options.bl_art:
self.bl_artist()
return
if self.options.remove_bl:
self.remove_black_list_entry()
return
- if self.options.similarity:
- self._control_similarity()
- self.write_simi()
- return
- if self.options.remove_art:
- self.remove_artist()
- return
- if self.options.remove_sim:
- self.remove_similarity()
- return
- if self.options.view:
- self.view()
- return
- if self.options.view_all:
- self.view_all()
if self.options.do_purge_hist:
self.purge_history()
exit(0)
home / dev / repositories / mpd-sima.git / commitdiff