NAME

Audio::DSP - Perl interface to *NIX digital audio device.

SYNOPSIS

use Audio::DSP;

($buf, $chan, $fmt, $rate) = (4096, 1, 8, 8192);

$dsp = new Audio::DSP(buffer   => $buf,
                      channels => $chan,
                      format   => $fmt,
                      rate     => $rate);

$seconds = 5;
$length  = ($chan * $fmt * $rate * $seconds) / 8;

$dsp->init() || die $dsp->errstr();

# Record 5 seconds of sound
for (my $i = 0; $i < $length; $i += $buf) {
    $dsp->read() || die $dsp->errstr();
}

# Play it back
for (;;) {
    $dsp->write() || last;
}

$dsp->close();

DESCRIPTION

Audio::DSP is built around the OSS (Open Sound System) API and allows perl to interface with a digital audio device. The Audio::DSP object stores I/O parameters and also supplies temporary storage for raw audio data.

In order to use Audio::DSP, you'll need to have the necessary OSS drivers/includes installed. OSS is available for many popular Unices, and a GPLed version (with which this extension was developed and tested) is distributed with with the Linux kernel.

CONSTRUCTOR

new([params])

Returns new Audio::DSP object. Parameters:

device

Name of audio device file. Default is "/dev/dsp".

buffer

Length of buffer, in bytes, for reading from/writing to the audio device file. Default is 4096.

rate

Sampling rate in bytes per second. Default is 8192.

format

Sample format. This parameter affects not only the size and the byte-order of a sample, but also its dynamic range.

Sample format may be specified as an integer (e.g. 8 or 16) or as a string corresponding to the formats defined in "#soundcard.h". The latter is preferred; an integer value of 16 (for example) corresponds to little endian signed 16 (AFMT_S16_LE), which format may or may not work with your card. So be careful. Formats are:

AFMT_QUERY: Used to query current audio format, and useless in this context. See the Audio::DSP::queryformat method for getting the currently used format of an initialized audio device.
AFMT_MU_LAW: logarithmic mu-Law
AFMT_A_LAW: logarithmic A-Law
AFMT_IMA_ADPCM: 4:1 compressed (IMA)
AFMT_U8: 8 bit unsigned
AFMT_S16_LE: 16 bit signed little endian (Intel - used in PC soundcards)
AFMT_S16_BE: 16 bit signed big endian (PPC, Sparc, etc)
AFMT_S8: 8 bit signed
AFMT_U16_LE: 16 bit unsigned little endian
AFMT_U16_BE: 16 bit unsigned bit endian
AFMT_MPEG: MPEG (currently not supported by OSS)

Default is AFMT_U8.

channels

1 (mono) or 2 (stereo). Default is 1.

file

File from which to read raw sound data to be stored in the Audio::DSP object.

No effort is made to interpret the type of file being read. It's up to you to set the appropriate rate, channel, and format parameters if you wish to write the sound data to your audio device without damaging your hearing.

METHODS

audiofile($filename)

Reads data from specified file and stores it in the Audio::DSP object. If there is already sound data stored in the object, the file data will be concatenated onto the end of it.

$dsp->audiofile("foo.raw") || die $dsp->errstr();

Returns true on success, false on error.

clear()

Clears audio data currently stored in Audio::DSP object, sets play mark to zero. No return value.

close()

Closes audio device file. Returns true on success, false on error.

data()

Returns sound data stored in Audio::DSP object.

open RAWFILE, ">foo.raw";
print RAWFILE $dsp->data();
close RAWFILE;

datacat($data)

Concatenates argument (a string) to audio data stored in Audio::DSP object. Returns length of audio data currently stored.

datalen()

Returns length of audio data currently stored in Audio::DSP object.

errstr()

Returns last recorded error.

getformat($format)

Returns true if specified sample format is supported by audio device. A false value may indicate the format is not supported, but it may also mean that the SNDCTL_DSP_GETFMTS ioctl failed (the Audio::DSP::init method must be called before this method), etc. Be sure to check the last error message in this case.

init([params])

Opens and initializes audio device file. Parameters device, buffer, rate, format, and channels are shared with the constructor, and will override them. Other parameters:

mode

Mode in which to open audio device file. Accepted values:

"O_RDONLY" (read-only)
"O_WRONLY" (write-only)
"O_RDWR" (read-write)

The default value is "O_RDWR".

Example:

$dsp->init(mode => "O_RDONLY") || die $dsp->errstr();

Returns true on success, false on error.

post()

Sends SNDCTL_DSP_POST ioctl message to audio device file. Returns true on success, false on error. The Audio::DSP::init method must be called before this method.

queryformat()

Returns currently used format of initialized audio device. Unlike the Audio::DSP::setformat method, queryformat "asks" the audio device directly which format is being used. The Audio::DSP::init method must be called before this method.

read()

Reads buffer length of data from audio device file and appends it to the audio data stored in Audio::DSP object. Returns true on success, false on error.

setbuffer([$length])

Sets read/write buffer if argument is provided.

Returns buffer length currently set in Audio::DSP object.

setrate([$rate])

Sets number of channels if argument is provided. If the audio device file is open, the number of channels will not actually be changed until you call close() and init() again.

Returns number of channels currently set in Audio::DSP object.

setdevice([$device_name])

Sets audio device file if argument is provided. If the device is open, it will not actually be changed until you call close() and init() again.

Returns audio device file name currently set in Audio::DSP object.

setformat([$bits])

Sets sample format if argument is provided. If the audio device file is open, the sample format will not actually be changed until you call close() and init() again.

Returns sample format currently set in Audio::DSP object.

setmark([$mark])

Sets play mark if argument is provided. The play mark indicates how many bites of audio data stored in the Audio::DSP object have been written to the audio device file since the mark was last set to zero. This lets the Audio::DSP::write method know what to write.

Returns current play mark.

setrate([$rate])

Sets sample rate if argument is provided. If the audio device file is open, the sample rate will not actually be changed until you call close() and init() again.

Returns sample rate currently set in Audio::DSP object.

sync()

Sends SNDCTL_DSP_SYNC ioctl message to audio device file. Returns true on success, false on error. The Audio::DSP::init method must be called before this method.

write()

Writes buffer length of sound data currently stored in Audio::DSP object, starting at the current play mark offset, to audio device file. Play mark is incremented one buffer length. Returns true on success, false on error or if the play mark exceeds the length of audio data stored in the Audio::DSP object.

NOTES

Audio::DSP does not provide any methods for converting the raw audio data stored in its object into other formats (that's another project altogether). You can, however, use the Audio::DSP::data method to dump the raw audio to a file, then use a program like sox to convert it to your favorite format. If you are interested in writing .wav files, you may want to take a look at Nick Peskett's Audio::Wav module.

TO DO

Implement PerlIO.

AUTHOR

Seth David Johnson, affection@pdamusic.com

COPYRIGHT

To install Audio::DSP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Audio::DSP

CPAN shell

perl -MCPAN -e shell
install Audio::DSP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)