NAME

Audio::Extract::PCM::Format - Format of PCM data

SYNOPSIS

This class is used by Audio::Extract::PCM and its backends to represent the format of PCM data.

ACCESSORS

freq

Also known as the sample rate, in samples per second.

samplesize

In bytes per sample.

endian

The string little or big. The constructor also accepts the string native.

channels

A number.

signed

1 or 0, which means signed or unsigned, respectively.

duration

(seconds, may be fractional)

Of course, it doesn't make sense to specify the duration when you call "open" in Audio::Extract::PCM, however it will return you an object that has a duration field, but it may be undefined if the backend does not support getting the duration.

Once you have extracted all the pcm data, you can get the duration in seconds using the formula:

pcm_buffer_length / samplesize / channels / freq

METHODS

new

Constructor. You'll probably call this when you want to call "open" in Audio::Extract::PCM or "pcm" in Audio::Extract::PCM. In this case, the following semantics apply:

Specify required values for frequency (samples per second), samplesize (bytes per sample), channels, endianness and signedness:

Audio::Extract::PCM::Format->new(
    freq => 44100,
    samplesize => 2,
    channels => 2,
    endian => 'native',
    signed => 1,
);

If you omit a specification (or it is "undef"), the value will be chosen by the back-end.

Additionally, there are some special ways to say what you want:

Audio::Extract::PCM::Format->new(

    # The frequency *must* be one of 44100, 48000
    freq => [44100, 48000],

    # If *possibly*, you would like little endian, but you accept other
    # values too (aka "nice-to-have" values):
    endian => \['little'],
);

Finally, there is a short form:

Audio::Extract::PCM::Format->new($freq, $samplesize, $channels);

This is equivalent to:

Audio::Extract::PCM::Format->new(
    freq        => $freq,
    samplesize  => $samplesize,
    channels    => $channels,
    endian      => 'native',
    signed      => 1,
);

findvalue

This is a useful method if you want to write your own backend. You give it a list of the formats that your backend can provide, and it tells you which one fits the user's wishes best (according to the rules described under "new").

See the source of the provided backends for how to use it.

combine

Argument: another format object

Combines the values of two format objects. Modifies $this and returns it.

satisfied

Argument: another format object

If more than one argument is given, the arguments will be interpreted like those of "new".

Returs whether the other format satisfies all required properties of this object.