Playing files is the most common way to build an audio stream. In liquidsoap, files are accessed through requests, which combine the retrieval of a possibly remote file, and its decoding.
Liquidsoap provides several operators for playing requests:
single, playlist and playlist.safe,
request.dynamic, request.queue and request.equeue.
In a few cases (single with a local file,
or playlist.safe) a request operator will know
that it can always get a ready request instantaneously.
It will then be infallible.
Otherwise, it will have a queue of requests ready
to be played (local files with a valid content), and will
feed this queue in the background.
This process is described here.
Common parameters
Queued request sources maintain an estimated remaining time,
and trigger a new request resolution when this remaining time
goes below their length parameter.
The estimation is based on the duration of files prepared in the queue,
and the estimated remaining time in the currently playing file.
Precise file durations being expensive to compute, they are not
forced: if a duration is provided in the metadata it shall be used,
otherwise the default_length is assumed.
For example, with the default 10 seconds of wanted queue length, the operator will only prepare a new file 10 seconds before the end of the current one.
Up to liquidsoap 0.9.1, the estimated remaining time
in the current track was not taken into account.
With this behavior, each request-based source would keep at least
one song in queue, which was sometimes inconvenient.
This behavior can be restored by passing conservative=true,
which is useful in some cases:
it helps to ensure that a song will be ready in case of skip;
generally, it prepares things more in advance, which is good when
resolution is long (e.g., heavily loaded server, remote files).
Request.dynamic
This source takes a custom function for creating its new requests.
This function, of type ()->request,
can for example call an external program.
To create the request, the function will have
to use the request.create function which has type
(string,?indicators:[string]).
The first string is the initial URI of the request,
which is resolved to get an audio file.
The second argument can be used to directly specify the first row of URIs
(see the page about requests for more details),
in which case the initial URI is just here for naming,
and the resolving process will try your list of indicators one by one
until a valid audio file is obtained.
An example that takes the output of an external script as an URI to create a new request can be:
def my_request_function() =
# Get the first line of my external process
result =
list.hd(
get_process_lines("my_script my_params"))
# Create and return a request using this result
request.create(result)
end
# Create the source
s = request.dynamic(my_request_function)
Queues
Liquidsoap features two sources which provide request queues that
can be directly manipulated by the user, via the server interface:
request.queue and request.equeue.
The former is a queued source where you can only push new requests,
while the later can be edited.
Both operators actually deal with two queues: primary and secondary queues. The secondary queue is user-controlled. The primary queue is the one that all queued request sources have, its behavior is the same as described above, and it cannot be changed in any way by the user. Requests added to the secondary queue sit there until the feeding process gets them and attempts to prepare them and put them in the primary queue. You can set how many requests will be in that primary queue by tweaking the common parameters of all queued request sources.
The two sources are controlled via the command server.
They both feature commands for looking up the queues,
queuing new requests, and the equeue operator also allows
removal and exchange of requests in the secondary queue.