head

code

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::Libshout - binding to the xiph.org libshout icecast source client


=begin code

use v6;

use Audio::Libshout;

sub MAIN(IO(Str) $in-file) {
    my $shout = Audio::Libshout.new(password => 'hackme', mount => '/foo', format => Audio::Libshout::Format::MP3);
    my $fh = $in-file.open(:bin);
    my $channel = $shout.send-channel;

    while not $fh.eof {
        my $buf = $fh.read(4096);
        $channel.send($buf);
    }

    $fh.close;
    $channel.close;
    $shout.close;
}

=end code


See also the files in the L<examples|examples> directory


This provides a source client to stream to an icecast server.  It can
stream Ogg/Vorbis or MP3 data but doesn't provide any transcoding so the
data will need to be provided from an appropriate source in the required
encoding. This has been developed against version 2.2.2 of libshout,
it is possible later versions may provide support for other encodings.


The API is somewhat simplified in comparison to libshout but provides
an asynchronous mechanism whereby data can be fed as quickly as it is
obtained to a worker thread via a channel so the client doesn't have
to worry about the timing and synchronisation issues, though the lower
level send and sync methods are available if your application requires
a different scheme.


In testing this proved quite capable of streaming a 320kb/s MP3 read from
a file to an icecast server on the local network, though of course network
conditions may limit the rate that will work well to remote servers.


The "examples" directory in the distribution contains a simple streaming
source client that will allow you to send an Ogg or MP3 file to an
icecast server.


If you're curious the first thing that I streamed using this library was


https://www.mixcloud.com/mikestern-awakening/mike-stern-guest-mix-for-technotic-eire-radio-show/


Mike's a great DJ, great DJs and producers make making software
worthwhile :)


method new(*%params) returns Audio::Libshout


The object constructor can be passed any of the parameters described in
L<STREAM PARAMETERS>.  It may throw an L<X::ShoutError> if there was a
problem initialising the library or setting any of the parameters.


The L<Audio::Libshout> object returned will be initialised but not
connected to the server, the connection should be made before any data
is sent to the server.


If the stream is not already connected this will open the stream so
that data can be sent.  The C<host>, C<port>, C<user> and C<password>
and other parameters that may be required by the protocol must be set
before calling C<open>.  If a connection cannot be made to the server or
the server refuses the connection (e.g. due to an authentication failure,)
a L<X::ShoutError> will be thrown.


It should be noted that the behaviour when there is a failure after the
initial connection to the server has been made  (such as an authentication
problem,) may differ between versions of C<libshout>:  v2.2.2 will allow
the connections parameters (e.g. the password,) to be changed and the
C<open> retried using the same instance, however later versions (I have tested
with v2.4.3,) may fail again with "already connected" and you will need
to create a new C<Audio::Libshout> instance with the revised parameters
to try again.


This will be called for you the first time that C<send> is called or
the first data is sent to the C<send-channel> however you may wish to
call it early in order to detect and rectify any problems.


This will close the connection to the server.  It will wait for the worker
thread that is started by C<send-channel> to complete, which will not
happen until the L<Channel> is closed so you should always call C<close>
on the channel to indicate that no more data will be sent.


multi method send(Buf $buf)
multi method send(CArray[uint8], Int $bytes);
multi method send(RawEncode $raw);


This will send the L<Buf> of unsigned chars (L<uint8>,) to the
server. The buffer must contain data encoded as per that set for C<format>
(i.e. either C<Ogg> or C<MP3> ) If there is a problem sending the data to
the server then a L<X::ShoutError> will be thrown.  If C<open> has not
already been called it will be called for you and this may also throw an
exception. The data will be sent immediately so C<sync> should be called
between each attempt to send or an exception may be thrown indicating
that the server is busy.


The second multi variant is intended to make interoperation with other
libraries which may return encoded data in a C<CArray>.  The third
is similar but accepts an C<Array> of two elements the first being
a C<CArray[uint8]> and the second an C<Int> which is the number of
bytes in the array, this reflects the return value of the C<encode>
methods of L<Audio::Encode::LameMP3> with the C<:raw> adverb. This
is intended to reduce the marshalling required when there is no
need to have the data in Raku space.


If you don't want to be concerned with the synchronisation issues then you
should consider the asynchronous interface provided by C<send-channel>.


This will block the thread of execution until the server is ready to
accept new data.  It should be called between each call to C<send> in
order to maintain the rate of data transfer correctly.  A C<send> that
is made without a preceding C<sync> may throw an exception indicating
that the server is busy.


multi method send-channel() returns Channel
multi method send-channel(Channel $channel) returns Channel


This provides an asynchronous mechanism that allows a client to send
data to a L<Channel> as it becomes available, being processed by a
helper thread that will take care of the synchronisation.  This should
be considered the preferred interface for most applications.


If C<open> has not already been called then it will be done for you the
first time that data is received on the L<Channel>, as with C<open> an
exception will be thrown if a connection cannot be made or the server
refuses the connection.


As with C<send> the data sent to the L<Channel> should be a L<Buf>
of unsigned chars (L<uint8>). If data of another type is sent on the
channel then an exception will be thrown in the worker thread. The data
can also be Array of two elements: a C<CArray[uint8]> and an C<Int> that
is the number of bytes in that C<CArray> as described under C<send> above.


This can be provided with an existing L<Channel> that may be useful if
the data originates from another asynchronous source for example.


The worker thread will be started immediately that this method is called
and will remain active until the channel is closed, consequently a
subsequent call to C<close> will wait until the thread is finished to
allow all the sent data to be transmitted to the server.


The "streamfile" program in the repository provides an example of the
use of this interface.


multi method add-metadata(Str $key, Str $value)
multi method add-metadata(*%metas)


This provides a means to set the metadata on the stream, it only works
for streams of format C<MP3>. The exact meaning of any particular metadata
item is specific to the client of the stream.


The metadata items are added to or updated in a private metadata
structure, that can be applied to the stream with C<set-metadata>, for
convenience if the metadata is supplied in the second form (i.e like
named arguments,) this will be done for you.


This may throw a L<X::ShoutError> if the metadata structure is invalid.



class Audio::Libshout:ver<0.0.13>:auth<github:jonathanstowe>:api<1.0> {
    use NativeCall;
    use AccessorFacade;

    my constant LIB = [ 'shout', v3 ];

    # encapsulate (bytes, count) in a type safe way
    subset RawEncode of Array where  ($_.elems == 2 ) && ($_[0] ~~ CArray) && ($_[1] ~~ Int);

    enum Error ( Success => 0 , Insane => -1 , Noconnect => -2 , Nologin => -3 , Socket => -4 , Malloc => -5, Meta => -6, Connected => -7, Unconnected => -8, Unsupported => -9, Busy => -10 );
    enum Format ( Ogg => 0, MP3 => 1 );
    enum Protocol ( HTTP => 0, XAUDIOCAST => 1, ICY => 2);

    class X::ShoutError is Exception {
        has Error $.error;
        has Str $.what = "unknown operation";

        method message() {
            my $message = do given $!error {
                                when Insane {
                                    "Not a valid Shout object or missing parameters";
                                }
                                when Noconnect {
                                    "A connection to the server could not be established."
                                }
                                when Nologin {
                                    "The server refused login, probably because authentication failed.";
                                }
                                when Socket {
                                    "An error occured while talking to the server.";
                                }
                                when Malloc {
                                    "There wasn't enough memory to complete the operation.";
                                }
                                when Meta {
                                    "The server returned an error while setting metadata.";
                                }
                                when Connected {
                                    "The connection has already been opened."
                                }
                                when Unconnected {
                                    "The Shout object is not currently connected";
                                }
                                when Unsupported {
                                    "The combination of parameters is not supported for this operation";
                                }
                                when Busy {
                                    "The connection is busy and could not perform the operation.";
                                }
                                default {
                                    "Unknown issue or not an error";
                                }

                            }
            $!what ~ ' : ' ~ $message;
        }
    }

    class Metadata is repr('CPointer') {
        sub shout_metadata_new( --> Metadata ) is native(LIB) { * }

        method new() {
            shout_metadata_new();
        }

        sub shout_metadata_free(Metadata) is native(LIB) { * }

        method DESTROY() {
            self.dispose;
        }

        method dispose() {
            shout_metadata_free(self);
        }

        sub shout_metadata_add(Metadata, Str, Str  --> int32 ) is native(LIB) { * }

        method add(Str $key is copy, Str $value is copy --> Error ) {
            explicitly-manage($key);
            explicitly-manage($value);
            my $rc = shout_metadata_add(self, $key, $value);
            Error($rc);
        }

    }

    class Shout is repr('CPointer') {

        sub shout_new( --> Shout ) is native(LIB) { * }

        method new(Shout:U: *%attribs --> Shout ) {
            my $shout = shout_new();

            for %attribs.kv -> $attrib, $value {
                if $shout.can($attrib) {
                    $shout."$attrib"() = $value;
                }
            }
            $shout;
        }

        sub shout_free(Shout --> int32 ) is native(LIB) { * }

        submethod DESTROY() {
            self.dispose;
        }

        method dispose() {
            shout_free(self);
        }

        sub shout_open(Shout) returns int32 is native(LIB) { * }

        method open( --> Error ) {
            my $rc = shout_open(self);
            Error($rc);
        }

        sub shout_close(Shout --> int32 ) is native(LIB) { * }

        method close( --> Error ) {
            my $rc = shout_close(self);
            Error($rc);
        }

        sub shout_send(Shout, CArray[uint8], int32 --> int32 ) is native(LIB) { * }

        proto method send(|c) { * }
        multi method send(CArray $buf, Int $elems --> Error ) {
            my $rc = shout_send(self, $buf, $elems);
            Error($rc);
        }

        multi method send(Buf $buf --> Error ) {
            my $carray = CArray[uint8].new;
            $carray[$_] = $buf[$_] for ^($buf.elems);
            self.send($carray, $buf.elems);
        }

        sub shout_sync(Shout) is native(LIB) { * }

        method sync() {
            shout_sync(self);
        }

        my sub manage(Shout $self, Str $value is copy) {
            explicitly-manage($value);
            $value;
        }

        my sub check(Shout $self, Int $rc ) {
            given Error($rc) {
                when Success {
                }
                default {
                    X::ShoutError.new(error => $_, what => "Setting parameter").throw;
                }
            }

        }

        # "attributes"
        #
        sub shout_set_host(Shout, Str --> int32 ) is native(LIB) { * }
        sub shout_get_host(Shout --> Str ) is native(LIB) { * }

        method host( --> Str ) is rw is accessor-facade(&shout_get_host, &shout_set_host, &manage, &check) { }

        sub shout_set_port(Shout, int32 --> int32 ) is native(LIB) { * }
        sub shout_get_port(Shout --> int32 ) is native(LIB) { * }

        method port( --> Int ) is rw is accessor-facade(&shout_get_port, &shout_set_port, Code, &check) { }

        sub shout_set_user(Shout, Str --> int32 ) is native(LIB) { * }
        sub shout_get_user(Shout --> Str ) is native(LIB) { * }

        method user( --> Str ) is rw is accessor-facade(&shout_get_user, &shout_set_user, &manage, &check) { }

        sub shout_set_password(Shout, Str --> int32 ) is native(LIB) { * }
        sub shout_get_password(Shout --> Str ) is native(LIB) { * }

        method password( --> Str ) is rw is accessor-facade(&shout_get_password, &shout_set_password, &manage, &check) { }

        sub shout_get_protocol(Shout --> int32 ) is native(LIB) { * }
        sub shout_set_protocol(Shout, int32 --> int32 ) is native(LIB) { * }

        method protocol( --> Protocol ) is rw is accessor-facade(&shout_get_protocol, &shout_set_protocol, Code, &check) { }

        sub shout_get_format(Shout --> int32 ) is native(LIB) { * }
        sub shout_set_format(Shout, int32 --> int32 ) is native(LIB) { * }

        method format( --> Format ) is rw is accessor-facade(&shout_get_format, &shout_set_format, Code, &check) { }

        sub shout_get_mount(Shout --> Str ) is native(LIB) { * }
        sub shout_set_mount(Shout, Str --> int32 ) is native(LIB) { * }

        method mount( --> Str ) is rw is accessor-facade(&shout_get_mount, &shout_set_mount, &manage, &check) { }

        sub shout_get_dumpfile(Shout --> Str ) is native(LIB) { * }
        sub shout_set_dumpfile(Shout, Str --> int32 ) is native(LIB) { * }

        method dumpfile( --> Str ) is rw is accessor-facade(&shout_get_dumpfile, &shout_set_dumpfile, &manage, &check ) { }

        sub shout_get_agent(Shout --> Str ) is native(LIB) { * }
        sub shout_set_agent(Shout, Str --> int32 ) is native(LIB) { * }

        method agent(--> Str ) is rw is accessor-facade(&shout_get_agent, &shout_set_agent, &manage, &check) { }

        # Directory parameters
        sub shout_get_public(Shout --> int32 ) is native(LIB) { * }
        sub shout_set_public(Shout, int32 --> int32 ) is native(LIB) { * }

        method public( --> Bool ) is rw is accessor-facade(&shout_get_public, &shout_set_public, Code, &check) { }

        sub shout_get_name(Shout --> Str ) is native(LIB) { * }
        sub shout_set_name(Shout, Str --> int32 ) is native(LIB) { * }

        method name( --> Str ) is rw is accessor-facade(&shout_get_name, &shout_set_name, &manage, &check) { }

        sub shout_get_url(Shout --> Str ) is native(LIB) { * }
        sub shout_set_url(Shout, Str --> int32 ) is native(LIB) { * }

        method url( --> Str ) is rw is accessor-facade(&shout_get_url, &shout_set_url, &manage, &check) { }

        sub shout_get_genre(Shout --> Str ) is native(LIB) { * }
        sub shout_set_genre(Shout, Str --> int32 ) is native(LIB) { * }

        method genre( --> Str ) is rw is accessor-facade(&shout_get_genre, &shout_set_genre, &manage, &check) { }

        sub shout_get_description(Shout --> Str ) is native(LIB) { * }
        sub shout_set_description(Shout, Str --> int32 ) is native(LIB) { * }

        method description( --> Str ) is rw is accessor-facade(&shout_get_description, &shout_set_description, &manage, &check) { }

        # Not making a method for these quite yet.
        sub shout_get_audio_info(Shout, Str --> Str ) is native(LIB) { * }
        sub shout_set_audio_info(Shout, Str, Str --> Str ) is native(LIB) { * }

        # Set the metadata on this instance.

        sub shout_set_metadata(Shout, Metadata --> int32 ) is native(LIB) { * }

        method set-metadata(Metadata $meta --> Error ) {
            my $rc = shout_set_metadata(self, $meta);
            Error($rc);
        }

        sub shout_get_error(Shout --> Str ) is native(LIB) { * };

        method last-error( --> Str ) {
            shout_get_error(self);
        }

        sub shout_get_errno(Shout --> int32 ) is native(LIB) { * };

        method last-error-number( --> Error ) {
            my $rc = shout_get_errno(self);
            Error($rc);
        }
    }

    class Initialiser {
        has Int $!initialisers = 0;

        sub shout_init() is native(LIB) { * }

        method init() {
            if $!initialisers == 0 {
                shout_init();
            }
            ++$!initialisers;
        }

        sub shout_shutdown() is native(LIB) { * }

        method shutdown() {
            --$!initialisers;
            if $!initialisers == 0 {
                shout_shutdown();
            }
        }
    }


    my $initialiser = Initialiser.new;

    has Shout $!shout handles <host port user password protocol format mount dumpfile agent public name url genre description>;
    has Metadata $!metadata;

    has Bool $!opened = False;

    has Promise $!helper-promise;

    method open() {
        if not $!opened {
            my $rc = $!shout.open();
            if $rc !~~ Success {
                X::ShoutError.new(error => $rc, what => "opening stream").throw;
            }
            $!opened = True;
        }
    }

    proto method send(|c) { * }
    multi method send(Buf $buff) {
        if not $!opened {
            self.open()
        }
        my $rc = $!shout.send($buff);
        if $rc !~~ Success {
            X::ShoutError.new(error => $rc, what => "sending data").throw;
        }
    }

    multi method send(CArray $buff, Int $bytes) {
        if not $!opened {
            self.open()
        }
        my $rc = $!shout.send($buff, $bytes);
        if $rc !~~ Success {
            X::ShoutError.new(error => $rc, what => "sending data").throw;
        }
    }

    multi method send(RawEncode $raw) {
        self.send($raw[0], $raw[1]);
    }

    proto method send-channel(|c) { * }

    multi method send-channel(Audio::Libshout $self: --> Channel ) {
        my $channel = Channel.new;
        $self.send-channel($channel);
    }

    class X::ChannelError is Exception {
        has Exception $.inner;
        method message() {
            "An error occurred in the send-channel : '{ $!inner.message }'";
        }
    }

    multi method send-channel(Audio::Libshout $self: Channel $channel --> Channel ) {
        sub send() {
            for $channel.list -> $item {
                    CATCH {
                        default {
                            $self.close;
                            X::ChannelError.new(inner => $_).throw;
                        }
                    }
                    LAST {
                    }
                    $self.send($item);
                    $self.sync;
            }
        }
        $!helper-promise = Promise.start(&send, scheduler => ThreadPoolScheduler.new);
        $channel;
    }

    method sync() {
        if $!opened {
            $!shout.sync();
        }
    }

    method close() {
        if $!helper-promise.defined {
            await $!helper-promise;
        }
        if $!opened {
            my $rc = $!shout.close();
            if $rc !~~ Success {
                X::ShoutError.new(error => $rc, what => "closing stream").throw;
            }
            $!opened = False;
        }
    }

    proto method add-metadata(|c) { * }

    multi method add-metadata(Str $key, Str $value) {
        my $rc = $!metadata.add($key, $value);
        if $rc !~~ Success {
            X::ShoutError.new(error => $rc, what => "adding metadata");
        }
    }

    multi method add-metadata(*%metas) {
        for %metas.kv -> $key, $value {
            self.add-metadata($key, $value);
        }
        self.set-metadata();
    }

    method set-metadata() {
        if self.format ~~ MP3 {
            my $rc = $!shout.set-metadata($!metadata);
            if $rc !~~ Success {
                X::ShoutError.new(error => $rc, what => "setting metadata");
            }
        }
    }


    sub shout_version(int32, int32, int32 --> Str ) is native(LIB) { * }
    method libshout-version( --> Version ) {
        my int32 $major;
        my int32 $minor;
        my int32 $patch;
        my $v = shout_version($major, $minor, $patch);
        Version.new($v);
    }

    multi submethod BUILD(*%attribs) {
        if not $initialiser.defined {
            $initialiser = Initialiser.new;
        }
        $initialiser.init();
        $!shout = Shout.new(|%attribs);
        $!metadata = Metadata.new;
    }

    method dispose(Audio::Libshout:D:) {
        if $!metadata.defined {
            $!metadata = Metadata;
        }
        if $!shout.defined {
            $!shout.dispose;
            $!shout = Shout;
        }
        $initialiser.shutdown();
    }

    submethod DESTROY() {
        self.dispose;
    }
}

# vim: expandtab shiftwidth=4 ft=raku


Libshout

item

Documentation

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

Audio::Libshout Examples

synopsis

streamfile

streamfile-encode

Audio::Libshout v0.0.14

Authors

License

Dependencies

Test Dependencies

Provides

Documentation