/ 
Audio-Extract-PCM-0.04_56
River stage one • 1 direct dependent • 1 total dependent
/ Audio::Extract::PCM

NAME

Audio::Extract::PCM - Extract PCM data from audio files

VERSION

Version 0.04_56

SYNOPSIS

This module's purpose is to extract PCM data from various audio formats. PCM is the format in which you send data to your sound card driver. This module aims to provide a single interface for PCM extraction from various audio formats, compressed and otherwise.

The distribution includes some backends which provide access to CPAN's audio decoding modules.

Usage example:

use Audio::Extract::PCM;
my $extractor = Audio::Extract::PCM->new('song.ogg');

$extractor->open(endian => 'native', samplesize => 2) or die $extractor->error;

warn "Sampling frequency is " . $extractor->format->freq;

my $l;
while ($l = $extractor->read(my $buf, bytes => 4096)) {
    print $buf;
}
die $extractor->error unless defined $l;

METHODS

new

Parameters: filename

Constructs a new object to access the specified file.

The extension of the filename will be used to determine which backends open() or pcm() will try.

pcm

Extracts all pcm data at once.

Returns a reference to a string buffer which contains PCM data. The format of these data can be found out using "format".

On error, an undefined value (or empty list) is returned.

Arguments are the same as to "open".

open

Opens the stream, initializes a backend.

Usage
$obj->open(
    freq       => 44100,
    samplesize => 2,
    channels   => 2,
    endian     => 'native',
);

If there is one single argument, it must be a Audio::Extract::PCM::Format object describing the desired format of the extracted PCM data.

Otherwise, the supplied arguments will be given to "new" in Audio::Extract::PCM::Format. See its documentation for details.

Note that not all backends support resampling and channel transformation, so if you don't really need 44100 Hz, better don't specify it. You'll probably get the best audio quality if you use the sample rate from the encoded file, which most backends use as default.

Return value

Another Audio::Extract::PCM::Format object which describes the actual format of the PCM data. They will be the same values as provided to this method, or some fitting values if no required values were specified. As I said, see "new" in Audio::Extract::PCM::Format for details.

read

Get decoded PCM samples. Use this only after a successful call to open.

Usage
$extractor->read(
    $buffer,          # an lvalue

    append => 1,      # Optional: append to buffer

    # Either a known amount of bytes:
    bytes => 4096,
    # or a known amount of time:
    seconds => 2.5,
);

The method will read at least as many bytes or seconds as specified. Under special circumstances (near the end of file), it may read less.

You shouldn't specify both bytes and seconds.

Maybe I'll get rid of the append option in future releases. And maybe of the at least.

"Strange" lvalues, like the return value of substr(), are not supported as the $buffer argument (yet?) -- at least for most backends.

Return value

If seconds were specified, the number of seconds of the read audio data will be returned. Otherwise, the number of read bytes will be returned. On eof, 0 will be returned. On error, undef will be returned (in scalar context), and the error may be retrieved via error().

error

Returns the last error that occured for this object.

Unfortunately this is often not very readable for computers. For instance, if the file couldn't be opened because it is not there, the various backends have different strings that describe this error.

Some of various possible errors:

"no suitable backend found"

This means that either there is no backend for this file type, or none of the possible backends have their dependencies installed, or none of the possible backends was able to satisfy the PCM format request (i.e. try a less specific format request).

format

Returns a Audio::Extract::PCM::Format object which describes the format of the extracted pcm data.

You should only call this method after a successfull call to "open" or "pcm". If you called "open", this method shall return the same format that "open" has returned.

EXPORTS

This module exports the following constants:

AEP  = "Audio::Extract::PCM"
AEPF = "Audio::Extract::PCM::Format"

This enables you to write:

use Audio::Extract::PCM;
my $aep = AEP->new($filename);

SEE ALSO

DEPENDENCIES

Apart from the dependencies that should be automatically installed by CPAN, there are some (optional) other dependencies. It's okay not to install all of them, especially if you don't need all file formats.

sox

An external audio processing program (should be in the PATH).

This is for the SoX backend (Audio::Extract::PCM::Backend::SoX). It will usually be used as a last resort, and it's quite clumsy as it uses an external program, and it doesn't support open/read yet (only pcm()). However, it supports a lot of formats.

Audio::Mad

Used for MP3 decoding (sox supports that too) by Audio::Extract::PCM::Backend::Mad. Please note that as of January 2009, there are some problems with this module (at least with recent perl and gcc versions), and you can find a patch by me at http://rt.cpan.org/Public/Bug/Display.html?id=42338.

Audio::Mad requires the libmad library, and its development headers for compiling.

Ogg::Vorbis::Decoder

This is used for Ogg/Vorbis decoding (sox supports that too) by Audio::Extract::PCM::Backend::Vorbis.

Ogg::Vorbis::Decoder requires the vorbis library, and its development headers for compiling.

Audio::SndFile

This is a module that supports a wide variety of audio formats and it is used by Audio::Extract::PCM::Backend::SndFile.

Audio::SndFile requires the libsndfile library, and its development headers for compiling.

libsndfile had been supporting mainly uncompressed formats for a while, but newer releases seem to support Ogg/Vorbis and FLAC too. At the moment the SndFile backend won't be tried for these formats because my system segfaults. Well, I'm going to make that configurable anyway.

About the vorbis support: As I understand it, libsndfile's read function isn't able to return an error status, while libvorbisfile's read function is. As both the Vorbis backend and libsndfile make use of libvorbisfile, you should use the former if you want to have full error control.

TODO / PLANS

  • Maybe I should add functionality for resampling and sample format transformation of the returned PCM data of any backend. Some backends (Mad, SoX) support it, but others don't (Vorbis). The point of the abstract interface is that the user needn't worry about the backends' capabilities, and he shouldn't have to know that he shouldn't try resampling for ogg files.

  • The list (and order) of the backends should be made configurable. For now it's hard-coded, which makes it more or less impossible to write new backend modules without changing this one, however I'm planning to change that.

  • Seeking.

If you have any good ideas how to implement these todo items, please let me know.

AUTHOR

Christoph Bussenius, <pepe at cpan.org>

Please include the name of this module in the subject of your emails so they won't get lost in spam.

If you find this module useful, I'll be glad if you drop me a note.

COPYRIGHT & LICENSE

Copyright 2008 Christoph Bussenius, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.