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:
Audio::Extract::PCM::Backend::SoX - uses the external "sox" program
Audio::Extract::PCM::Backend::Vorbis - uses Ogg::Vorbis::Decoder
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.
used_versions
Should be implemented by the backends to describe the versions of the modules, libraries and other pieces of software that are being used.
Should return a hash reference where the keys are the names of the products, and the values are their versions. The versions may be strings of any kind (or objects that can be stringified). The intend is to provide an easy way to show the user what software was used.