head

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

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


code

=begin code

use Audio::Liquidsoap;

my $ls = Audio::Liquidsoap.new;

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


...

=end code


More expansive examples can be found in the examples directory


This provides a mechanism to interact with the L<Liquidsoap media
toolkit|http://liquidsoap.fm/> 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 C<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 C<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.


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(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.


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


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.


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.


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.)


This sends the command C<$command> to liquidsoap command interface and returns
the response verbatim (except the output terminator) If the response indicates
there was an error an exception (L<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 C<client> but this should be the preferred
interface for running ad-hoc commands on the server (such as those added by
C<server.register>


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


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


This returns a list of the lines returned by the C<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.


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".


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


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


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


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


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


This returns an L<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.)




class Audio::Liquidsoap:ver<0.1.1>:auth<github:jonathanstowe>:api<1.0> {

    class X::NoServer is Exception {
        has $.port;
        has $.host;
        has Str $.socket-path;
        has $.error;
        method message() {
            if $!socket-path.defined {
                "Cannot connect on { $!socket-path } : { $!error }";
            }
            else {
                "Cannot connect on { $!host }:{ $!port } : { $!error }";
            }
        }
    }

    class X::Command is Exception {
        has $.error is required;

        method message() {
            my $e = $!error.subst(/'ERROR: '/,'');
            "Got error from server : '$e'";
        }

    }

    sub check-liquidsoap(Int $port = 1234, Str $host = 'localhost') returns Bool is export {
        my $rc = True;
        CATCH {
            when X::NoServer {
               return False;
            }
        }

        $rc = Audio::Liquidsoap.new(:$port, :$host).version ?? True !! False;

        $rc;
    }

    class Client {
        has Int $.port  = 1234;
        has Str $.host  = 'localhost';
        has Str $.socket-path;

        my role LiquidSock {
            has Bool $.closed;
            method opened() returns Bool {
                !$!closed;
            }
            method close() returns Bool {
                if self.opened {
                    self.print: "quit\r\n";
                    $!closed = True;
                    nextsame;
                }
            }
        }

        has LiquidSock $!socket;

        method socket() returns LiquidSock handles <lines recv print close> {
            CATCH {
                default {
                    X::NoServer.new(socket-path => $!socket-path, host => $!host, port => $!port, error => $_.message).throw;
                }
            }

            if not ( $!socket.defined && $!socket.opened) {
                if $!socket-path.defined {
                    $!socket = IO::Socket::INET.new(host => $!socket-path, port => 0, family => PF_UNIX) but LiquidSock;
                }
                else {
                    $!socket = IO::Socket::INET.new(host => $!host, port => $!port, family => PF_INET) but LiquidSock;
                }
            }
            $!socket;
        }

        method command(Str $command, *@args) {
            my @out;
            self.print: $command ~ "\r\n";
            for self.lines -> $l {
                if $l eq 'END' {
                    last;
                }
                @out.append: $l;
            }
            self.close;
            if @out.grep(/^^ERROR:/ ) -> $out {
                X::Command.new(error => $out).throw;
            }
            @out.join("\n");
        }
    }

    has Client $.client;
    has Int $.port = 1234;
    has Str $.host = 'localhost';
    has Str $.socket-path;

    method command(Str $command, *@args) {
        if not $!client.defined {
            $!client = Client.new(socket-path => $!socket-path, host => $!host, port => $!port);
        }
        $!client.command($command, @args);
    }

    method uptime() returns Duration {
        multi sub get-secs(Str $s) returns Duration {
            my regex uptime {
                $<day>=[\d+]d\s+$<hour>=[\d+]h\s+$<minute>=[\d+]m\s+$<second>=[\d+]s
            }

            if $s ~~ /<uptime>/ {
                get-secs($/<uptime>);
            }
            else {
                fail "Incorrect format - $s";
            }
        }

        multi sub get-secs(Match $s) returns Duration {
            my $secs = ($s<day>.Int * 86400) + ($s<hour>.Int * 3600) + ( $s<minute>.Int * 60) + $s<second>.Int;
            Duration.new($secs);
        }

        my $u = self.command("uptime");
        get-secs($u);
    }

    method version() returns Version {
        my $v = self.command("version");
        Version.new($v.split(/\s+/)[1]);
    }

    method list() {
        my $list = self.command('list');
        $list.lines;
    }

    has %!vars;

    method get-vars() {
        my $vars = self.command("var.list");
        my %vars;
        for $vars.lines -> $var {
            my ( $name, $type ) = $var.split(/\s+\:\s+/);
            %vars{$name} = do given $type {
                when 'bool' {
                    Bool
                }
                when 'string' {
                    Str
                }
                when 'float' {
                    Numeric
                }
                default {
                    die "unrecognised type '$_' found in vars";
                }
            }


        }
        %vars;
    }


    class X::NoVar is Exception {
        has $.name is required;
        method message() returns Str {
            "Variable '{ $!name }' does not exist";
        }
    }

    multi sub get-val($val, Bool) returns Bool {
        $val eq 'true';
    }

    multi sub get-val($val, Numeric) returns Rat {
        Rat($val.subst(/'.'$/,''));
    }

    multi sub get-val($val, Str) returns Str {
        $val.subst('"', '', :g);
    }


    method get-var(Str $name) {
        if not %!vars.keys {
            %!vars = self.get-vars();
        }

        if not %!vars{$name}:exists {
            X::NoVar.new(name => $name).throw;
        }

        my $val = self.command("var.get $name");
        get-val($val, %!vars{$name});
    }

    multi sub set-val(Bool $val, Bool) returns Str {
        $val.Str.lc;
    }

    multi sub set-val(Numeric $val, Numeric) {
        $val.Str;
    }
    multi sub set-val(Str() $val, Str) {
        '"' ~ $val ~ '"';
    }

    method set-var(Str $name, $val) {
        if not %!vars.keys {
            %!vars = self.get-vars();
        }

        if not %!vars{$name}:exists {
            X::NoVar.new(name => $name).throw;
        }

        my $out-val = set-val($val, %!vars{$name});

        my $ret = self.command("var.set $name = $out-val");
        if $ret ~~ /"Variable $name set"/ {
            True;
        }
        else {
            False;
        }
    }


    my role SimpleCommand[Str $command] {
        method CALL-ME($self) {
            $self.command($command);
        }
    }

    my role SimpleCommand[Str $command, $check] {
        method CALL-ME($self) {
            $self.command($command) eq $check;
        }
    }

    my role SimpleCommand[Str $command, &after ] {
        method CALL-ME($self) {
            after($self.command($command));
        }
    }

    multi sub trait_mod:<is> (Method $m, Str :$command!) {
        $m does SimpleCommand[$command];
    }

    multi sub trait_mod:<is> (Method $m, :$command! (Str $cmd, Str $check)) {
        $m does SimpleCommand[$cmd, $check];
    }

    multi sub trait_mod:<is> (Method $m, :$command! (Str $cmd, &after)) {
        $m does SimpleCommand[$cmd, &after];
    }

    my role Item {
        has Str $.name;
        has Client $.client;

        method command(Str $command, *@args) {
            my $full-command = "{$!name}.$command";
            if @args.elems {
                $full-command ~= ' ' ~ @args.join(' ');
            }
            $!client.command($full-command);
        }
    }

    sub rids-from-list(Str $rids) {
        $rids.comb(/\d+/).map({Int($_)});
    }

    class Metadata {
        has Str $.title;
        has Str $.artist;
        has Str $.decoder;
        has Str $.filename;
        has Str $.initial-uri;
        has Str $.kind;
        has DateTime $.on-air;
        has Int $.rid;
        has Str $.source;
        has Str $.status;
        has Bool $.temporary;

        multi sub meta-value(Str $key, Str:D $value) {
            $value.subst('"', '', :g)
        }

        multi sub meta-value('on-air', Str:D $value) {
            DateTime.new(meta-value(Str,$value).trans('/' => '-', ' ' => 'T'))
        }
        multi sub meta-value('temporary', Str:D $value) {
            meta-value(Str, $value) eq 'true';
        }
        multi sub meta-value('rid', Str:D $value ) {
            Int(meta-value(Str, $value));
        }

        multi sub meta-key(Str $key) {
            $key.subst('_', '-');
        }

        sub get-metadata-pair(Str $line) {
            my ( $key, $value ) = $line.split('=',2);
            if $key && $value {
                $key   = meta-key($key);
                $value = meta-value($key, $value);
                $key, $value;
            }
        }

        multi method new(:$metadata!) {
            my %meta;
            for $metadata.lines -> $line {
                # Moved the awful code to a subroutine
                if my ( $key, $value) = get-metadata-pair($line) {
                    if $key {
                        %meta{$key} = $value;
                    }
                }
            }
            self.new(|%meta);
        }
    }

    class Request does Item {
        =begin note
        | request.alive
        | request.all
        | request.metadata <rid>
        | request.on_air
        | request.resolving
        | request.trace <rid>
        =end note

        method alive()     is command('alive', &rids-from-list)     { * }

        method all()       is command('all', &rids-from-list)       { * }

        method on-air()    is command('on_air', &rids-from-list)    { * }

        method resolving() is command('resolving', &rids-from-list) { * }

        class TraceItem {
            has Int      $.rid;
            has DateTime $.when;
            has Str      $.what;
        }

        method trace(Int() $rid) {
            my @trace;
            for self.command('trace', $rid).lines -> $line {
                if $line ~~ /^^\[$<when>=(.+?)\]\s+$<that>=(.+)$/ {
                    my $what = ~$/<that>;
                    my $dt = DateTime.new((~$/<when>).trans('/' => '-', ' ' => 'T'));
                    @trace.append: TraceItem.new(:$rid, when => $dt, what => $what);
                }
            }
            @trace;
        }

        method metadata(Int() $rid) returns Metadata {
            my $metadata = self.command('metadata', $rid);
            Metadata.new(:$metadata);
        }
    }

    has Request $!requests;

    method requests() returns Request {
        if not $!requests.defined {
            $!requests = Request.new(name => 'request', client => $!client);
        }
        $!requests;
    }

    class Queue does Item {
        =begin note
        | incoming.consider <rid>
        | incoming.ignore <rid>
        | incoming.primary_queue
        | incoming.push <uri>
        | incoming.queue
        | incoming.secondary_queue
        =end note


        method push(Str $uri) returns Int {
            my $rid = self.command('push',$uri);
            $rid.defined ?? Int($rid) !! Int;
        }

        method consider(Int() $rid) {
            self.command('consider', $rid) eq 'OK';
        }

        method ignore(Int() $rid) {
            self.command('ignore', $rid) eq 'OK';
        }

        method queue() is command('queue', &rids-from-list) { * }

        method primary-queue() is command('primary_queue', &rids-from-list) { * }

        method secondary-queue() is command('secondary_queue', &rids-from-list) { * }

    }

    method queues() {
        if not %!queues.keys.elems {
            self!get-items();
        }
        %!queues;
    }



    class Output does Item {
        has Str $.type;
        =begin note
        | dummy-output.autostart
        | dummy-output.metadata
        | dummy-output.remaining
        | dummy-output.skip
        | dummy-output.start
        | dummy-output.status
        | dummy-output.stop
        =end note


        method start() is command('start') { * }
        method stop()  is command('stop') { * }
        method status() is command('status') { * }
        method skip() is command('skip') { * }
        method autostart() is rw returns Bool {
            my $client  = $!client;
            my $name    = $!name;
            Proxy.new(
                FETCH   =>  method () returns Bool {
                    $client.command("$name.autostart") eq 'on';
                },
                STORE   =>  method (Bool $val) returns Bool {
                    my $on-off = $val ?? 'on' !! 'off';
                    $client.command("$name.autostart $on-off") eq 'on';
                }
            );
        }

        sub get-remaining(Str $r) returns Duration {
            CATCH {
                default {
                    return Duration.new(Rat(0));
                }
            }
            Duration.new(Rat($r // '0'));
        }

        method remaining() returns Duration is command('remaining', &get-remaining) { * }


        method !metadata() is command('metadata') { * }

        method metadata() {
            my @metas;
            for self!metadata.split(/^^'--- '\d+' ---'\s*$$/,:skip-empty) -> $metadata {
                @metas.append: Metadata.new(:$metadata);
            }
            @metas.sort(-> $v { $v.rid });
        }
    }

    method outputs() {
        if not %!outputs.keys.elems {
            self!get-items();
        }
        %!outputs;
    }

    class Input does Item {
        has Str $.type;
        role Http {

            method start() is command('start', 'Done') { * }

            method uri() returns Str is rw {
                my $self = self;
                Proxy.new(
                    FETCH => method () {
                        $self.command('url');
                    },
                    STORE => method (Str() $url) {
                        $self.command('url', $url);
                    }
                );
            }

        }
        role Harbor {
            method kick() returns Str is command('kick', 'Done') { * }
        }

        =begin note
         "http relay"
         | relay-source.buffer_length
         | relay-source.start
         | relay-source.status
         | relay-source.stop
         | relay-source.url [url]
         "harbor"
         | live-source.buffer_length
         | live-source.kick
         | live-source.status
         | live-source.stop
        =end note

        # TODO: make pluggable
        my %type-role = harbor => Harbor, http => Http;

        multi method new(Str :$name, Client :$client, Str :$type ) {
            my $self = self.bless(:$name, :$client, :$type);
            if %type-role{$type}:exists {
                $self does %type-role{$type};
            }
            $self;
        }

        method buffer-length() is command('buffer_length', -> Str $l { Rat($l) }) { * }

        method stop() is command('stop', 'Done') { * }

        method status() returns Str is command('status') { * }

    }

    has Input %!inputs;

    method inputs() {
        if not %!inputs.keys.elems {
            self!get-items();
        }
        %!inputs;
    }

    class Playlist does Item {
        =begin note
        | default-playlist.next
        | default-playlist.reload
        | default-playlist.uri [<URI>]
        =end note

        method next() is command('next', -> $l { $l.lines} ) { * }

        method reload() is command('reload', 'OK') { * }

        method uri() returns Str is rw {
            my $client = $!client;
            my $command = $!name ~ '.uri';
            Proxy.new(
                FETCH => method () {
                    $client.command($command);
                },
                STORE => method (Str() $uri) {
                    $client.command("$command $uri");
                }
            );
        }
    }

    method playlists() {
        if not %!playlists.keys.elems {
            self!get-items();
        }
        %!playlists;
    }

    method !get-items() {
        say self.list.perl;
        for self.list -> $item-line {
            my ($name, $type)  = $item-line.split(/\s+\:\s+/);
            given $type {
                when 'queue'|'request.queue' {
                    %!queues{$name} = Queue.new(name => $name, client => $!client);
                }
                when 'playlist' {
                    %!playlists{$name} = Playlist.new(name => $name, client => $!client);
                }
                when 'request.dynamic.list' {
                    %!playlists{$name} = Playlist.new(name => $name, client => $!client);
                }
                when /^output/ {
                    my $st = $_.split('.')[1];
                    %!outputs{$name} = Output.new(name => $name, client => $!client, type => $st);
                }
                when /^input/ {
                    my $st = $_.split('.')[1];
                    %!inputs{$name} = Input.new(name => $name, client => $!client, type => $st);
                }
                when /variables/ {
                    # do nothing but want to know when we really get one we don't know about
                }
                default {
                    warn "unknown item type '$type' for '$name'" if $*LIQUIDSOAP-DEBUG;
                }
            }

        }
    }

    has Queue       %!queues;
    has Output      %!outputs;
    has Playlist    %!playlists;
}

# vim: expandtab shiftwidth=4 ft=raku


Liquidsoap

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

Simple

Audio::Liquidsoap v0.1.2

Authors

License

Dependencies

Test Dependencies

Provides

Documentation