1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>simadb_cli</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="simadb_cli"><a name="idp104"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>simadb_cli — simadb_cli is a command line interface editor for the sima user DB.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--add_similarity=</code><em class="replaceable"><code>similarity_string</code></em> [
<code class="option">--check_names</code>
] [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
] [
<code class="option">--reciprocal</code>
] [
<code class="option">--host=</code><em class="replaceable"><code>mpd_host</code></em>
] [
<code class="option">--port=</code><em class="replaceable"><code>mpd_port</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--remove_artist=</code><em class="replaceable"><code>artist</code></em> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
] [
<code class="option">--reciprocal</code>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--remove_similarity=</code><em class="replaceable"><code>"main artist,similar artist"</code></em> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
] [
<code class="option">--reciprocal</code>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--purge_hist</code> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--view_artist=<em class="replaceable"><code>"artist name"</code></em></code> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--view_all</code> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> { <code class="option">--bl_curr_trk</code> | <code class="option">--bl_curr_art</code> | <code class="option">--bl_curr_alb</code> | <code class="option">--bl_art=</code><em class="replaceable"><code>artist_name</code></em> } [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
] [
<code class="option">--host=</code><em class="replaceable"><code>mpd_host</code></em>
] [
<code class="option">--port=</code><em class="replaceable"><code>mpd_port</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--remove_bl=</code><em class="replaceable"><code>row_id</code></em> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> <code class="option">--view_bl</code> [
<code class="option">--dbfile=</code><em class="replaceable"><code>db_file</code></em>
]</p></div><div class="cmdsynopsis"><p><code class="command">simadb_cli</code> {
{ <code class="option">-h</code> | <code class="option">--help</code> }
| <code class="option">--version</code> }</p></div></div><div class="refsect1" title="DESCRIPTION"><a name="description"></a><h2>DESCRIPTION</h2>
<p>This manual page documents briefly the
<span class="command"><strong>simadb_cli</strong></span> commands.</p>
<p>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 <a class="xref" href="#files" title="FILES">the section called “FILES”</a>) can be overridden if
you want.</p>
<p>Consider reading <a class="xref" href="#simadb" title="A WORD ABOUT SIMA DATA BASE">the section called “A WORD ABOUT SIMA DATA BASE”</a> to understand the
structure and relation of similarities within the database.</p>
</div><div class="refsect1" title="EXAMPLE"><a name="example"></a><h2>EXAMPLE</h2>
<div class="refsect2" title="Similarity edition"><a name="similarity"></a><h3>Similarity edition</h3>
<p>Here follows some simple examples on how to deal with similarity database.</p>
<p>Pay attention, the following examples set one-way similarities in the DB! Read more about it in <a class="xref" href="#simadb" title="A WORD ABOUT SIMA DATA BASE">the section called “A WORD ABOUT SIMA DATA BASE”</a>.</p>
<p><span class="emphasis"><em>Adding a similarity between two artists.</em></span> 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.</p>
<p><span class="command"><strong>simadb_cli --add "Pelican,Russian Circles:80" --check_names</strong></span></p>
<p>Similarity string use comma "," as artists separator and semi colon ":" for
artist/similarity score separator, cf. <a class="xref" href="#simiformat" title="SIMILARITY FORMAT">the section called “SIMILARITY FORMAT”</a>.</p>
<p><span class="emphasis"><em>Adding a similarity between multiple artists.</em></span> 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.</p>
<p><span class="command"><strong>simadb_cli --add "Rage Against The Machine,Tool:70,Audiosalve:80" --check_names</strong></span></p>
<p><span class="emphasis"><em>Viewing similarit(y|ies) for an artist.</em></span> In the
following example we are looking for entries for "Rage Against The Machine"</p>
<p><span class="command"><strong>simadb_cli --view_artist "Rage Against The Machine"</strong></span></p>
</div>
<div class="refsect2" title="Black list edition"><a name="blacklist"></a><h3>Black list edition</h3>
<p><span class="emphasis"><em>Adding to black list.</em></span> 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
<code class="option">--bl_curr_trk</code> to prevent simadb_cli to queue this
track, <code class="option">--bl_curr_alb</code> or <code class="option">--bl_curr_art</code> respectively for the album and the
artist.
</p>
<p>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:
</p>
<p><span class="command"><strong>simadb_cli --bl_curr_art -S mympd.example.org</strong></span></p>
<p>
<span class="emphasis"><em>To black list a specific artist</em></span> (not
currently playing) you can use <code class="option">--bl_ar="Artist name to black list"</code>.
</p>
</div>
</div><div class="refsect1" title="OPTIONS"><a name="options"></a><h2>OPTIONS</h2>
<p>The program follows the usual GNU command line syntax,
with long options starting with two dashes ("-"). A summary of
options is included below.</p>
<div class="variablelist"><dl><dt><span class="term"><code class="option">-h</code>, </span><span class="term"><code class="option">--help</code></span></dt><dd><p>Print help and exit.</p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>Print version and exit.</p></dd><dt><span class="term"><code class="option">-a <em class="replaceable"><code>similarity_string</code></em></code>, </span><span class="term"><code class="option">--add_similarity=<em class="replaceable"><code>similarity_string</code></em></code></span></dt><dd><p>Add similarity to the database.<br>For more details about the <em class="replaceable"><code>similarity_string</code></em> see <a class="xref" href="#simiformat" title="SIMILARITY FORMAT">the section called “SIMILARITY FORMAT”</a>.</p></dd><dt><span class="term"><code class="option">-c</code>, </span><span class="term"><code class="option">--check_names</code></span></dt><dd><p>Use with <code class="option">--add_similarity</code> in order to check artists names used in <em class="replaceable"><code>similarity_string</code></em>. simadb_cli will control presence of artists names in MPD library. Default is to look for MPD server on localhost:6600 or environment variables <code class="envar">MPD_HOST</code> and <code class="envar">MPD_PORT</code> if set.<br>You can as well give simadb_cli host/port on the command line using respectively <code class="option">-S</code> and <code class="option">-P</code>.</p></dd><dt><span class="term"><code class="option">--bl_art=<em class="replaceable"><code>artist_name</code></em></code></span></dt><dd><p>Use to black list <em class="replaceable"><code>artist_name</code></em>. simadb_cli is checking <em class="replaceable"><code>artist_name</code></em> is actually in MPD music library (cf <code class="option">-S</code> and <code class="option">-P</code> options to set MPD host/address if necessary).</p><p>If <em class="replaceable"><code>artist_name</code></em> is not found the script print out a list of matching artists.</p></dd><dt><span class="term"><code class="option">--bl_curr_trk</code> | <code class="option">--bl_curr_art</code> | <code class="option">--bl_curr_alb</code></span></dt><dd><p>Use to black list the currently playing track|artist|album. You need access to your MPD server, use <code class="option">-S</code> and <code class="option">-P</code> to set MPD host/address if necessary.</p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>db_file</code></em></code>, </span><span class="term"><code class="option">--dbfile=<em class="replaceable"><code>db_file</code></em></code></span></dt><dd><p>Use the specific file <em class="replaceable"><code>db_file</code></em> as database.<br>Default is too use <code class="envar">XDG_DATA_HOME</code> (see <a class="xref" href="#files" title="FILES">the section called “FILES”</a>).</p></dd><dt><span class="term"><code class="option">--purge_hist</code></span></dt><dd><p>Purge history, you may supply an alternative DB file with --dbfile option.</p></dd><dt><span class="term"><code class="option">-r</code>, </span><span class="term"><code class="option">--reciprocal</code></span></dt><dd><p>Use with an editing options in order to edit reciprocal similarity as well. <code class="option">--add_similarity</code> and <code class="option">--remove_{artist|similarity}</code> are supporting reciprocal edition.</p><p><span class="emphasis"><em>N.B</em></span>: this option has to appear after the editing option on the command line.</p><p>See <a class="xref" href="#simadb" title="A WORD ABOUT SIMA DATA BASE">the section called “A WORD ABOUT SIMA DATA BASE”</a> for further information about reciprocity notion.</p></dd><dt><span class="term"><code class="option">--remove_artist=<em class="replaceable"><code>artist</code></em></code></span></dt><dd><p>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 <code class="option">--reciprocal</code> option.</p></dd><dt><span class="term"><code class="option">--remove_bl=<em class="replaceable"><code>row_id</code></em></code></span></dt><dd><p>Use to remove a black list entry. To get the row_id to suppress use <code class="option">--view_bl</code> option.</p></dd><dt><span class="term"><code class="option">--remove_similarity=<em class="replaceable"><code>"main artist,similar artist"</code></em></code></span></dt><dd><p>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 <code class="option">--reciprocal</code> is possible here, see <a class="xref" href="#simadb" title="A WORD ABOUT SIMA DATA BASE">the section called “A WORD ABOUT SIMA DATA BASE”</a>.</p><p>This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use <code class="option">--remove_artist</code> instead.</p></dd><dt><span class="term"><code class="option">-v <em class="replaceable"><code>"artist name"</code></em></code>, </span><span class="term"><code class="option">--view_artist=<em class="replaceable"><code>"artist name"</code></em></code></span></dt><dd><p>Get entries for <em class="replaceable"><code>"artist name"</code></em> in the data base (print to stdout).</p></dd><dt><span class="term"><code class="option">--view_bl</code></span></dt><dd><p>Get all entries in the black list.</p></dd><dt><span class="term"><code class="option">--view_all</code></span></dt><dd><p>Get all entries in the data base (print to stdout).</p></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>mpd_port</code></em></code>, </span><span class="term"><code class="option">--port=<em class="replaceable"><code>mpd_port</code></em></code></span></dt><dd><p>Use the specific port number <em class="replaceable"><code>mpd_port</code></em> on MPD server. This overrides <code class="envar">MPD_PORT</code> environment variable.<br>Default is <span class="emphasis"><em>6600</em></span>.</p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>mpd_host</code></em></code>, </span><span class="term"><code class="option">--host=<em class="replaceable"><code>mpd_host</code></em></code></span></dt><dd><p>Use the specific host <em class="replaceable"><code>mpd_host</code></em> as MPD server.<br><em class="replaceable"><code>mpd_host</code></em> can be an <acronym class="acronym">IP</acronym> or a fully qualified domain name as long as your system can resolve it. This overrides <code class="envar">MPD_HOST</code> environment variable.<br>Default is <span class="emphasis"><em>localhost</em></span>.</p></dd></dl></div>
</div><div class="refsect1" title="FILES"><a name="files"></a><h2>FILES</h2>
<div class="variablelist"><dl><dt><span class="term"><code class="filename">${XDG_DATA_HOME}/mpd_sima/sima.db</code></span></dt><dd><p>SQLite DB file. Usually <code class="envar">XDG_DATA_HOME</code> is set to <code class="filename">${HOME}/.local/share</code>.</p></dd></dl></div>
</div><div class="refsect1" title="SIMILARITY FORMAT"><a name="simiformat"></a><h2>SIMILARITY FORMAT</h2>
<p>The <em class="replaceable"><code>similarity_string</code></em> 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 <span class="emphasis"><em>main_art</em></span>, followed by a list of similar artists which you want to be related to that <span class="emphasis"><em>main_art</em></span>, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the <span class="emphasis"><em>main_art</em></span>. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match.</p>
<p><em class="replaceable"><code>similarity_string</code></em> is then to be formatted as follow:</p>
<p><span class="command"><strong>main_art,first artist:<score>,second artist:<score></strong></span></p>
<p>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.</p>
<p>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 <em class="replaceable"><code>similarity_string</code></em> will be the following:</p>
<p><span class="command"><strong>Led Zeppelin,Tool:25,Audiosalve:20</strong></span></p>
<p>See <a class="xref" href="#simadb" title="A WORD ABOUT SIMA DATA BASE">the section called “A WORD ABOUT SIMA DATA BASE”</a> for more details about how similarities are handled</p>
</div><div class="refsect1" title="A WORD ABOUT SIMA DATA BASE"><a name="simadb"></a><h2>A WORD ABOUT SIMA DATA BASE</h2>
<p>The similarity database is defined from the point of view of a <span class="emphasis"><em>main artist</em></span> which is declared related to a list of <span class="emphasis"><em>similar artists</em></span>. That means when you define <span class="emphasis"><em>main_art</em></span> to be similar to <span class="emphasis"><em>sim_art A</em></span> and <span class="emphasis"><em>sim_art B</em></span> the reciprocal won't be true, <span class="emphasis"><em>sim_art A</em></span> and <span class="emphasis"><em>sim_art B</em></span> are not similar to <span class="emphasis"><em>main_art</em></span>. 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 <code class="option">--reciprocal</code> option allows one to add reciprocal relation where <span class="emphasis"><em>sim_art A</em></span> and <span class="emphasis"><em>sim_art B</em></span> become respectively the <span class="emphasis"><em>main_art</em></span>. Using <code class="option">--reciprocal</code> 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 <span class="command"><strong>main_art,sim_art A:34,sim_art B:45</strong></span>.</p>
<p><span class="command"><strong>simadb_cli --reciprocal --add_similarity=main_art,sim_art A:34,sim_art B:45</strong></span></p>
<p>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</p>
<p>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).</p>
</div><div class="refsect1" title="BUGS"><a name="bugs"></a><h2>BUGS</h2>
<p>The upstream <acronym class="acronym">BTS</acronym> can be found
at <a class="ulink" href="http://codingteam.net/project/sima/bugs" target="_top">http://codingteam.net/project/sima/bugs</a>.</p>
</div><div class="refsect1" title="FEEDBACK"><a name="feedback"></a><h2>FEEDBACK</h2>
<p>The maintainer would be more than happy to ear from you, don't hesitate to send feedback on the forge, via the upstream <acronym class="acronym">BTS</acronym>, the forum or the chat room, all available on the forge at <a class="ulink" href="http://codingteam.net/project/sima" target="_top">http://codingteam.net/project/sima</a>.</p>
<p><acronym class="acronym">XMPP</acronym> users are welcome to join the dedicated chat room at <a class="ulink" href="sima@conference.codingteam.net" target="_top">sima@conference.codingteam.net</a>.</p>
</div><div class="refsect1" title="SEE ALSO"><a name="see_also"></a><h2>SEE ALSO</h2>
<p><span class="citerefentry"><span class="refentrytitle">mpc</span>(1)</span>, <span class="citerefentry"><span class="refentrytitle">mpd</span>(1)</span></p>
<p>
<code class="filename">/usr/share/doc/mpd-sima/</code>
</p>
</div></div></body></html>
|
