- MPD_SIMA -


Follow news and release announcement on CodingTeam forge at:
	<http://codingteam.net/project/sima/news>

 RUNNING
-=-=-=-=-
Runs with python >= 2.6 and < 3.
No installation nor compilation necessary.
Make sure to satisfy dependency (currently python-mpd only).

Archlinux and Debian users might use MPD_sima package for their
distributions, cf. <http://codingteam.net/project/sima/doc/DownLoad>.

A Makefile is also available.

Otherwise follow these instructions:

 0. Install mpd python library (cf. DEPENDENCIES below).
 
 1. Default is to look for MPD server at localhost:6600, use
    configuration file or environment variables to use your own
    settings.
 
 2. Pray Gaïa and A.M. Turing.

 3. Run MPD_sima by launching either the shell or python script.
    The shell script is just provided as an example, functional though.
    * Shell
    		sh ./launch.sh
    * Python
    		python ./src/mpd_sima --daemon --pid=/path/to/my_PID_file.pid --log=/path/to/file.log
    	or
    		# using MPD env. var and log output to stdout/stderr
    		MPD_HOST="password@host" ./src/mpd_sima
    * HELP
    		python ./src/mpd_sima --help

 4. Lay back and enjoy.
 
 5. Well… refer to next section to report bugs, request features…


 DEPENDENCIES
-=-=-=-=-=-=-=-
 * python-mpd >= 0.3
      http://pypi.python.org/pypi/python-mpd/
      Git repo:
      http://jatreuman.indefero.net/p/python-mpd/


 CONFIGURATION
-=-=-=-=-=-=-=-

You may want to change default settings.

File:   $XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg
Usually $XDG_CONFIG_HOME refers to $HOME/.config
Conf files examples are provided in ./doc/examples/

These are the defaults for main settings.
__________________________________________________________________

[MPD]
host = localhost
port = 6600
# Do not set if you don't use a password
#password = False

[sima]
# Queue mode
# Possible values:
#	track : Will queue tracks from similar artists (default).
#	album : Will queue whole album from similar artists.
#	top   : Will queue top tracks from similar artists.
queue_mode = track
# Similarity value to use filtering similar artists (as a percentage).
similarity = 15
________________________________________________[ mpd_sima.cfg ]__

If you do not need password to access MPD either remove the option in
the conf file or set it up to "false".

Some more settings are available, though, for "advanced use",
everything should be just fine with the main settings above.


 DESCRIPTION - advanced use
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
The commented file <all_settings.cfg> (in examples directory)
present all defaults settings available in configuration file. Optional
sections give you some more control over MPD_sima core behaviour.  Here
follows a quick description of MPD_sima working behaviour.


MPD_sima will add tracks in your playlist following suggestions from
last.fm.  It will try to add tracks when playlist is getting short.

The amount of track added and length of the playlist triggering it can
be defined in the configuration file (mpd_sima.cfg) otherwise the
default values will be used:

track_to_add = 1
album_to_add = 1 
queue_length = 1

MPD_sima is controlling MPD's state via idle command (cf. MPD protocol
documentation). Any change in MPD state triggers a control of the
playlist state, queue length and add new tracks if needed.

For more options see <all_settings.cfg> (in examples directory).


HISTORY
You may set how long ago you want MPD_sima to look back in
play history using "history_duration". The default value is 8 hours and
MPD_sima stores a week of play history at max (hence 7*24 = 168 hours).
 N.B.
 Take notice that the history of played tracks is used to avoid to play
 twice the same title. That means, it may end up you do not have any more
 unplayed tracks for some artists if you run MPD_sima for a long time
 and/or set up "history_duration" to high.

SQLITE USERDB
With MPD_sima 0.6.0 appeared the new SQLite database as a replacement of
the previous text based user database. A client has been written to allow
users to edit SQLite DB, refer to simadb_cli documentation for further
details.

SQLITE file.
This file is saved to standard directory $XDG_DATA_HOME, if not set
the default $HOME/.local/share/ is used.


 FILES
-=-=-=-

conf      $XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg
          $HOME/.config/mpd_sima/mpd_sima.cfg

DB file   $XDG_CONFIG_HOME/mpd_sima/sima.db
          $HOME/.local/share/mpd_sima/sima.db


 FEED BACK
-=-=-=-=-=-
Please report any suggestions, feed back, patch, bug through the forge
kindly hosting the project: http://sima.codingteam.net/

Do not hesitate to contact the author to send him pizza, post cards,
music or spliff at <efrim@azylum.org>.

Donate: donation will benefit all people/entities involved in MPD_sima.
Coding Team forge and project leaders, contributors.
I will donate to MPD project if I manage to find a way to avoid
sourceforge to do so.


 BUGS
-=-=-=-
Probably enough, waiting for you to fill a report on ;)
Drop an email/message to the author or fill a report:
http://codingteam.net/project/sima/bugs


-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 vim: textwidth=72 ai fileencoding=utf-8
$Id$