NAME
Audio::SndFile - Portable reading and writing of audio files
SYNOPSIS
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);
}DESCRIPTION
Audio::SndFile is a perl interface to the sndfile library and provides a portable API for reading and writing audio data in different formats.
API
Constructor
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.
%options: if you're opening a file write-only, you should specify at least the options "type", "subtype" and "channels". The default endianness is "file". See also "FORMATS"
File info
my $type = $sndfile->type;
my $subtype = $sndfile->subtype;
my $endianness = $sndfile->endianness;
my $channels = $sndfile->channels;
my $samplerate = $sndfile->samplerate;
my $sections = $sndfile->sections;
my $bool = $sndfile->seekable;
my $frames = $sndfile->frames;Read info from an Audio::SndFile object. See also "FORMATS" and "Meta info".
Read audio data
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.
Write audio data
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.
Seek
$sndfile->seek($offset, $whence);Seek to frame $offset. See also Fcntl and "seek" in perlfunc.
Errors
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.
lib_version
my $libsndfile_version = Audio::SndFile::lib_version;Version of the libsndfile library linked by the module.
Meta info
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.
$sndfile->title($title);
$sndfile->copyright($copyright);
# etc.Set metadata for $sndfile. These methods are not supported for all filetypes.
FORMATS
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.
BUGS & ISSUES.
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 is a decent way of using the sf_command() calls. This will be implemented later.
There is currently no way to read seperate channels into seperate buffers.
CHANGES
SEE ALSO
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.
AUTHOR
Joost Diepenmaat, <joost@zeekat.nl>. http://zeekat.nl.
COPYRIGHT AND LICENSE
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 by 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.