/ 
Audio-SndFile-0.09
River stage zero No dependents
/ Audio::SndFile

NAME

Audio::SndFile - Portable reading and writing of sound 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 (soundfile) library and provides a portable API for reading and writing sound files in different formats.

Reading & Writing

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

A list of name => value pairs. All required when reading raw data. Most are required when opening a file write-only.

type

The major filetype. Required when opening a file write-only.

subtype

The representation of data in the file. Required when opening a file write-only.

channels

The number of channels. Required when opening a file write-only.

endianness

The endianness of the data in the file.

samplerate

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);

Audio info

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".

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.

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.

Other file operations

Seek

$sndfile->seek($offset, $whence);

Seek to frame $offset. See also Fcntl and "seek" in perlfunc.

Sync

$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.

Truncate

$sndfile->truncate($number_of_frames);

Truncate file to $number_of_frames.

Implemented via sf_command().

Conversion parameters

Clipping

$sndfile->clipping($bool);
my $bool = $sndfile->clipping;

Get or set automatic clipping for float -> integer conversions.

Implemented via sf_command().

Other methods

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.

Implemented via sf_command().

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.

SF_COMMAND, LIBSNDFILE VERSIONS & API CHANGES

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.

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 are most of the sf_command() calls. They will be implemented later.

There is currently no way to read seperate channels into seperate buffers.

CHANGES

v0.09

Documentation updates. Documented changes for v0.08. Fixed MANIFEST to include test wav for fix in 0.08

v0.08

Tomas Doran fixed an issue with opening broken files. Added test case for this fix. See commit 24b54574a0a17a6c6f0fce033d62c2c0d8275361

v0.07

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

v0.06

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.

v0.05

Made the frames() method work and added regression test. Thanks to zergen for the bug report.

v0.04

Pushed the required perl version back to v5.6.0. If this breaks anything, please let me know.

v0.03

Added write_sync() method. Added some sf_command() methods. Documentation updates.

v0.02

Documentation updates.

v0.01

Initial version

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.

With bug fix by Tomas Doran <bobtfish@bobtfish.net>. Thanks!

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, 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.