Audio::SndFile(3)

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.