NAME

Audio::Liquidsoap - Interact with the Liquidsoap telnet interface.

SYNOPSIS

use Audio::Liquidsoap;

my $ls = Audio::Liquidsoap.new;

say "Connected to liquidsoap { $ls.version } up since { DateTime.new($ls.uptime) }";


...

More expansive examples can be found in the examples directory

DESCRIPTION

This provides a mechanism to interact with the Liquidsoap media toolkit and possibly build radio applications with it.

It provides abstractions to interact with the defined Inputs, Outputs, Queues, Playlists and Requests to the extent allowed by the "telnet" interface of liquidsoap. There is also a generalised mechanism for sending arbitrary commands to the server, such as those that may have been provided by the liquidsoap server.register function. However it should be borne in mind that you will almost certainly need to still actually to write some liquidsoap script in order to declare the things to manipulate.

Audio::Liquidsoap

class Audio::Liquidsoap

This provides the primary interface for interacting with the liquidsoap instance and will acquire and construct the details of all the other objects as necessary.

method new

method new(Str :$socket-path, Int :$port = 1234, Str :$host = 'localhost', Client :$client)

This is the constructor of the class, the host and port or socket path of the liquidsoap command interface can be provided and default to 1234 and 'localhost'. A client object will be created as necessary but one can be provided if for instance one is required with different capabilities.

attribute client

This is the Audio::Liquidsoap::Client that will be created as required. The primary interface command is delegated to this class, so you probably don't need to worry about it unless you have special requirements.

attribute port

This is the port that the liquidsoap command interface is using, it will default to the liquidsoap default of 1234 and will typically be set in the constructor.

attribute host

This is the host that the liquidsoap command interface can be found on. It defaults to 'localhost'. Typically however a liquidsoap instance will only bind to the loopback interface for security reasons so it is unlikely that you will need to change it.

attribute socket-path

If provided this will be the path to a Unix domain socket which will be used to communicate with the Liquidsoap server rather than the TCP "telnet" socket. This should be preferred to using a TCP socket in a production environment as it is easier to secure (by adjusting the permissions on the socket file.)

method command

method command (Str $command, *@args)

This sends the command $command to liquidsoap command interface and returns the response verbatim (except the output terminator) If the response indicates there was an error an exception (X::Command) will be thrown. Any additional arguments given will be given to the command as-is (separated by spaces.)

This is actually a delegation from the client but this should be the preferred interface for running ad-hoc commands on the server (such as those added by server.register

method uptime

method uptime ( --> Duration)

This returns a Duration object indicating how long the liquidsoap instance has been running.

method version

method version ( --> Version)

This returns a Version object that is based on the version string of the liquidsoap.

method list

method list ()

This returns a list of the lines returned by the list command of the liquidsoap. Internally it used to determine what objects are exposed by the server and their types, but it may be useful for the purposes of debugging or for dealing with things that aren't catered for.

method get-vars

method get-vars ()

This returns a Hash keyed by name of the interactive variables defined in the liquidsoap script, the values represent the type of the liquidsoap variable (either Bool, Str or Numeric (which stands in for the liquidsoap "float".

method get-var

method get-var (Str $name)

This returns the value of the named variable (which should be one that has been returned by get-vars.) If the name does not exist then an X::NoVar will be thrown.

method set-var

method set-var (Str $name, $val)

This sets the interactive variable specified by $name to $val. The value should be of an appropriate type as returned by get-vars.

If the variable named doesn't exist then a X::NoVar will be thrown.

A boolean is returned to indicate whether the variable was set on the server successfully.

method requests

method requests ( --> Audio::Liquidsoap::Request)

This returns an Audio::Liquidsoap::Request object that reflects the state of all the requests for output on the liquidsoap from any source (and is distinct from the 'requests' that might come from a Queue for instance.)

method queues

method queues ()

This returns a Hash keyed by name of Audio::Liquidsoap::Queue objects. Each one representing a "request.queue" defined in the liquidsoap script.

method outputs

method outputs ()

This returns a Hash keyed by name Audio::Liquidsoap::Output objects representing the outputs defined in the liquidsoap script. An application may have various outputs to different streaming servers or in different encodings for instance.

method inputs

method inputs ()

This returns a Hash keyed by name of Audio::Liquidsoap::Input objects representing inputs defined in the liquidsoap script (e.g. 'input.harbour', 'input.http',) because these may have different behaviours the actual object may have a role applied to represent the type.

method playlists

method playlists ()

This returns a Hash keyed by name of Audio::Liquidsoap::Playlist objects. These objects represent the playlists defined by 'playlist()' in the liquidsoap script. A typical radio application may use more than one playlist to represent various schedule slots.

Audio::Liquidsoap::Queue

class Audio::Liquidsoap::Queue does Audio::Liquidsoap::Item

Objects of this class represent 'request queues' declared with 'request.queue' or 'request.equeue' in the liquidsoap script.

The queue allows for the addition of arbitrary single tracks by URI (which can either be a remote url or a local filename which must be qualified to a path that is accessible to liquidsoap.)

attribute name

The name of the queue.

attribute client

The Audio::Liquidsoap::Client object that is common with all the other objects.

method push

method push (Str $uri --> Int)

Add a new track to the queue. The supplied URI must either by a resolvable to url of a single remote file or a full local filepath. It will return the "request ID" of the queued request or throw an X::Command if there was an error.

method consider

method consider ($rid)

In the first instance all new requests will be placed in the secondary queue and will be moved to the primary queue and thence become candidates to be sent to an output when necessary.

consider will move the request specified by "request id" from the secondary queue to the primary queue.

method ignore

method ignore ($rid)

Ignoring a request specified by "request id" in the secondary queue will stop that request being selected to be played. It may be removed from the secondary queue at some point.

method queue

method queue ()

This is a list of all the request ids of all the requests in the queue. Comprising both the primary and secondary queues.

method primary-queue

method primary-queue ()

The primary queue is where the selected tracks are chosen to become sources that will be sent to the output(s). This is a list of the request ids.

method secondary-queue

method secondary-queue ()

A list of the request ids that have not yet been selected for the primary queue, they can be added to the primary queue with consider or ignored

Audio::Liquidsoap::Output

class Audio::Liquidsoap::Output does Audio::Liquidsoap::Item

This represents an output as defined in the liquidsoap script. There may be multiple outputs defined for example for different streaming servers, encodings or bitrates. They can all be controlled individually.

attribute type

This is the type of the output which may be e.g. "icecast", "alsa" or any other configured in the liquidsoap.

attribute name

The name of the output.

attribute client

The Audio::Liquidsoap::Client object.

method start

method start ()

Start the output if it is not already started.

method stop

method stop ()

Stop the output if it is started.

method status

method status ()

This returns the status of the output, it may be "on" or "off".

method skip

method skip ()

This causes the output to request its source to provide a new request to be output (which may be an item from a playlist or queue for instance.) Some types of source may not actually support skipping so it may not work for them.

method autostart

method autostart ( --> Bool)

This is a boolean to indicate whether the output should automatically start itself when a playable source becomes available, it is a read/write method so can be set to control the behaviour.

method remaining

method remaining ( --> Duration)

This returns a Duration object representing the time remaining on the current source (e.g. track from a playlist or queue.)

method metadata

method metadata ()

This returns a list of all the Audio::Liquidsoap::Metadata of the individual tracks from all sources that are available to this output.

Audio::Liquidsoap::Request

class Audio::Liquidsoap::Request does Audio::Liquidsoap::Item

This represents something of an aggregation of all the requests in the system from the various queues, manually or dynamically created requests and so forth.

attribute name

This is always 'request'

attribute client

The shared Audio::Liquidsoap::Client object.

method alive

method alive ()

This a list of the request ids of the requests that are able to be sent to an output now, this may include the aggregate of all the primary queues and any manually or dynamically created requests.

method all

method all ()

A list of all the request ids on the system.

method on-air

method on-air ()

This is a list of the "on air" request ids, depending on the way the sources are defined there may actually be more than one entry in the list despite there being only one output, you may need to calculate , based on the source specified in the metadata which one is actually playing.

method resolving

method resolving ()

This is a list of the request ids of those request that have entered the system but have not yet been completely 'resolved', if most of the requests are for local files then this may generally be empty, if there are remote files that need to copied then they may appear here.

method trace

method trace ($rid)

This returns a list of TraceItem objects for the specified request id, there will be at least one, they have when which is a DateTime when the event occurred and what which is largely free text describing what happened. This can be useful for seeing what happens to requests.

method metadata

method metadata ($rid --> Audio::Liquidsoap::Metadata)

This returns an Audio::Liquidsoap::Metadata object for the specified request ID.

Audio::Liquidsoap::Metadata

The metadata contains information that is derived from the source (e.g. ID3 tags) and internally by liquidsoap.

attribute title

This will be the ID3 "title" tag if present.

attribute artist

This will be the ID3 "artist" tag if present.

attribute decoder

This is the internal name of the decoder that liquidsoap used for the input data, e.g. "MAD" if it was MP3 data.

attribute filename

This is the filename that is being used by liquidsoap. If the request URI was a local filename then this will be the same as initial-uri

attribute initial-uri

This is the uri that was used to originally make the request, it may be the same as filename if it represents a local file.

attribute kind

This is the subtype of the liquidsoap source in the form of something like "{audio=2;video=0;midi=0}" , indicating the number of channels of each key in the source. It is not very useful but it is used by liquidsoap to determine the suitability of a request for a source or an outpur.

attribute on-air

A DateTime representing when the request went on-air, it may be undefined if the request hasn't yet been on air.

attribute rid

The request ID.

attribute source

The id of the source as specified in the liquidsoap script, this may be a request queue or playlist for instance.

attribute status

The text status of the request. e.g. "playing", "ready"

attribute temporary

A Bool indicating whether "filename" represents a temporary file that willl be removed when the request is done with.

method new

multi method new (:$metadata!)

The constructor can take a whole record of metadata as returned by liquidsoap.

Audio::Liquidsoap::Input

class Audio::Liquidsoap::Input does Audio::Liquidsoap::Item

This represents an input as defined in the liquidsoap script, because the various input types have different capabilities the objects as created for the inputs hash will have a role applied that will give them additional methods.

attribute type

This is the name of the type of the input e.g. "http", "harbor".

attribute name

The name of the input.

attribute client

The shared Audio::Liquidsoap::Client object.

method buffer-length

method buffer-length ()

The length of the buffer that is being used on the input.

method stop

method stop ()

Stops the input, marking it as unavailable.

method status

method status ( --> Str)

Returns the status of the input as a string. e.g. "stopped", may differ from type to type.

Audio::Liquidsoap::Input::Http

role Audio::Liquidsoap::Input::Http

This is applied to inputs of type 'http' it provides two additional methods. It describes an input which retrieves its source from an external stream over http (such as icecast)

method start

method start ( --> Bool)

Attempts to start this input returning a Bool to indicate success or otherwise.

method uri

method uri ( --> Str)

This is a read/write method that can be used to get or set the uri that the input is being retrieved from.

Audio::Liquidsoap::Input::Harbor

role Audio::Liquidsoap::Input::Harbor

This is applied to inputs of type 'harbor'. It describes an input which receives connections from icecast source clients as a server and is typically used for live streams of radio shows from remote sources.

method kick

method kick ( --> Bool)

Attempt to kick (disconnect) the current connected client, returning a Bool to indicate success.

Audio::Liquidsoap::Playlist

class Audio::Liquidsoap::Playlist does Audio::Liquidsoap::Item

A playlist provides a list of files or URIs as a source and may be a local directory, a text file, xspf, .m3u or other type of playlist format understood by liquidsoap.

attribute name

The name of the playlist.

attribute client

The shared Audio::Liquidsoap::Client

method next

method next ()

Returns a list of the next uris or filenames available from the playlist, in the case of a large playlist or directory this may only be ten or so.

method reload

method reload ()

This will cause the playlist to be reloaded to reflect any changes, it should not affect any currently playing track.

method uri

method uri ( --> Str)

By default this will reflect the uri that the playlist was configured with in the liquidsoap script. It can be set (it is a read/write method) to change the source of the playlist, but as of the latest version of liquidsoap I have tested with it doesn't appear to actual change even though it will start loading files from the new location.

Audio::Liquidsoap::Client

This is the common client that provides the connection to the liquidsoap command server.

attribute port

The port on which to connect, the default is 1234.

attribute host

The host on which to connect. The default is localhost.

method socket

method socket ( --> Audio::Liquidsoap::Client::LiquidSock)

This is the actual socket that is used to perform the connection it is typically not kept open between commands.

method command

method command (Str $command, *@args)

Sends the command to the liquidsoap instance, the command should be qualified with the namespace, any arguments will be supplied as is separated by spaces.

The command method provided by the Audio::Liquidsoap::Item role takes care of providing the namespace for the object.