Installing larigira is quite simple. You can install latest version from PyPI using pip install larigira. Or you can git clone and run python install. As always, the usage of a virtualenv is recommended.

Python greater or equal than 3.4 is supported.


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/", 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/", 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/", line 254, in _execute
    return retval()
  File "/home/user/.virtualenvs/larigira3/lib/python3.5/site-packages/python_mpd2-0.5.5-py3.5.egg/", 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/", 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/", 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/", 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/", line 291, in _read_line
    raise CommandError(error)
mpd.CommandError: [400] {addid} Access denied


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.


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
If you are not using a socket, but a TCP address (which is not suggested), this is how you can specify the port.
you can set it to true or false. Defaults to false.
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.


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}. You could, for example, change it to { "kind": "randomdir", "paths": ["/var/music"], "howmany": 10} or to {"kind": "mpd", "howmany": 5, "prefix": "background"}.
See EventFilters
Path to an INI-formatted file to configure logging. See python logging documentation


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

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
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
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.
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/
The path to the events database. The default is $XDG_CONFIG_DIR/larigira/db.json
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
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

A list of paths. Those paths will be scanned for suggestions in audiogenerator forms.
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.
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 support in larigira is basic to say the least. However, something can be done. Dates (not consistently! sigh) are formatted according to 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

The format to show in /db/calendar page. The format is specified here. Default is medium.

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