larigira/doc/source/audiogenerators.rst

Audiogenerators
===============

mpd
---------

picks ``howmany`` song randomly from your mpd library. It follows this
strategy: it picks ``howmany`` artists from your MPD library, then picks a random song for each one

if you specify a ``prefix``, then only files inside the ``prefix`` directory
will be picked.

randomdir
----------

Given a directory ``path``, scan it recursively, then picks ``howmany`` random
files. Only files whose filename ends in mp3/ogg/oga/wav are considered . Files are copied to ``TMPDIR`` before being returned.

static
---------

That simple: every element in ``paths`` is returned. Before doing so, they are
copied to ``TMPDIR``.

http
---------

Given a sequence of ``urls``, downloads each one and enqueue it.

This is **not** suitable for streams (a fundamental limitation of larigira),
only for audio files.

mostrecent
-------------

It is similar to randomdir, but instead of picking randomly, picks the most
recent file (according to the ctime).

podcast
------------

This is probably the most powerful generator that comes included with
``larigira``. To use this generator, you would need to have a valid podcast
URL. Beware, here the world *podcast* refer to its very specific meaning of
an xml-based format which resembles a RSS feed but has more media-specific
entities. See `this specification
<https://github.com/simplepie/simplepie-ng/wiki/Spec:-iTunes-Podcast-RSS>`_ for
more technical details.

So, if you have a valid podcast URL, larigira can look at it, extract audios,
 download and play the most recent one. Here are some typical usecases for this:
 * You want to play replica based on what you host on your radio's website.
 * You want to play some audio from some other radio (or other kind of podcast
   source)

The podcast form has many many options, but I promise you that 90% of the cases
are easily solved using ONLY the first option: enter the URL of the podcast
and... it works!

So, what are all the other options for? Well, to cover some other use cases.

For example, let's say that at night you want to play a *random* show (not the
last one, which is the default) that happened on your radio. Then you can
change the "sort by" to be "random". Easy, right?

Another typical usecase is selecting an audio that has a duration which "fits"
with the schedule of your radio: not too long and not too short. You can do
that with the "min len" and "max len" fields. For example, setting a `min_len`
of `30min` and `max_len` of `1h15m` you can avoid picking flash news (too
short) and very long shows.

You can do many other things with its options, but I left those to your
immagination. Let's just clarify the workflow:

 * the podcast URL is fetched and audio information is retrieved
 * filter: audios are filtered by min/max length
 * sort: audios are sorted according to `sort_by` and `reverse`
 * select: the n-th episode is fetched, according to `start` field


script
--------

see :doc:`audiogenerators-write`