NAME
Audio::LibSampleRate - interface to Secret Rabbit Code audio sample rate converter
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.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.
The simple interface
This interface consists of a single function, exported by default:
src_simple(\@interleaved_frames, $ratio, $converter_type, $channels)
where @interleaved_frames is an array of frames in interleaved format, $ratio is the conversion ratio (output_sample_rate/input_sample_rate), $converter_type is the converter as described in the "Converter types" section, and $channels is the number of channels.
If not supplied, the $converter_type defaults to the best available converter and $channels defaults to 2 (stereo sound).
The function returns a list of samples, the result of the conversion.
The object oriented interface
The following methods are available:
- Audio::LibSampleRate->new($converter_type, $channels)
-
Creates a new Audio::LibSampleRate object. $converter_type and $channels have the same meaning and default values as in the previous section.
- $self->process(\@interleaved_frames, $ratio, $end_of_input)
-
The most important function. @interleaved_frames is an array of frames to be processed in interleaved format, $ratio is the conversion ratio, and $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.
- $self->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.
- $self->set_ratio($new_ratio)
-
Normally, when updating the $ratio argument in 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.
Converter types
SRC currently offers 5 converters, numbered from 0 to 4. This module includes constants for the available converters, all of them exported by default.
- SRC_SINC_BEST_QUALITY
-
This is a bandlimited interpolator derived from the mathematical sinc function and this is the highest quality sinc based converter, providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%.
This is the default converter for src_simple and new.
- SRC_SINC_MEDIUM_QUALITY
-
This is another bandlimited interpolator much like the previous one. It has an SNR of 97dB and a bandwidth of 90%. The speed of the conversion is much faster than the previous one.
- SRC_SINC_FASTEST
-
This is the fastest bandlimited interpolator and has an SNR of 97dB and a bandwidth of 80%.
- SRC_ZERO_ORDER_HOLD
-
A Zero Order Hold converter (interpolated value is equal to the last value). The quality is poor but the conversion speed is blindlingly fast.
- SRC_LINEAR
-
A linear converter. Again the quality is poor, but the conversion speed is blindingly fast.
The library also includes two functions that provide human-readable information about converters. Both are exported by default.
- src_get_name($converter_type)
-
Given a converter, returns its human-readable name.
- src_get_description($converter_type)
-
Given a converter, returns its human-readable description.
SEE ALSO
http://www.mega-nerd.com/SRC/api.html
AUTHOR
Marius Gavrilescu, <marius@ieval.ro>
COPYRIGHT AND LICENSE
Copyright (C) 2015 by Marius Gavrilescu
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.