extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
+ 'sphinx.ext.intersphinx',
]
# Add any paths that contain templates here, relative to this directory.
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
+
+intersphinx_mapping = {'https://docs.python.org/': None}
Track object Documentation
==========================
+.. autodata:: SEPARATOR
+
.. automodule:: sima.lib.track
:members:
Generic class and helper function
---------------------------------
-.. autoclass:: sima.lib.meta.Meta(name, mbid=None, **kwargs)
+.. autoclass:: sima.lib.meta.Meta
:members:
:undoc-members:
Derived objects
---------------
-.. autoclass:: sima.lib.meta.Artist(name, mbid=None, albumartist=None, musicbrainz_artistid=None, musicbrainz_albumartistid=None)
+.. autoclass:: sima.lib.meta.Artist(name, mbid=None, musicbrainz_artistid=None, albumartist=None)
+ :show-inheritance:
+
+.. autoclass:: sima.lib.meta.Album
:show-inheritance:
--- /dev/null
+Database managment module
+=========================
+
+.. automodule:: sima.lib.simadb
+ :members:
+ :undoc-members:
+
+.. autodata:: sima.lib.simadb.__HIST_DURATION__
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-MPD_sima's documentation!
-=========================
+#########################
+MPD_sima's documentation
+#########################
+MPD_sima is meant to **auto-magically queue** tracks in MPD_, it is a non interactive client for MPD_.
-Development documentation
--------------------------
+Actually there is no magic involved, it relies on music metadata found in music
+files tags and external information providers such as last.fm_. Then to use
+MPD_sima (or any advanced music players, MPD_ among them), you need to ensure
+your library is correctly tagged (see :ref:`metadata-convention`).
+
+The default setting for MPD_sima is to queue similar artists thanks to last.fm_
+suggestions but there are other possibilities.
+
+**To queue tracks from similar artists, start playing a track in MPD then launch MPD_sima:**
+
+.. code-block:: sh
-**Contents:**
+ # runs against localhost MPD (or whatever is set in MPD_HOST/MPD_PORT)
+ mpd-sima
+
+ # runs against a specific MPD server
+ mpd-sima --host mpd.example.org
+
+#####################
+User's documentation
+#####################
+
+.. toctree::
+ :maxdepth: 2
+ :glob:
+
+ user/*
+
+
+##########################
+Development documentation
+##########################
.. toctree::
:maxdepth: 2
dev/meta
dev/lastfm
dev/cache
+ dev/simadb
Indices and tables
* :ref:`modindex`
* :ref:`search`
+
+.. include:: links.rst
+
+.. vim: spell spelllang=en
--- /dev/null
+.. _picard: https://picard.musicbrainz.org/
+.. _beets: https://beets.io/
+.. _mpd: https://musicpd.org/
+.. _MusicBrainzIDs: https://musicbrainz.org/doc/MusicBrainz_Identifier
+.. _MBIDs: https://musicbrainz.org/doc/MusicBrainz_Identifier
+.. _MusicBrainz: https://musicbrainz.org
+.. _`ID3 tags`: https://en.wikipedia.org/wiki/ID3
+.. _last.fm: https://www.last.fm/
--- /dev/null
+Installation
+============
+
+\*nix distributions
+-------------------
+
+Use your package manager, there are packages for Debian (and probably derivatives) and Arch via AUR.
+
+
+Python virtualenv
+-----------------
+
+.. code:: bash
+
+ # create venv
+ python -m venv mpd_sima-venv
+ # activate
+ . ./mpd_sima-venv/bin/activate
+ # Install the application
+ pip install MPD_sima
+ # Print help message
+ mpd-sima --help
+
+From Source
+-----------
+
+Virtualenv installation from source:
+
+Run ``python ./vinstall.py`` from the source to generate the python virtualenv and install requirements.
+
+It will setup a virtualenv within a "venv" directory (same level as vinstall.py file). It should also write a shell wrapper to run mpd-sima within the virtualenv.
+
+
+.. code:: bash
+
+ # Clone master branch
+ git clone -b master git@gitlab.com:kaliko/sima.git
+ # setup virtualenv
+ python ./vinstall.py
+ ./vmpd-sima --help
+
+To restart from scratch or pull latest changes
+
+.. code:: bash
+
+ # Get into the local git repo (here sima directory)
+ cd sima
+ # Remove virtualenv
+ rm -rf ./venv
+ # Fetch and merge latest changes
+ git pull
+ # setup virtualenv
+ python ./vinstall.py
+ ./vmpd-sima --help
+
+
+.. vim: spell spelllang=en
--- /dev/null
+Configuration examples
+======================
+
+Configuration location is ``${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg`` usually ``${XDG_CONFIG_HOME}`` is in ``${HOME}/.config/``.
+
+
+Default configuration
+---------------------
+
+MPD_sima runs without explicit configuration as long as your MPD server is easy
+to discover (``localhost:6600`` or exposed via environment variables ``MPD_HOST``/``MPD_PORT``).
+
+The default configuration is to run in *track mode* with suggestions from last.fm:
+
+.. code:: ini
+
+ [MPD]
+ # Change MPD server here
+ #host = mpdserver.example.org
+ #port = 6600
+
+ [sima]
+ internal = Crop, Lastfm, Random
+ history_duration = 8
+ queue_length = 2
+
+ [crop]
+ consume = 10
+
+ [lastfm]
+ queue_mode = track
+ single_album = False
+ track_to_add = 1
+
+Album mode
+^^^^^^^^^^
+
+One of the first request added to MPD_sima was album mode. It allows to queue whole album instead of single tracks.
+
+Here the configuration keeps the queue plugin *Lastfm* but configure it to queue albums (``queue_mode = album``) and ask for 2 albums to be add.
+
+The configuration of MPD_sima in ``sima`` section is also modified for ``queue_length``. The value of 10 is to trigger album queueing when there are 10 tracks or less in the queue.
+
+.. code:: ini
+
+ [MPD]
+ # Change MPD server here
+ #host = mpdserver.example.org
+ #port = 6600
+
+ [sima]
+ internal = Crop, Lastfm, Random
+ history_duration = 8
+ queue_length = 10
+
+ [crop]
+ consume = 10
+
+ [lastfm]
+ queue_mode = album
+ album_to_add = 2
+
+
+Offline auto-queuing
+--------------------
+
+
+.. vim: spell spelllang=en
--- /dev/null
+.. _metadata-convention:
+
+Music library metadata convention
+=================================
+
+In order to choose which tracks to add, your music library needs to follow some
+conventions regarding **metadata** [1]_. Files in your library should be tagged
+with the metadata best describing the music file.
+
+Be aware that the benefit from a well tagged library goes far beyond the use of
+MPD_sima alone. Any piece of software will take advantage of a well tagged
+library, especially music players. If you already use MPD_ as a player, you are
+already well aware of it.
+
+A minimal set of tags required for MPD_sima to work would be ``ARTIST``, ``ALBUM``, ``TITLE``, but in order to work properly and with all plugins a more complete tag set is recommended.
+
+MPD_sima is actually expecting: ``ARTIST``, ``ALBUM``, ``TITLE``, ``ALBUMARTIST``,
+``GENRE`` and some MusicBrainzIDs_ [2]_ as well: ``MUSICBRAINZ_ARTISTID``,
+``MUSICBRAINZ_ALBUMID`` and ``MUSICBRAINZ_ALBUMARTISTID``.
+
+There are very good tools to (auto)tag you music library, picard_ is highly
+recommended, beets_ is also a good alternative. Actually any piece of software
+tagging your files with the most common tags (albumartist especially) and
+MusicBrainzIDs_ [3]_ should be fine.
+
+
+
+.. [1] commonly named tags or `ID3 tags`_ for MP3, but most audio format have some metadata features.
+
+.. [2] MusicBrainz_ provides a reliable and unambiguous form of music identification; this music identification is performed through the use of MusicBrainz Identifiers (MBIDs_).
+.. [3] cf 2_
+
+.. include:: ../links.rst
+
+.. vim: spell spelllang=en
home / dev / repositories / mpd-sima.git / commitdiff