larigira/doc/source/install.rst

Installation
=============

Installing larigira is quite simple. You can install latest version from PyPI
using ``pip install larigira``. Or you can ``git clone
https://git.lattuga.net/boyska/larigira.git`` and run ``python setup.py install``.
As always, the usage of a virtualenv is recommended.

Python greater or equal than 3.4 is supported.

Configuration
---------------

larigira use MPD in a peculiar way. It can use mpd internal library, but it can
also work with "regular" local files, outside of the library. To do so,
however, it requires you to connect to MPD through the UNIX socket instead of
the TCP port.

So how to create this setup?
inside ``~/.mpdconf``, add the following line::

    bind_to_address "~/.mpd/socket"

For larigira, you need to set the ``MPD_HOST`` environment variable to
``$HOME/.mpd/socket``. If you don't do this, you'll find many lines like these in the logs::

    15:37:10|ERROR[Player:93] Cannot insert song file:///tmp/larigira.1002/audiogen-randomdir-8eoklcee.mp3
    Traceback (most recent call last):
      File "/home/user/my/ror/larigira/larigira/mpc.py", line 91, in enqueue
        mpd_client.addid(uri, insert_pos)
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 629, in decorator
        return wrapper(self, name, args, bound_decorator(self, returnValue))
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 254, in _execute
        return retval()
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 623, in decorator
        return function(self, *args, **kwargs)
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 384, in _fetch_item
        pairs = list(self._read_pairs())
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 311, in _read_pairs
        pair = self._read_pair(separator)
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 302, in _read_pair
        line = self._read_line()
      File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/mpd.py", line 291, in _read_line
        raise CommandError(error)
    mpd.CommandError: [400] {addid} Access denied



Options
~~~~~~~~~~

Options will be presented "grouped" to make them more easily understandable. This is just for documentation
purposes, they don't need to be divided in the configuration.

Options values are assumed to be JSON formatted. For strings and numbers, this makes no difference. For
booleans, this means that the only valid values are ``true`` and ``false``. For lists and objects, read a JSON
reference or learn from examples.

To set an option, you must set an environment variable with the name ``LARIGIRA_OPTIONNAME``.

General
^^^^^^^^^^^^^

MPD_HOST
    This option let you set the way to connect to your MPD server. Please remind that for complete larigira
    operatoin you should set the path to a UNIX domain socket, not ``localhost``
MPD_PORT
    If you are not using a socket, but a TCP address (which is *not* suggested), this is how you can specify the
    port.
DEBUG
    you can set it to ``true`` or ``false``. Defaults to ``false``. Will enable extremely verbose output.
TMPDIR
    The base for larigira tmpdir. Please note that larigira will create its own directory inside this
    temporary directory. This defaults to the system-wide ``$TMPDIR``, or to ``/tmp/`` if not ``TMPDIR`` is
    not set. Choose it wisely, keeping in mind that in this directory a lot of cache files will be stored, and
    could therefore require hundreds of MB.
UMASK
    Umask affects created files permissions. This is important if you want to pass files to a MPD instance
    that is running with a different users. There is no default umask, so that you can apply umask via your
    standard system tools.

Events
^^^^^^^^^

CONTINOUS_AUDIOSPEC
    when the playlist is too short, larigira picks something new. How? this is controlled by this variable.
    This variable should be set to the JSON representation of an audiospec describing how to generate new
    audios. The default is ``{"kind": "mpd", "howmany": 1}``, which picks a random song from MPD library. You could, for example, change it to:

    - ``{ "kind": "randomdir", "paths": ["/var/music"], "howmany": 5}``
      to pick files from a specified directory, ignoring MPD library completely. Here, ``howmany`` is set to 5 for performance sake
    - ``{"kind": "mpd", "howmany": 10, "prefix": "background"}``
      if you want to use the MPD library, but only use one of its subdirectories.
      Since using ``mpd`` with a ``prefix`` can be slow, so this is setting ``howmany`` to 10 to
      gain some performance

    Yes, there's a typo in the name, but I'll keep it like this for compatibility
EVENT_FILTERS
    See :doc:`eventfilters`
LOG_CONFIG
    Path to an INI-formatted file to configure logging. See `python logging documentation
    <https://docs.python.org/2/library/logging.config.html#logging-config-dictschema>`_
MPD_ENFORCE_ALWAYS_PLAYING
    If this is set to 1, larigira will make sure that MPD is always playing. This means that you can't stop
    mpd, not even manually running ``mpd stop``. That's probably useful for radios in which mpd is meant to be
    run unattended. Default: 0

Internals
^^^^^^^^^^^^^^

These are options you probably don't want to change, unless you want to debug

CACHING_TIME
    larigira needs an estimate on how much time an audiogenerator will need. This option sets this. The
    default is 10 (seconds). If you set it too low, the events will be scheduled with some delay
CHECK_SECS
    The interval (in seconds) that will trigger a check for the playlist length. Set it too low, and you'll be
    consuming resource with no usage. Set it too high and you might miss some moment of playlist shortage.
    The default is 20
EVENT_TICK_SECS
    The interval (in seconds) that will trigger a check on the events to see if there's something to schedule.
    This also determines how much time in advance you can add/delete/change an event for the change to be
    effective.
SCRIPTS_PATH
    This options controls the path where scripts will be looked for. This is a single path, not a list. The
    default is ``$XDG_CONFIG_DIR/larigira/scripts/`` which might boil down to
    ``$HOME/.config/larigira/scripts/`` 
DB_URI
    The path to the events database. The default is ``$XDG_CONFIG_DIR/larigira/db.json``
MPD_WAIT_START
    When larigira starts, it will try to connect to MPD. If MPD doesn't look ready, larigira will wait until
    it is. This makes larigira depend on MPD. However, this also makes it easier to run larigira at boot
    without complex dependency on MPD to be fully started and listening. You can disable this behavior setting
    this to ``false``
MPD_WAIT_START_RETRYSECS
    The behavior described for the previous option requires polling. This variable lets you customize the
    polling frequency, expressed in seconds. The default is ``5``.

Web interface
^^^^^^^^^^^^^^^^

HTTP_ADDRESS
   The address that the HTTP interface will listen to; defaults to `0.0.0.0`
HTTP_PORT
   The port that the HTTP interface will listen to; defaults to `5000`
FILE_PATH_SUGGESTION
    A list of paths. Those paths will be scanned for suggestions in audiogenerator forms.
UI_CALENDAR_FREQUENCY_THRESHOLD
    The "calendar" view in the UI will omit events that occur too frequently, to avoid noise. This variable is
    the threshold, in seconds. Defaults to 4 hours.
BOOTSTRAP_SERVE_LOCAL
    larigira can serve every js and css by itself. However, you might like to make the user download standard
    libraries from CDNs. In that case, set this variable to ``false``.

Localization
++++++++++++++

Localization support in larigira is basic to say the least. However, something can be done.
Dates (not consistently! sigh) are formatted according to locale.

LARIGIRA_BABEL_DEFAULT_LOCALE
    The short language code you want to use when the user doesn't specify any. Values are in the form
    ``it``, ``en``, ``en-US``...
LARIGIRA_UI_CALENDAR_DATE_FMT
    The format to show in ``/db/calendar`` page. The format is specified `here <http://babel.pocoo.org/en/latest/dates.html>`_. Default is ``medium``.

    As an example, ``eee dd LLL`` will show ``Sun 10 Mar`` for english, and ``dom 10 mar`` for italian.

Debug and development
^^^^^^^^^^^^^^^^^^^^^^^

REMOVE_UNUSED_FILES
    By default, larigira removes the file it generates, as soon as they are no longer in MPD playlist. There is no good reason to change this behavior, unless you need to debug what's going on. For example, if you want to inspect files. Set this to `false` keep everything.