view release on metacpan or  search on metacpan

lib/Audio/LibSampleRate.pm  view on Meta::CPAN

=encoding utf-8

=head1 NAME

Audio::LibSampleRate - interface to Secret Rabbit Code audio sample rate converter

=head1 SYNOPSIS

  use Audio::LibSampleRate;
  use 5.010;

  my @in = (1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6);
  my @out;

  # High quality sample rate doubling
  say join ' ', map { sprintf "%.1f", $_ } src_simple \@in, 2;
  # 1.1 1.1 1.7 1.7 1.9 1.9 2.2 2.2 ...

  # Very low quality sample rate halving
  say join ' ', src_simple [1 .. 10], 1/2, SRC_LINEAR, 1;
  # 1 2 4 6 8

  # Halve first half, Double second half. Smooth transition.
  my $src = Audio::LibSampleRate->new(SRC_ZERO_ORDER_HOLD, 1);
  say join ' ', $src->process([1 ..  5], 1/2);  # 1 2 4
  say join ' ', $src->process([6 .. 10], 2, 1); # 6 8 9
  # (the doubling doesn't happen due to the smooth transition)

  # Halve first half, Double second half. Step transition.
  $src->reset;
  say join ' ', $src->process([1 ..  5], 1/2);  # 1 2 4
  $src->set_ratio(2);
  say join ' ', $src->process([6 .. 10], 2, 1); # 6 6 7 7 8 8 9 9 10

  say src_get_name SRC_SINC_FASTEST; # Fastest sinc interpolator
  say src_get_description SRC_SINC_FASTEST;
  # Band limited sinc interpolation, fastest, 97dB SNR, 80% BW.

=head1 DESCRIPTION

Secret Rabbit Code (aka libsamplerate) is a Sample Rate Converter for
audio. One example of where such a thing would be useful is converting
audio from the CD sample rate of 44.1kHz to the 48kHz sample rate used
by DAT players.

SRC is capable of arbitrary and time varying conversions ; from
downsampling by a factor of 256 to upsampling by the same factor.
Arbitrary in this case means that the ratio of input and output sample
rates can be an irrational number. The conversion ratio can also vary
with time for speeding up and slowing down effects.

SRC provides a small set of converters to allow quality to be traded
off against computation cost. The current best converter provides a
signal-to-noise ratio of 145dB with -3dB passband extending from DC to
96% of the theoretical best bandwidth for a given pair of input and
output sample rates.

There are two interfaces: a simple procedural interface which converts
a single block of samples in one go, and a more complex object
oriented interface which can handle streaming data, for situations
where the data is received in small pieces.

The underlying library also defines a callback interface, which is not
yet implemented in Audio::LibSampleRate.

All functions and methods below die in case of error with a message
containing the error number and description, as returned by SRC.

=head2 The simple interface

This interface consists of a single function, exported by default:

B<src_simple>(\I<@interleaved_frames>, I<$ratio>, I<$converter_type>, I<$channels>)

where I<@interleaved_frames> is an array of frames in interleaved
format, I<$ratio> is the conversion ratio
(C<output_sample_rate/input_sample_rate>), I<$converter_type> is the
converter as described in the L</"Converter types"> section, and
I<$channels> is the number of channels.

If not supplied, the I<$converter_type> defaults to the best available
converter and I<$channels> defaults to 2 (stereo sound).

The function returns a list of samples, the result of the conversion.

=head2 The object oriented interface

The following methods are available:

=over 4

=item Audio::LibSampleRate->B<new>(I<$converter_type>, I<$channels>)

Creates a new Audio::LibSampleRate object. I<$converter_type> and
I<$channels> have the same meaning and default values as in the
previous section.

=item $self->B<process>(\I<@interleaved_frames>, I<$ratio>, I<$end_of_input>)

The most important function. I<@interleaved_frames> is an array of
frames to be processed in interleaved format, I<$ratio> is the
conversion ratio, and I<$end_of_input> is a boolean (defaulting to
false) that should be true if this is the last piece of data, false
otherwise.

The function returns a list of samples, the result of the conversion.

=item $self->B<reset>

This function resets the internal state of the Audio::LibSampleRate
object. It should be called when the sample rate converter is used on
two separate, unrelated blocks of audio.

=item $self->B<set_ratio>($new_ratio)

Normally, when updating the I<$ratio> argument in B<process> the
library tries to smoothly transition between the previous and the
current conversion ratios. This function changes the ratio without a
smooth transition, achieving a step respone in the conversion ratio.