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

VERSION
    Version 0.04_55

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::PCM::Extract;
        my $extractor = Audio::PCM::Extract->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.

SEE ALSO
    *       <http://en.wikipedia.org/wiki/Pulse-code_modulation> - PCM
            (Pulse-code modulation)

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.

