Audio::SndFile - Portable reading and writing of sound files
use Audio::SndFile; my $f = Audio::SndFile->open("<","audiofile.wav"); my $g = Audio::SndFile->open(">","audiofile.au", type => 'au', subtype => 'pcm_16', channels => 1, endianness => 'file'); my $buffer = ""; while ($f->read_int($buffer,1024)) { $g->write_int($buffer); }
Audio::SndFile is a perl interface to the sndfile (soundfile) library and provides a portable API for reading and writing sound files in different formats.
my $sndfile = Audio::SndFile->open($mode, $file, %options);
Creates an Audio::SndFile object from a file specification.
$mode can be "<" (read), ">" (write) or "+<" (read/write)
$file is a filehandle or filename.
A list of name => value pairs. All required when reading raw data. Most are required when opening a file write-only.
The major filetype. Required when opening a file write-only.
The representation of data in the file. Required when opening a file write-only.
The number of channels. Required when opening a file write-only.
The endianness of the data in the file.
The samplerate for this file.
The available values for type, subtype and endianness are listed in "FORMATS".
Examples:
# open for reading; no options are needed for non-raw # soundfiles: my $infile = Audio::SndFile->open("<","/tmp/test.wav"); # open for writing, you need type, subtype & channels options: my $outfile = Audio::SndFile->open(">","/tmp/out.wav", type => "wav", subtype => "pcm_16", channels => 2);
Information about the sound data is available from the Audio::SndFile object.
my $type = $sndfile->type; my $subtype = $sndfile->subtype; my $endianness = $sndfile->endianness; my $channels = $sndfile->channels; my $samplerate = $sndfile->samplerate;
These are the same as the open() options. The following are also available:
my $sections = $sndfile->sections; # number of sections my $bool = $sndfile->seekable; # is this stream/file seekable my $frames = $sndfile->frames; # number of frames
See also "FORMATS" and "Meta info".
Additional metadata
my $title = $sndfile->title(); my $copyright = $sndfile->copyright(); my $software = $sndfile->software(); my $artist = $sndfile->artist(); my $comment = $sndfile->comment(); my $date = $sndfile->date();
Read metadata from $sndfile. When given an argument, set the metadata on a $sndfile:
$sndfile->title($title); $sndfile->copyright($copyright); # etc.
These methods are not supported for all filetypes.
my $numsamples = $sndfile->read_TYPE($buffer,$num); my $numframes = $sndfile->readf_TYPE($buffer,$num);
Read max $num samples (single values) or frames (interleaved values; one value for each channel) from $sndfile into $buffer as a packed string of native endianness. TYPE may be one of "short", "int", "float" or "double". Values will be converted if necessary.
Returns the number of samples / frames read. $buffer will be shrunk or grown accordingly.
my @values = $sndfile->unpack_TYPE($num); my @values = $sndfile->unpackf_TYPE($num);
Same as read_TYPE and readf_TYPE, but returns the values as a list of scalars.
my $num = $sndfile->write_TYPE($buffer); my $num = $sndfile->writef_TYPE($buffer);
Write $buffer with packed samples or frames to $sndfile. TYPE may be one of "short", "int", "float" or "double". Returns the number of frames / samples written.
my $num = $sndfile->pack_TYPE(@values); my $num = $sndfile->packf_TYPE(@values);
Same as write_TYPE and writef_TYPE but these take a list of values instead of a packed string.
$sndfile->seek($offset, $whence);
Seek to frame $offset. See also Fcntl and "seek" in perlfunc.
$sndfile->write_sync();
Flush data to disk if $sndfile is opened for writing. This function is not available in libsndfile prior to 2006-07-31 / release 1.0.17.
You can use $sndfile->can('write_sync') to test for it.
$sndfile->can('write_sync')
$sndfile->truncate($number_of_frames);
Truncate file to $number_of_frames.
Implemented via sf_command().
$sndfile->clipping($bool); my $bool = $sndfile->clipping;
Get or set automatic clipping for float -> integer conversions.
Most methods throw an exception on error, but if you need to know:
my $enum = $sndfile->error; my $estring = $sndfile->strerror;
Return the last error as a number or string.
my $libsndfile_version = Audio::SndFile::lib_version;
Version of the libsndfile library linked by the module.
The exact list of supported file types is dependend on your libsndfile version. When building this module it tries to figure out which types are available. File types that are not supported by your libsndfile at the time of building this module will not be available. In other words: recompile this module after upgrading your libsndfile.
Supported file types (when available) in this version of Audio::SndFile are:
wav, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5, pvf, xi, htk, sds, avr, wavex, sd2, flac, caf.
Supported subtypes are:
pcm_s8, pcm_16, pcm_24, pcm_32, pcm_u8, float, double, ulaw, alaw, ima_adpcm, ms_adpcm, gsm610, vox_adpcm, g721_32, g723_24, g723_40, dwvw_12, dwvw_16, dwvw_24, dwvw_n, dpcm_8, dpcm_16.
These map to SF_FORMAT_$type in the C API.
See http://www.mega-nerd.com/libsndfile/api.html#open for the description of each (sub)type.
The following endianness specifications are supported:
file, big, little, cpu.
These map to SF_ENDIAN_$endianness in the C API.
Note that not all combinations of type, subtype and endianness are supported. See also http://www.mega-nerd.com/libsndfile/#Features.
As noted in "FORMATS", the supported file formats are dependent on the version of libsndfile that is installed at the time of building this module.
This is also true for the methods implemented via sf_command() and the write_sync() method. Available methods are detected by Makefile.PL at build time.
Methods implemented via sf_command() are noted in the documentation. Other methods, except for write_sync() should be available everywhere, since this module won't build if they're not available.
Currenly there are no known bugs, but this code is new and not very well tested.
This module does not implement the full libsndfile API. Notably missing are most of the sf_command() calls. They will be implemented later.
There is currently no way to read seperate channels into seperate buffers.
Documentation updates. Documented changes for v0.08. Fixed MANIFEST to include test wav for fix in 0.08
Tomas Doran fixed an issue with opening broken files. Added test case for this fix. See commit 24b54574a0a17a6c6f0fce033d62c2c0d8275361
Noticed that installation was aborting on systems with perl < 5.8.6. Moved minimum required version to 5.6.0 in all files. Let's see what breaks.
Fixed http://rt.cpan.org/Public/Bug/Display.html?id=32318
Fixed Makefile.PL to use LIBS correctly. Amongst other things, that means that it's now possible to build the module if your libsndfile shared library is in a non-standard location.
(get_/set_)artist, comment etc *should* now work, but need some serious testing.
Thanks to Paul Seelig for reporting the issues and helping me find the solution.
Made the frames() method work and added regression test. Thanks to zergen for the bug report.
Pushed the required perl version back to v5.6.0. If this breaks anything, please let me know.
Added write_sync() method. Added some sf_command() methods. Documentation updates.
Documentation updates.
Initial version
Erik de Castro Lopo's libsndfile page: http://www.mega-nerd.com/libsndfile/
Audio::SoundFile - an old(er) interface to libsndfile. Doesn't build on my perl and looks incomplete.
Audio::Play - play audio and read/write .au files.
Audio::LADSPA - process audio streams using LADSPA plugins.
Joost Diepenmaat, <joost@zeekat.nl>. http://zeekat.nl.
With bug fix by Tomas Doran <bobtfish@bobtfish.net>. Thanks!
Note: The following copyright & license only apply to this perl package (i.e. the "glue" to libsndfile). See http://www.mega-nerd.com/libsndfile/#Licensing for the license to libsndfile.
Copyright (C) 2006, 2012 Joost Diepenmaat, Zeekat Softwareontwikkeling
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.
To install Audio::SndFile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Audio::SndFile
CPAN shell
perl -MCPAN -e shell install Audio::SndFile
For more information on module installation, please visit the detailed CPAN module installation guide.