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

NAME

Audio::Extract::PCM::Backend - base class for audio extraction backends

SYNOPSIS

This is the base class for the backends for Audio::Extract::PCM. The backend classes provide a common interface to other modules:

Apart from these backends that are provided with this distribution, it should be fairly easy (and soon fully documented) to design backends to interface with other modules/libraries/codecs.

Ideally, Audio::Extract::PCM should find an appropriate backend for a given file automatically.

INHERITANCE

This module inherits from Class::Accessor::Fast. If you write your own backend, you should inherit from this class and thus you can add your own accessors using CA's API.

ACCESSORS

filename

The file name. This is expected to be given to the constructor.

error

Contains the description of the last error.

format

Contains a Audio::Extract::PCM::Format object describing the format of the PCM data after a successfull call to "pcm" or "open".

METHODS

new

Constructor. Accepts key-value pairs as arguments (i.e. not a hash reference like Class::Accessor's constructor).

pcm

Extract all pcm data from the file.

In your backend, you should not override this method. Rather you provide open_back and (optionally) pcm_back methods. If you provide a pcm_back method, it will be used to extract the audio data. Otherwise, your open_back and read_back methods will be used.

The single parameter for both pcm and pcm_back is a Audio::Extract::PCM::Format object which describes the desired format of the PCM data.

If you provide a pcm_back method, it is supposed to store the actual PCM format with the "format" accessor.

The return value is a reference to the PCM string buffer.

On error, undef is returned (in scalar context) and the error should be set with the /error accessor.

open

Open, i.e. prepare for "read".

You should not override this method but rather provide a open_back method with the same specifications.

The argument is a Audio::Extract::PCM::Format object which describes the desired format of the PCM data.

The return value is another format object which describes the actual format of the audio data. You need not bother setting the "format" accessor in open_back; open does this for you.

On error, undef is returned (in scalar context) and the error should be set with the /error accessor.

If the backend decides that it cannot open the file but some other backend might be able to, the string "trynext" should be returned. If open_back returns a format that does not satisfy the format request, open treats this as though open_back had returned "trynext".

read

The backend should provide a read_back method which will be called like this:

$backend->read_back(
    $buffer,           # lvalue

    bytes => 100000,   # how many bytes to read at least.  Should default
                       # to all bytes

    append => 1,       # If this is specified, the buffer shall be appended to.
                       # Some backends can do this efficiently.
);

The buffer shall be an lvalue, but the backend need not care about "strange" lvalues like substr(). This would be too troublesome because many backends make use of XS modules.

In scalar context, read_back shall return the number of bytes read, 0 on eof and undef on error.