data/man/simadb_cli.1

   1 '\" t
   2 .\"     Title: simadb_cli
   3 .\"    Author: Jack Kaliko <kaliko@azylum.org>
   4 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
   5 .\"      Date: 06/12/2014
   6 .\"    Manual: mpd-sima 0.12.0 User Manual
   7 .\"    Source: mpd-sima
   8 .\"  Language: English
   9 .\"
  10 .TH "SIMADB_CLI" "1" "06/12/2014" "mpd-sima" "mpd-sima 0.12.0 User Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 simadb_cli \- simadb_cli is a command line interface editor for the sima user DB\&.
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBsimadb_cli\fR\ 'u
  34 \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]
  35 .HP \w'\fBsimadb_cli\fR\ 'u
  36 \fBsimadb_cli\fR \fB\-\-remove_artist=\fR\fIartist\fR [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR]
  37 .HP \w'\fBsimadb_cli\fR\ 'u
  38 \fBsimadb_cli\fR \fB\-\-remove_similarity=\fR\fI"main\ artist,similar\ artist"\fR [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR]
  39 .HP \w'\fBsimadb_cli\fR\ 'u
  40 \fBsimadb_cli\fR \fB\-\-purge_hist\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
  41 .HP \w'\fBsimadb_cli\fR\ 'u
  42 \fBsimadb_cli\fR \fB\-\-view_artist=\fR\fB\fI"artist\ name"\fR\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
  43 .HP \w'\fBsimadb_cli\fR\ 'u
  44 \fBsimadb_cli\fR \fB\-\-view_all\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
  45 .HP \w'\fBsimadb_cli\fR\ 'u
  46 \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]
  47 .HP \w'\fBsimadb_cli\fR\ 'u
  48 \fBsimadb_cli\fR \fB\-\-remove_bl=\fR\fIrow_id\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
  49 .HP \w'\fBsimadb_cli\fR\ 'u
  50 \fBsimadb_cli\fR \fB\-\-view_bl\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
  51 .HP \w'\fBsimadb_cli\fR\ 'u
  52 \fBsimadb_cli\fR {{\fB\-h\fR\ |\ \fB\-\-help\fR} | \fB\-\-version\fR}
  53 .SH "DESCRIPTION"
  54 .PP
  55 This manual page documents briefly the
  56 \fBsimadb_cli\fR
  57 commands\&.
  58 .PP
  59 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
  60 the section called \(lqFILES\(rq) can be overridden if you want\&.
  61 .PP
  62 Consider reading
  63 the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
  64 to understand the structure and relation of similarities within the database\&.
  65 .SH "EXAMPLE"
  66 .SS "Similarity edition"
  67 .PP
  68 Here follows some simple examples on how to deal with similarity database\&.
  69 .PP
  70 Pay attention, the following examples set one\-way similarities in the DB! Read more about it in
  71 the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq\&.
  72 .PP
  73 \fIAdding a similarity between two artists\&.\fR
  74 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\&.
  75 .PP
  76 \fBsimadb_cli \-\-add "Pelican,Russian Circles:80" \-\-check_names\fR
  77 .PP
  78 Similarity string use comma "," as artists separator and semi colon ":" for artist/similarity score separator, cf\&.
  79 the section called \(lqSIMILARITY FORMAT\(rq\&.
  80 .PP
  81 \fIAdding a similarity between multiple artists\&.\fR
  82 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\&.
  83 .PP
  84 \fBsimadb_cli \-\-add "Rage Against The Machine,Tool:70,Audiosalve:80" \-\-check_names\fR
  85 .PP
  86 \fIViewing similarit(y|ies) for an artist\&.\fR
  87 In the following example we are looking for entries for "Rage Against The Machine"
  88 .PP
  89 \fBsimadb_cli \-\-view_artist "Rage Against The Machine"\fR
  90 .SS "Black list edition"
  91 .PP
  92 \fIAdding to black list\&.\fR
  93 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
  94 \fB\-\-bl_curr_trk\fR
  95 to prevent simadb_cli to queue this track,
  96 \fB\-\-bl_curr_alb\fR
  97 or
  98 \fB\-\-bl_curr_art\fR
  99 respectively for the album and the artist\&.
 100 .PP
 101 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:
 102 .PP
 103 \fBsimadb_cli \-\-bl_curr_art \-S mympd\&.example\&.org\fR
 104 .PP
 105 \fITo black list a specific artist\fR
 106 (not currently playing) you can use
 107 \fB\-\-bl_ar="Artist name to black list"\fR\&.
 108 .SH "OPTIONS"
 109 .PP
 110 The program follows the usual GNU command line syntax, with long options starting with two dashes ("\-")\&. A summary of options is included below\&.
 111 .PP
 112 \fB\-h\fR, \fB\-\-help\fR
 113 .RS 4
 114 Print help and exit\&.
 115 .RE
 116 .PP
 117 \fB\-\-version\fR
 118 .RS 4
 119 Print version and exit\&.
 120 .RE
 121 .PP
 122 \fB\-a \fR\fB\fIsimilarity_string\fR\fR, \fB\-\-add_similarity=\fR\fB\fIsimilarity_string\fR\fR
 123 .RS 4
 124 Add similarity to the database\&.
 125 .br
 126 For more details about the
 127 \fIsimilarity_string\fR
 128 see
 129 the section called \(lqSIMILARITY FORMAT\(rq\&.
 130 .RE
 131 .PP
 132 \fB\-c\fR, \fB\-\-check_names\fR
 133 .RS 4
 134 Use with
 135 \fB\-\-add_similarity\fR
 136 in order to check artists names used in
 137 \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
 138 \fBMPD_HOST\fR
 139 and
 140 \fBMPD_PORT\fR
 141 if set\&.
 142 .br
 143 You can as well give simadb_cli host/port on the command line using respectively
 144 \fB\-S\fR
 145 and
 146 \fB\-P\fR\&.
 147 .RE
 148 .PP
 149 \fB\-\-bl_art=\fR\fB\fIartist_name\fR\fR
 150 .RS 4
 151 Use to black list
 152 \fIartist_name\fR\&. simadb_cli is checking
 153 \fIartist_name\fR
 154 is actually in MPD music library (cf
 155 \fB\-S\fR
 156 and
 157 \fB\-P\fR
 158 options to set MPD host/address if necessary)\&.
 159 .sp
 160 If
 161 \fIartist_name\fR
 162 is not found the script print out a list of matching artists\&.
 163 .RE
 164 .PP
 165 \fB\-\-bl_curr_trk\fR | \fB\-\-bl_curr_art\fR | \fB\-\-bl_curr_alb\fR
 166 .RS 4
 167 Use to black list the currently playing track|artist|album\&. You need access to your MPD server, use
 168 \fB\-S\fR
 169 and
 170 \fB\-P\fR
 171 to set MPD host/address if necessary\&.
 172 .RE
 173 .PP
 174 \fB\-d \fR\fB\fIdb_file\fR\fR, \fB\-\-dbfile=\fR\fB\fIdb_file\fR\fR
 175 .RS 4
 176 Use the specific file
 177 \fIdb_file\fR
 178 as database\&.
 179 .br
 180 Default is too use
 181 \fBXDG_DATA_HOME\fR
 182 (see
 183 the section called \(lqFILES\(rq)\&.
 184 .RE
 185 .PP
 186 \fB\-\-purge_hist\fR
 187 .RS 4
 188 Purge history, you may supply an alternative DB file with \-\-dbfile option\&.
 189 .RE
 190 .PP
 191 \fB\-r\fR, \fB\-\-reciprocal\fR
 192 .RS 4
 193 Use with an editing options in order to edit reciprocal similarity as well\&.
 194 \fB\-\-add_similarity\fR
 195 and
 196 \fB\-\-remove_{artist|similarity}\fR
 197 are supporting reciprocal edition\&.
 198 .sp
 199 \fIN\&.B\fR: this option has to appear after the editing option on the command line\&.
 200 .sp
 201 See
 202 the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
 203 for further information about reciprocity notion\&.
 204 .RE
 205 .PP
 206 \fB\-\-remove_artist=\fR\fB\fIartist\fR\fR
 207 .RS 4
 208 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
 209 \fB\-\-reciprocal\fR
 210 option\&.
 211 .RE
 212 .PP
 213 \fB\-\-remove_bl=\fR\fB\fIrow_id\fR\fR
 214 .RS 4
 215 Use to remove a black list entry\&. To get the row_id to suppress use
 216 \fB\-\-view_bl\fR
 217 option\&.
 218 .RE
 219 .PP
 220 \fB\-\-remove_similarity=\fR\fB\fI"main artist,similar artist"\fR\fR
 221 .RS 4
 222 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\&.
 223 .br
 224 Use of
 225 \fB\-\-reciprocal\fR
 226 is possible here, see
 227 the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq\&.
 228 .sp
 229 This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use
 230 \fB\-\-remove_artist\fR
 231 instead\&.
 232 .RE
 233 .PP
 234 \fB\-v \fR\fB\fI"artist name"\fR\fR, \fB\-\-view_artist=\fR\fB\fI"artist name"\fR\fR
 235 .RS 4
 236 Get entries for
 237 \fI"artist name"\fR
 238 in the data base (print to stdout)\&.
 239 .RE
 240 .PP
 241 \fB\-\-view_bl\fR
 242 .RS 4
 243 Get all entries in the black list\&.
 244 .RE
 245 .PP
 246 \fB\-\-view_all\fR
 247 .RS 4
 248 Get all entries in the data base (print to stdout)\&.
 249 .RE
 250 .PP
 251 \fB\-P \fR\fB\fImpd_port\fR\fR, \fB\-\-port=\fR\fB\fImpd_port\fR\fR
 252 .RS 4
 253 Use the specific port number
 254 \fImpd_port\fR
 255 on MPD server\&. This overrides
 256 \fBMPD_PORT\fR
 257 environment variable\&.
 258 .br
 259 Default is
 260 \fI6600\fR\&.
 261 .RE
 262 .PP
 263 \fB\-S \fR\fB\fImpd_host\fR\fR, \fB\-\-host=\fR\fB\fImpd_host\fR\fR
 264 .RS 4
 265 Use the specific host
 266 \fImpd_host\fR
 267 as MPD server\&.
 268 .br
 269 \fImpd_host\fR
 270 can be an
 271 IP
 272 or a fully qualified domain name as long as your system can resolve it\&. This overrides
 273 \fBMPD_HOST\fR
 274 environment variable\&.
 275 .br
 276 Default is
 277 \fIlocalhost\fR\&.
 278 .RE
 279 .SH "FILES"
 280 .PP
 281 ${XDG_DATA_HOME}/mpd_sima/sima\&.db
 282 .RS 4
 283 SQLite DB file\&. Usually
 284 \fBXDG_DATA_HOME\fR
 285 is set to
 286 ${HOME}/\&.local/share\&.
 287 .RE
 288 .SH "SIMILARITY FORMAT"
 289 .PP
 290 The
 291 \fIsimilarity_string\fR
 292 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
 293 \fImain_art\fR, followed by a list of similar artists which you want to be related to that
 294 \fImain_art\fR, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the
 295 \fImain_art\fR\&. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match\&.
 296 .PP
 297 \fIsimilarity_string\fR
 298 is then to be formatted as follow:
 299 .PP
 300 \fBmain_art,first artist:<score>,second artist:<score>\fR
 301 .PP
 302 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\&.
 303 .PP
 304 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
 305 \fIsimilarity_string\fR
 306 will be the following:
 307 .PP
 308 \fBLed Zeppelin,Tool:25,Audiosalve:20\fR
 309 .PP
 310 See
 311 the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
 312 for more details about how similarities are handled
 313 .SH "A WORD ABOUT SIMA DATA BASE"
 314 .PP
 315 The similarity database is defined from the point of view of a
 316 \fImain artist\fR
 317 which is declared related to a list of
 318 \fIsimilar artists\fR\&. That means when you define
 319 \fImain_art\fR
 320 to be similar to
 321 \fIsim_art A\fR
 322 and
 323 \fIsim_art B\fR
 324 the reciprocal won\*(Aqt be true,
 325 \fIsim_art A\fR
 326 and
 327 \fIsim_art B\fR
 328 are not similar to
 329 \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"\&.
 330 .br
 331 The
 332 \fB\-\-reciprocal\fR
 333 option allows one to add reciprocal relation where
 334 \fIsim_art A\fR
 335 and
 336 \fIsim_art B\fR
 337 become respectively the
 338 \fImain_art\fR\&. Using
 339 \fB\-\-reciprocal\fR
 340 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
 341 \fBmain_art,sim_art A:34,sim_art B:45\fR\&.
 342 .PP
 343 \fBsimadb_cli \-\-reciprocal \-\-add_similarity=main_art,sim_art A:34,sim_art B:45\fR
 344 .PP
 345 main_art similar to sim_art A:34 and sim_art B:45
 346 .br
 347 sim_art A similar to main_art:34
 348 .br
 349 sim_art B similar to main_art:45
 350 .PP
 351 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)\&.
 352 .SH "FEEDBACK/BUGS"
 353 .PP
 354 The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
 355 \m[blue]\fB\%http://kaliko.me/id/\fR\m[]\&.
 356 .PP
 357 XMPP
 358 users are welcome to join the dedicated chat room at
 359 \m[blue]\fBkaliko\&.me@conf\&.azylum\&.org\fR\m[]\&.
 360 .SH "SEE ALSO"
 361 .PP
 362 \fBmpc\fR(1),
 363 \fBmpd\fR(1)
 364 .PP
 365 /usr/share/doc/mpd\-sima/
 366 .SH "AUTHOR"
 367 .PP
 368 \fBJack Kaliko\fR <\&kaliko@azylum\&.org\&>
 369 .RS 4
 370 Wrote this man page and is currently leading MPD_sima project\&.
 371 .RE
 372 .SH "COPYRIGHT"
 373 .br
 374 Copyright \(co 2009-2014 Jack Kaliko
 375 .br
 376 .PP
 377 This manual page was written for the Debian system (and may be used by others)\&.
 378 .PP
 379 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\&.
 380 .PP
 381 On Debian systems, the complete text of the GNU General Public License can be found in
 382 /usr/share/common\-licenses/GPL\&.
 383 .sp