'\" t
.\"     Title: mpd-sima.cfg
.\"    Author: Jack Kaliko <efrim@azylum.org>
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 09/26/2012
.\"    Manual: mpd-sima User Manual
.\"    Source: mpd-sima
.\"  Language: English
.\"
.TH "MPD\-SIMA\&.CFG" "5" "09/26/2012" "mpd-sima" "mpd-sima User Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mpd-sima.cfg \- mpd\-sima will try to maintain some titles ahead in your play list following different policies\&. This manual document the configuration file for mpd\-sima\&.
.SH "DESCRIPTION"
.PP
This manual page documents briefly
\fBmpd\-sima\fR
configuration options available in user configuration file (see
the section called \(lqFILES\(rq)\&.
.SH "CONFIGURATION FILE"
.PP
The configuration file consists of sections, led by a
\fB[section]\fR
header and followed by
\fBname:\ \&value\fR
entries, with continuations in the style of RFC 822 (see section 3\&.1\&.1, \(lqLONG HEADER FIELDS\(rq);
\fBname=value\fR
is also accepted\&. Lines beginning with
\fI\*(Aq#\*(Aq\fR
or
\fI\*(Aq;\*(Aq\fR
are ignored and may be used to provide comments\&.
.PP
The default values are used in the options lists below\&.
.SS "MPD section"
.PP
This section is meant to configure MPD access, MPD host address / port and password if necessary\&.
.PP
\fB[MPD]\fR
.RS 4
.RE
.PP
\fBhost=\fR\fIlocalhost\fR
.RS 4
Set MPD host\&. Use IP or FQDN\&.
.RE
.PP
\fBport=\fR\fI6600\fR
.RS 4
Set host port to access MPD to\&.
.RE
.PP
\fBpassword=\fR\fIfalse\fR
.RS 4
Set MPD password to use\&. Do not use this option if you don\*(Aqt have enabled password protected access on your MPD server\&.
.RE
.SS "log section"
.PP
Configure logging\&.
.PP
\fB[log]\fR
.RS 4
.RE
.PP
\fBverbosity=\fR\fIinfo\fR
.RS 4
Logging verbosity among
\fIdebug\fR,
\fIinfo\fR,
\fIwarning\fR,
\fIerror\fR\&.
.RE
.SS "sima section"
.PP
This section allows you to tweak mpd\-sima behaviour such as how many tracks to add and/or what queue mode you want
etc\&.\&.
.PP
\fB[sima]\fR
.RS 4
.RE
.PP
\fBqueue_mode=\fR\fItrack\fR
.RS 4
Queue mode to use among
\fItrack\fR,
\fItop\fR
and
\fIalbum\fR
(see
the section called \(lqQUEUE MODES\(rq
for info about queue modes)\&.
.RE
.PP
\fBsimilarity=\fR\fI15\fR
.RS 4
Similarity value as a percentage, use to filter similar artists results\&.
.br

The value of
\fBsimilarity\fR
is used to filter similar artists list from database (last\&.fm and user db)\&.
.RE
.PP
\fBdynamic=\fR\fI10\fR
.RS 4
Dynamic value as an integer\&. Sets how many similar artists to retrieve from local music library\&.
.br

mpd\-sima will try to gather at most
\fBdynamic\fR
artists from local media library at least
\fBsimilarity\fR% similar\&.
.br

If
\fBdynamic\fR
is zero, then mpd\-sima gathers all artists from similar artists list also present in local library and at least
\fBsimilarity\fR% similar\&.
.RE
.PP
\fBuser_db=\fR\fIfalse\fR
.RS 4
Look for user defined similarities in user data base\&.
.RE
.PP
\fBhistory_duration=\fR\fI8\fR
.RS 4
How far to look back in history to avoid to play twice the same track/title (duration in hours)\&.
.RE
.PP
\fBconsume=\fR\fI0\fR
.RS 4
How many played tracks to keep in the play list\&. Allow to maintain a fixed length play list\&. Set to 0 to keep all played tracks\&.
.RE
.PP
\fBsingle_album=\fR\fIfalse\fR
.RS 4
Prevent from queueing a track from the same album (it often happens with OST)\&.
.br

Only relevant in "track" queue mode\&.
.RE
.PP
\fBcheck_new_version=\fR\fIfalse\fR
.RS 4
Checks the forge for new version of MPD_sima\&.
.RE
.PP
The following options are still part of
\fBsima\fR
section but you usually do not need to change them\&.
.PP
\fBqueue_length=\fR\fI1\fR
.RS 4
This value triggers queue process if the play list length is less than specified queue_length\&.
.RE
.PP
\fBtrack_to_add=\fR\fI1\fR
.RS 4
How many track(s) to add\&. Only relevant in
\fBtop\fR
and
\fBtrack\fR
queue modes\&.
.RE
.PP
\fBalbum_to_add=\fR\fI1\fR
.RS 4
How many album(s) to add\&. Only relevant in
\fBalbum\fR
queue modes\&.
.RE
.SH "QUEUE MODES"
.PP
mpd\-sima offers different queue modes\&. All of them pick up tracks from artists similar to the one currently played\&.
.PP
mpd\-sima tries preferably to chose among unplayed artists or at least not recently played artist\&. Concerning track and album queue modes titles are chosen purely at random among unplayed tracks\&.
.PP
\fBtrack\fR
.RS 4
Queue a similar track chosen at random from a similar artist\&.
.RE
.PP
\fBtop\fR
.RS 4
Queue a track from a similar artist, chosen among "top tracks" according to last\&.fm data mining\&.
.RE
.PP
\fBalbum\fR
.RS 4
Queue a whole album chosen at random from a similar artist\&.
.sp
\fINota Bene:\fR
.br

Due to the track point of view of database build upon tracks tags an album lookup for a specific artist will return albums as soon as this artist appears in a single track of the album\&.
.br

For instance looking for album from "The Velvet Underground" will fetch "Last Days" and "Juno" OSTs because the band appears on the soundtrack of these two movies\&.
.br

A solution is for you to set AlbumArtists tag to something different than the actual artist of the track\&. For compilations, OSTs etc\&. a strong convention is to use "Various Artists" for this tag\&.
.sp
mpd\-sima is currently looking for AlbumArtists tags and avoid album where this tag is set with "Various Artists"\&. If a single track within an album is found with AlbumArtists:"Various Artists" the complete album is skipped and won\*(Aqt be queued\&.
.br

It is planned to allow users to set the values of AlbumArtists tag triggering this behaviour\&. cf\&. feature request #2085 on the tracker\&.
.RE
.SH "FILES"
.PP
Unless you override it mpd\-sima will try to read the configuration file name
mpd_sima\&.cfg
in the standard location within
\fBXDG_CONFIG_HOME\fR\&.
.PP
${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
.RS 4
The per\-user configuration file\&. Usually
\fBXDG_CONFIG_HOME\fR
is set to
${HOME}/\&.config\&.
.RE
.SH "EXAMPLES"
.SS "Album queue mode\&."
.PP
Here is an example of album queue configuration\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[MPD]
host=example\&.org
port=8000

[sima]
queue_mode = album
consume = 30 # keep 30 played tracks in playlist
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.PP
The upstream
BTS
can be found at
\m[blue]\fB\%http://codingteam.net/project/sima/bugs\fR\m[]\&.
.SH "FEEDBACK"
.PP
The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback on the forge, via the upstream
BTS, the forum or the chat room, all available on the forge at
\m[blue]\fB\%http://codingteam.net/project/sima\fR\m[]\&.
.PP
XMPP
users are welcome to join the dedicated chat room at
\m[blue]\fBsima@conference\&.codingteam\&.net\fR\m[]\&.
.SH "SEE ALSO"
.PP
\fBmpd-sima\fR(1),
\fBsimadb_cli\fR(1)
.PP

/usr/share/doc/mpd\-sima/
.SH "AUTHOR"
.PP
\fBJack Kaliko\fR <\&efrim@azylum\&.org\&>
.RS 4
Wrote this man page and is currently leading MPD_sima project\&.
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2009-2012 Jack Kaliko
.br
.PP
This manual page was written for the Debian system (and may be used by others)\&.
.PP
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\&.
.PP
On Debian systems, the complete text of the GNU General Public License can be found in
/usr/share/common\-licenses/GPL\&.
.sp