lib/Audio/LibSampleRate.pm

   1 package Audio::LibSampleRate;
   2
   3 use 5.008009;
   4 use strict;
   5 use warnings;
   6 use parent qw/Exporter/;
   7
   8 my @constants;
   9 BEGIN { @constants = qw/SRC_SINC_BEST_QUALITY SRC_SINC_MEDIUM_QUALITY SRC_SINC_FASTEST SRC_ZERO_ORDER_HOLD SRC_LINEAR/ }
  10 use constant +{ map { $constants[$_] => $_ } 0 .. $#constants };
  11
  12 our @EXPORT_OK = (qw/src_simple src_get_name src_get_description/, @constants);
  13 our @EXPORT = @EXPORT_OK;
  14
  15 our $VERSION = '0.001';
  16
  17 use XSLoader;
  18 XSLoader::load('Audio::LibSampleRate', $VERSION);
  19
  20 1;
  21 __END__
  22
  23 =encoding utf-8
  24
  25 =head1 NAME
  26
  27 Audio::LibSampleRate - interface to Secret Rabbit Code audio sample rate converter
  28
  29 =head1 SYNOPSIS
  30
  31   use Audio::LibSampleRate;
  32   use 5.010;
  33
  34   my @in = (1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6);
  35   my @out;
  36
  37   # High quality sample rate doubling
  38   say join ' ', map { sprintf "%.1f", $_ } src_simple \@in, 2;
  39   # 1.1 1.1 1.7 1.7 1.9 1.9 2.2 2.2 ...
  40
  41   # Very low quality sample rate halving
  42   say join ' ', src_simple [1 .. 10], 1/2, SRC_LINEAR, 1;
  43   # 1 2 4 6 8
  44
  45   # Halve first half, Double second half. Smooth transition.
  46   my $src = Audio::LibSampleRate->new(SRC_ZERO_ORDER_HOLD, 1);
  47   say join ' ', $src->process([1 ..  5], 1/2);  # 1 2 4
  48   say join ' ', $src->process([6 .. 10], 2, 1); # 6 8 9
  49   # (the doubling doesn't happen due to the smooth transition)
  50
  51   # Halve first half, Double second half. Step transition.
  52   $src->reset;
  53   say join ' ', $src->process([1 ..  5], 1/2);  # 1 2 4
  54   $src->set_ratio(2);
  55   say join ' ', $src->process([6 .. 10], 2, 1); # 6 6 7 7 8 8 9 9 10
  56
  57   say src_get_name SRC_SINC_FASTEST; # Fastest sinc interpolator
  58   say src_get_description SRC_SINC_FASTEST;
  59   # Band limited sinc interpolation, fastest, 97dB SNR, 80% BW.
  60
  61 =head1 DESCRIPTION
  62
  63 Secret Rabbit Code (aka libsamplerate) is a Sample Rate Converter for
  64 audio. One example of where such a thing would be useful is converting
  65 audio from the CD sample rate of 44.1kHz to the 48kHz sample rate used
  66 by DAT players.
  67
  68 SRC is capable of arbitrary and time varying conversions ; from
  69 downsampling by a factor of 256 to upsampling by the same factor.
  70 Arbitrary in this case means that the ratio of input and output sample
  71 rates can be an irrational number. The conversion ratio can also vary
  72 with time for speeding up and slowing down effects.
  73
  74 SRC provides a small set of converters to allow quality to be traded
  75 off against computation cost. The current best converter provides a
  76 signal-to-noise ratio of 145dB with -3dB passband extending from DC to
  77 96% of the theoretical best bandwidth for a given pair of input and
  78 output sample rates.
  79
  80 There are two interfaces: a simple procedural interface which converts
  81 a single block of samples in one go, and a more complex object
  82 oriented interface which can handle streaming data, for situations
  83 where the data is received in small pieces.
  84
  85 The underlying library also defines a callback interface, which is not
  86 yet implemented in Audio::LibSampleRate.
  87
  88 All functions and methods below die in case of error with a message
  89 containing the error number and description, as returned by SRC.
  90
  91 =head2 The simple interface
  92
  93 This interface consists of a single function, exported by default:
  94
  95 B<src_simple>(\I<@interleaved_frames>, I<$ratio>, I<$converter_type>, I<$channels>)
  96
  97 where I<@interleaved_frames> is an array of frames in interleaved
  98 format, I<$ratio> is the conversion ratio
  99 (C<output_sample_rate/input_sample_rate>), I<$converter_type> is the
 100 converter as described in the L</"Converter types"> section, and
 101 I<$channels> is the number of channels.
 102
 103 If not supplied, the I<$converter_type> defaults to the best available
 104 converter and I<$channels> defaults to 2 (stereo sound).
 105
 106 The function returns a list of samples, the result of the conversion.
 107
 108 =head2 The object oriented interface
 109
 110 The following methods are available:
 111
 112 =over 4
 113
 114 =item Audio::LibSampleRate->B<new>(I<$converter_type>, I<$channels>)
 115
 116 Creates a new Audio::LibSampleRate object. I<$converter_type> and
 117 I<$channels> have the same meaning and default values as in the
 118 previous section.
 119
 120 =item $self->B<process>(\I<@interleaved_frames>, I<$ratio>, I<$end_of_input>)
 121
 122 The most important function. I<@interleaved_frames> is an array of
 123 frames to be processed in interleaved format, I<$ratio> is the
 124 conversion ratio, and I<$end_of_input> is a boolean (defaulting to
 125 false) that should be true if this is the last piece of data, false
 126 otherwise.
 127
 128 The function returns a list of samples, the result of the conversion.
 129
 130 =item $self->B<reset>
 131
 132 This function resets the internal state of the Audio::LibSampleRate
 133 object. It should be called when the sample rate converter is used on
 134 two separate, unrelated blocks of audio.
 135
 136 =item $self->B<set_ratio>($new_ratio)
 137
 138 Normally, when updating the I<$ratio> argument in B<process> the
 139 library tries to smoothly transition between the previous and the
 140 current conversion ratios. This function changes the ratio without a
 141 smooth transition, achieving a step respone in the conversion ratio.
 142
 143 =back
 144
 145 =head2 Converter types
 146
 147 SRC currently offers 5 converters, numbered from 0 to 4. This module
 148 includes constants for the available converters, all of them exported
 149 by default.
 150
 151 =over 4
 152
 153 =item SRC_SINC_BEST_QUALITY
 154
 155 This is a bandlimited interpolator derived from the mathematical sinc
 156 function and this is the highest quality sinc based converter,
 157 providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels (dB)
 158 at a bandwidth of 97%.
 159
 160 This is the default converter for B<src_simple> and B<new>.
 161
 162 =item SRC_SINC_MEDIUM_QUALITY
 163
 164 This is another bandlimited interpolator much like the previous one.
 165 It has an SNR of 97dB and a bandwidth of 90%. The speed of the
 166 conversion is much faster than the previous one.
 167
 168 =item SRC_SINC_FASTEST
 169
 170 This is the fastest bandlimited interpolator and has an SNR of 97dB
 171 and a bandwidth of 80%.
 172
 173 =item SRC_ZERO_ORDER_HOLD
 174
 175 A Zero Order Hold converter (interpolated value is equal to the last
 176 value). The quality is poor but the conversion speed is blindlingly
 177 fast.
 178
 179 =item SRC_LINEAR
 180
 181 A linear converter. Again the quality is poor, but the conversion
 182 speed is blindingly fast.
 183
 184 =back
 185
 186 The library also includes two functions that provide human-readable
 187 information about converters. Both are exported by default.
 188
 189 =over
 190
 191 =item B<src_get_name>(I<$converter_type>)
 192
 193 Given a converter, returns its human-readable name.
 194
 195 =item B<src_get_description>(I<$converter_type>)
 196
 197 Given a converter, returns its human-readable description.
 198
 199 =back
 200
 201 =head1 SEE ALSO
 202
 203 L<http://www.mega-nerd.com/SRC/api.html>
 204
 205 =head1 AUTHOR
 206
 207 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 208
 209 =head1 COPYRIGHT AND LICENSE
 210
 211 Copyright (C) 2015 by Marius Gavrilescu
 212
 213 This program is free software; you can redistribute it and/or
 214 modify it under the terms of the GNU General Public License
 215 as published by the Free Software Foundation; either version 2
 216 of the License, or (at your option) any later version.
 217
 218 This program is distributed in the hope that it will be useful,
 219 but WITHOUT ANY WARRANTY; without even the implied warranty of
 220 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 221 GNU General Public License for more details.
 222
 223 You should have received a copy of the GNU General Public License
 224 along with this program; if not, write to the Free Software
 225 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 226 02110-1301, USA.
 227
 228
 229 =cut