head

Image

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::Encode::LameMP3 - encode PCM data to MP3 using libmp3lame


=begin code

    use Audio::Encode::LameMP3;
    use Audio::Sndfile;

    my $test-file = 't/data/cw_glitch_noise15.wav';

    my $sndfile = Audio::Sndfile.new(filename => $test-file, :r);
    my $encoder = Audio::Encode::LameMP3.new(bitrate => 128, quality => 3, in-samplerate => $sndfile.samplerate);

    my $out-file = 'encoded.mp3'.IO.open(:w, :bin);

    loop {
        my @in-frames = $sndfile.read-short(4192);
        my $buf = $encoder.encode-short(@in-frames);
        $out-file.write($buf);
        last if ( @in-frames / $sndfile.channels ) != 4192;
    }

    $sndfile.close();
    my  $buf = $encoder.encode-flush();
    $out-file.write($buf);
    $out-file.close;

=end code


See also the C<examples/> directory in the distribution.


This module provides a simple binding to 'mp3lame',v0 an MP3 encoding library.


With this you can encode PCM data to MP3 at any bitrate or quality
supported by the lame library.


The interface is somewhat simplified in comparison to that of lame
and some of the esoteric or rarely used features may not be supported.


Because marshalling large arrays and buffers between Raku space and the
native world may be too slow for some use cases the interface provides
for passing and returning native CArrays (and their sizes) for the use
of other native bindings (e.g. L<Audio::Sndfile>, L<Audio::Libshout>) where
speed may prove important, which , for me at least, is quite a common
use-case.  The C<raku-lame-encode> example demonstrates this way of using
the interface.


All of the encode methods below have multi variants that accept appropriately
shaped CArray arguments (along with the number of frames.)  With the C<:raw>
adverb they will return a C<RawEncode> sub-set which is defined as an Array
of two elements the first being a C<CArray[uint8]> containing the encoded
data and an C<Int> indicating how many items there are.  This is for ease of
interoperating with modules such as L<Audio::Sndfile> and L<Audio::Libshout>
and avoids the cost of marshalling to/from Raku Arrays where it is not needed.


method new(*%attributes) returns Audio::Encode::LameMP3


The constructor of objects of this type, this can be passed any of the
encoder parameters or id3 tags described below.  It will set some internal
defaults.


This initialises the encoder ready to start the encoding.  It may be called after
all the rquired parameters have been set, however it will be called for you when
the first encode method is called.  It is an error to attempt to set any encoding
parameters after C<init> has been called.


This can be used to re-initialise the encoder's internal state in order that it
can be re-used for the encoding of a new source (e.g. a new file.)  It should only
be called after C<encode-flush> has been called and the result of doing otherwise
is undefined.  Typically this could be used when streaming multiple files in sequence
to the the same stream endpoint for example, calling C<encode-flush> and C<init-bitstream>
between each file.


This is not necessary on the first initialisation as it is called by C<init()>


This returns a L<Version> object indicating the version of C<libmp3lame> that is
being used.


Encode the block of PCM data expressed as signed 16 bit integers to
MP3 returning the data as unsigned 8 bit integers.  The input data
can be provided either as separate channels or in interleaved form.
The multi variants allow the data to provided as Raku arrays or as
C<CArray[int16]> and the number of frames ( the number of frames is the
number left channel, right channel pairs.)


If the C<:raw> adverb is provided then the data will be returned as a
two element array containing a C<CArray[uint8]> and an C<Int> with the
number of elements in the array. Otherwise it will return a Raku Array
with the data.


Tests seem to demonstrate that this is the fastest of the encoding
methods, which is convenient as 16 bit PCM is probably the most common
format for general use (being that which is used on CDs.)


multi method encode-short(@left, @right) returns Buf
multi method encode-short(@frames) returns Buf
multi method encode-short(@left, @right, :$raw!) returns RawEncode
multi method encode-short(@frames, :$raw!) returns RawEncode
multi method encode-short(CArray[int16] $left, CArray[int16] $right, Int $frames) returns Buf
multi method encode-short(CArray[int16] $frames-in, Int $frames) returns Buf
multi method encode-short(CArray[int16] $left, CArray[int16] $right, Int $frames, :$raw!) returns RawEncode
multi method encode-short(CArray[int16] $frames-in, Int $frames, :$raw!) returns RawEncode


Encode the block of PCM data expressed as 32 bit integers to MP3 returning
the data as unsigned 8 bit integers.  The input data can be provided
either as separate channels or in interleaved form.  The multi variants
allow the data to provided as Raku arrays or as C<CArray[int32]> and
the number of frames ( the number of frames is the number left channel,
right channel pairs.)


C<libmp3lame> doesn't provide the interleaved data option for this data
type so it is emulated in Raku code so it may be slower if used like that.


The C<libmp3lame> documentation suggests that the scaling of the integer
encoding may not be as good as for other data types, if you need to
use this data type you should test this and provide your own scaling
if necessary.


multi method encode-int(@left, @right) returns Buf
multi method encode-int(@frames) returns Buf
multi method encode-int(@left, @right, :$raw!) returns RawEncode
multi method encode-int(@frames, :$raw!) returns RawEncode
multi method encode-int(CArray[int32] $left, CArray[int32] $right, Int $frames) returns Buf
multi method encode-int(CArray[int32] $frames-in, Int $frames) returns Buf
multi method encode-int(CArray[int32] $left, CArray[int32] $right, Int $frames, :$raw!) returns RawEncode
multi method encode-int(CArray[int32] $frames-in, Int $frames, :$raw!) returns RawEncode


Encode the block of PCM data expressed as 64 bit integers to MP3 returning
the data as unsigned 8 bit integers.  The input data can be provided
either as separate channels or in interleaved form.  The multi variants
allow the data to provided as Raku arrays or as C<CArray[int64]> and
the number of frames ( the number of frames is the number left channel,
right channel pairs.)


multi method encode-long(@left, @right) returns Buf
multi method encode-long(@frames) returns Buf
multi method encode-long(@left, @right, :$raw!) returns RawEncode
multi method encode-long(@frames, :$raw!) returns RawEncode
multi method encode-long(CArray[int64] $left, CArray[int64] $right, Int $frames) returns Buf
multi method encode-long(CArray[int64] $frames-in, Int $frames) returns Buf
multi method encode-long(CArray[int64] $left, CArray[int64] $right, Int $frames, :$raw!) returns RawEncode
multi method encode-long(CArray[int64] $frames-in, Int $frames, :$raw!) returns RawEncode


Encode the block of PCM data expressed as 32 bit floating point numbers
to MP3 returning the data as unsigned 8 bit integers.  The input data
can be provided either as separate channels or in interleaved form.
The multi variants allow the data to provided as Raku arrays or as
C<CArray[num32]> and the number of frames ( the number of frames is the
number left channel, right channel pairs.)


multi method encode-float(@left, @right) returns Buf
multi method encode-float(@frames) returns Buf
multi method encode-float(@left, @right, :$raw!) returns RawEncode
multi method encode-float(@frames, :$raw!) returns RawEncode
multi method encode-float(CArray[num32] $left, CArray[num32] $right, Int $frames) returns Buf
multi method encode-float(CArray[num32] $frames-in, Int $frames) returns Buf
multi method encode-float(CArray[num32] $left, CArray[num32] $right, Int $frames, :$raw!) returns RawEncode
multi method encode-float(CArray[num32] $frames-in, Int $frames, :$raw!) returns RawEncode


Encode the block of PCM data expressed as 64 bit floating point numbers
to MP3 returning the data as unsigned 8 bit integers.  The input data
can be provided either as separate channels or in interleaved form.
The multi variants allow the data to provided as Raku arrays or as
C<CArray[num64]> and the number of frames ( the number of frames is the
number left channel, right channel pairs.)


multi method encode-double(@left, @right) returns Buf
multi method encode-double(@frames) returns Buf
multi method encode-double(@left, @right, :$raw!) returns RawEncode
multi method encode-double(@frames, :$raw!) returns RawEncode
multi method encode-double(CArray[num64] $left, CArray[num64] $right, Int $frames) returns Buf
multi method encode-double(CArray[num64] $frames-in, Int $frames) returns Buf
multi method encode-double(CArray[num64] $left, CArray[num64] $right, Int $frames, :$raw!) returns RawEncode
multi method encode-double(CArray[num64] $frames-in, Int $frames, :$raw!) returns RawEncode


LameMP3

Audio::Convert::Samplerate - perform samplerate conversion on audio data


=begin code

    use Audio::Convert::Samplerate;
    use Audio::Sndfile;

    my $test-file-in = "t/data/1sec-chirp-22050.wav";
    my $test-file-out = "test-out.wav";
    my $bufsize = 4192;
    my $ratio = 2;

    my Audio::Sndfile $in-obj = Audio::Sndfile.new(filename => $test-file-in, :r);
    my Audio::Convert::Samplerate $conv-obj =  Audio::Convert::Samplerate.new(channels => $in-obj.channels);
    my Int $sr = ($in-obj.samplerate * $ratio).Int;

    my Audio::Sndfile $out-obj = Audio::Sndfile.new(filename   => $test-file-out,
                                                    channels   => $in-obj.channels,
                                                    format     => $in-obj.format,
                                                    samplerate => $sr,  :w);


    loop {
        my @data-in = $in-obj.read-int($bufsize);
        my Bool $last = (@data-in.elems != ($bufsize * $in-obj.channels));
        my @data-out = $conv-obj.process-int(@data-in, $ratio, $last);
        $out-obj.write-int(@data-out);
        last if $last;
    }

    $in-obj.close;
    $out-obj.close;

=end code


See also the C<examples> directory in the repository.


This provides a mechanism for doing sample rate conversion of PCM audio
data using libsamplerate (http://www.mega-nerd.com/libsamplerate/)
the implementation of which is both fairly quick and accurate.


The interface is fairly simple, providing methods to work with native
C arrays where the raw speed is important as well as Raku arrays where
further processing is required on the data.


The native library is designed to work only with 32 bit floating point
samples so working with other sample types requires some conversion
and a subsequent small loss of efficiency (although the int and short
to float conversions are done in C code and so are reasonably quick.)
There is no support for 64 bit int (long) or float (double) data.


It should be noted that "round-tripping" data (for example doubling
the samplerate and then halving it again,) may not always result in the
same number of samples that you started with (by a very small number
usually less than 0.2% of the samples.) This is a feature of the way
that libsamplerate works and not a bug.


method new (Type :$type = Medium, Int :$channels = 2)


The constructor of the class.  The C<type> parameter is a value of
the enum C<Type> with one of thse values:


item

The converter types are described in detail at L<http://www.mega-nerd.com/SRC/api_misc.html#Converters>


The default for C<type> is C<Medium> which has a balance of quality of
speed suitable for general application.


The C<channels> should represent the number of channels present in the
input audio for the processing methods.  It defaults to 2 but should always
represent the correct value or the conversion will be incorrect.


method samplerate-version ( --> Version)


This returns a L<Version> object that represents the version of the
underlying library.  The author of the library seems to use their own
scheme for versioning so this is probably not suitable for direct
comparison.


method process-float (@items, Num $src-ratio, Bool $last = False --> Array)


Perform sample rate conversion on the 32 bit floating point numbers
provided as an array, to the ratio C<$src-ratio> returning an array of
the processed samples.  The C<$last> should be set to True when this is
the last batch of samples to be processed so it can return any buffered
samples.


This will throw an L<X:InvalidRatio> if the ratio supplied was found to
be invalid, or a L<X::ConvertError> if there was some other problem with
the conversion.


method process-short (@items, Num $src-ratio, Bool $last = False --> Array)


Perform sample rate conversion on the 16 bit integers provided as an
array, to the ratio C<$src-ratio> returning an array of the processed
samples.  The C<$last> should be set to True when this is the last batch
of samples to be processed so it can return any buffered samples.


method process-int (@items, Num $src-ratio, Bool $last = False --> Array)


Perform sample rate conversion on the 32 bit integers provided as an
array, to the ratio C<$src-ratio> returning an array of the processed
samples.  The C<$last> should be set to True when this is the last batch
of samples to be processed so it can return any buffered samples.


multi method process (CArray[num32] $data-in, Int $input-frames, Num $src-ratio, Bool $last = False --> RawProcess)
multi method process (CArray[int16] $data-in, Int $input-frames, Num $src-ratio, Bool $last = False --> RawProcess)
multi method process (CArray[int32] $data-in, Int $input-frames, Num $src-ratio, Bool $last = False --> RawProcess)


Perform sample rate conversion on the samples in the appropriately typed
native array which should contain the data for C<$input-frames> frames
(that is the number of samples divided by the number of channels in the
data,)  to the ratio C<$src-ratio>. The C<$last> should be set to True
when this is the last batch of samples to be processed so it can return
any buffered samples.


The return value is a two element array with a L<CArray> as the first
element and the number of B<frames> represented as the second.


method is-valid-ratio (Num() $ratio --> Bool)


Returns a Bool to indicate whether the supplied conversion ratio is valid.
This may be used if taking a ratio from user input as the process
methods will throw an exception if supplied an invalid ratio.



class Audio::Convert::Samplerate:ver<0.0.9>:auth<github:jonathanstowe>:api<1.0> {
    use NativeCall;
    use NativeHelpers::Array;

    subset RawProcess of Array where  ($_.elems == 2 ) && ($_[0] ~~ CArray) && ($_[1] ~~ Int);

    enum Type <Best Medium Fastest OrderHold Linear>;

    class X::ConvertError is Exception {
        has Int $.error-code = 0;

        sub src_strerror(int32 $error --> Str ) is native('samplerate',v0) { * }

        method message( --> Str ) {
            src_strerror($!error-code);
        }
    }

    class X::InvalidRatio is Exception {
        has Num $.ratio is required;

        method message( --> Str ) {
            "The convertion ratio { $!ratio } is not valid";
        }
    }

    class Data is repr('CStruct') {
        has CArray[num32] $.data-in;
        has CArray[num32] $.data-out;
        has int64 $.input-frames;
        has int64 $.output-frames;
        has int64 $.input-frames-used;
        has int64 $.output-frames-gen;
        has int32 $.end-of-input;
        has num64 $.src-ratio;

        submethod BUILD(CArray[num32] :$data-in!, Int :$input-frames!, Num() :$src-ratio!, Int :$channels = 2, Bool :$last = False) {
            $!data-in := $data-in;
            $!input-frames = $input-frames;
            $!src-ratio = $src-ratio;
            my CArray[num32] $data-out := CArray[num32].new;
            $!output-frames = ($input-frames * $src-ratio).Int + 10;
            $data-out[$!output-frames * $channels] = Num(0);
            $!data-out := $data-out;
            $!input-frames-used = 0;
            $!output-frames-gen = 0;
            $!end-of-input = $last ?? 1 !! 0;
        }
    }

    class State is repr('CPointer') {

        sub src_new(int32 $converter-type, int32 $channels, int32 $error --> State ) is native('samplerate',v0) { * }

        method new(Type $type, Int $channels --> State) {
            my Int $error = 0;
            my $state = src_new($type.Int, $channels, $error);

            if not $state.defined {
                X::ConvertError.new(error-code => $error).throw;
            }

            $state;
        }

        sub src_process(State $st, Data $d is rw --> int32) is native('samplerate',v0) { * }

        multi method process(Data $data is rw --> Data ) {
            my $rc = src_process(self, $data);

            if $rc != 0 {
                X::ConvertError.new(error-code => $rc).throw;
            }
            $data;
        }

        # put this in here as it simplifies matters
        sub src_is_valid_ratio (num64 $ratio --> int32 ) is native('samplerate',v0) { * }

        method is-valid-ratio(Num $ratio --> Bool ) {
            so src_is_valid_ratio($ratio);
        }

        sub src_set_ratio(State $state, num64 $new_ratio --> int32 ) is native('samplerate',v0) { * }

        method set-ratio(Num $new-ratio) {
            my $rc = src_set_ratio(self, $new-ratio);

            if $rc != 0 {
                X::ConvertError.new(error-code => $rc).throw;
            }
        }

        sub src_reset(State --> int32 ) is native('samplerate',v0) { * }

        method reset() {
            my $rc = src_reset(self);

            if $rc != 0 {
                X::ConvertError.new(error-code => $rc).throw;
            }
        }

        sub src_delete(State) is native('samplerate',v0) { * }

        method DESTROY() {
            src_delete(self);
        }

    }


    has Type  $!type;
    has Int   $!channels;
    has State $!state handles <is-valid-ratio>;

    submethod BUILD(Type :$!type = Medium, Int :$!channels = 2) {
        $!state = State.new($!type, $!channels);
    }

    sub src_get_version( --> Str ) is native('samplerate',v0) { * }

    method samplerate-version( --> Version ) {
        my $v = src_get_version();
        Version.new($v);
    }

    multi method process(CArray[num32] $data-in, Int $input-frames, Num() $src-ratio, Bool $last = False --> RawProcess ) {

        if not self.is-valid-ratio($src-ratio) {
            X::InvalidRatio.new.throw;
        }


        my Data $data = Data.new(:$data-in, :$input-frames, :$last, :$src-ratio);

        $data = $!state.process($data);
        refresh($data);

        [ $data.data-out, $data.output-frames-gen ];
    }

    method !process-other(Mu $type, CArray $data-in, Int $input-frames, Num() $src-ratio, Bool $last, &to, &from --> RawProcess ) {
        my CArray[num32] $new-data = CArray[num32].new;
        my Int $total-frames = ($input-frames * $!channels).Int;
        $new-data[$total-frames] = Num(0);
        &to($data-in, $new-data, $total-frames);
        (my $float-out, my $frames-out ) = self.process($new-data, $input-frames, $src-ratio, $last).list;
        my CArray $int-out = CArray[$type].new;
        my Int $total-out = ($frames-out * $!channels).Int;
        $int-out[$total-out] = 0;
        &from($float-out, $int-out, $total-out);
        [ $int-out, $frames-out ]
    }

    multi method process(CArray[int16] $data-in, Int $input-frames, Num() $src-ratio, Bool $last = False --> RawProcess ) {
        self!process-other(int16, $data-in, $input-frames, $src-ratio, $last, &src_short_to_float_array, &src_float_to_short_array);
    }

    multi method process(CArray[int32] $data-in, Int $input-frames, Num() $src-ratio, Bool $last = False --> RawProcess ) {
        self!process-other(int32, $data-in, $input-frames, $src-ratio, $last, &src_int_to_float_array, &src_float_to_int_array);
    }

    method !process-array(Mu $type, @items, Num() $src-ratio, Bool $last = False --> Array ) {
        my CArray $carray = copy-to-carray(@items, $type);
        my $frames = (@items.elems / $!channels).Int;
        my $ret = self.process($carray, $frames, $src-ratio, $last);
        copy-to-array($ret[0], $ret[1] * $!channels);
    }
    method process-float(@items, Num() $src-ratio, Bool $last = False --> Array ) {
        self!process-array(num32, @items, $src-ratio, $last);
    }
    method process-short(@items, Num() $src-ratio, Bool $last = False --> Array ) {
        self!process-array(int16, @items, $src-ratio, $last);
    }
    method process-int(@items, Num() $src-ratio, Bool $last = False --> Array ) {
        self!process-array(int32, @items, $src-ratio, $last);
    }

    sub src_short_to_float_array(CArray[int16] $in, CArray[num32] $out, int32 $len) is native('samplerate',v0) { * }
    sub src_float_to_short_array(CArray[num32] $in, CArray[int16] $out, int32 $len) is native('samplerate',v0) { * }

    sub src_int_to_float_array(CArray[int32] $in, CArray[num32] $out, int32 $len) is native('samplerate',v0) { * }
    sub src_float_to_int_array(CArray[num32] $in, CArray[int32] $out, int32 $len) is native('samplerate',v0) { * }

}

# vim: expandtab shiftwidth=4 ft=raku


Samplerate

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::Convert::Samplerate

image i_github_com_jonathanstowe_audio_convert_samplerate_workflows_ci_badge_svg not found

Description

Installation

Support

Licence

Audio::Convert::Samplerate v0.0.10

Authors

License

Dependencies

Test Dependencies

Provides

Documentation