/ 
Audio-PortAudio-0.03
River stage one • 1 direct dependent • 1 total dependent
/ Audio::PortAudio

NAME

Audio::PortAudio - portable audio I/O

SYNOPSIS

   my $api = Audio::PortAudio::default_host_api();
   my $device = $api->default_input_device;
   
   my $stream = $device->open_read_stream( {
	channel_count => 2,
        sample_format => 'float32'
     },
     $sample_rate,
     $frames_per_buffer, 
     $stream_flags
   );
 
   my $buffer = "";
   while (1) {
     $stream->read($buffer,$number_of_frames);
     my @samples = unpack("f".($number_of_frames * $num_channels));
   }

DESCRIPTION

Audio::PortAudio is an object oriented interface to the PortAudio library ( http://www.portaudio.com/ ). It provides flexible multi-channel audio input & output on a variety of different platforms.

PortAudio is not a music playing / mixing library. PortAudio provides direct access to the audio inputs and outputs using raw sample data at a fixed sample rate.

The PortAudio library is available for many platforms including Windows, Macintosh (8,9,X), Unix / Linux (OSS, ALSA & JACK), SGI, and BeOS. Recent linux distributions should have it as a package, otherwise get it at http://www.portaudio.com/

PROGRAMMING INTERFACE

PortAudio IO is implemented using Audio::PortAudio::Stream objects. To create a stream you need to select a host API and a device first.

Audio::PortAudio

host_apis

my @apis = Audio::PortAudio::host_apis();

Returns a list of all available host APIs.

default_host_api

my $api = Audio::PortAudio::default_host_api();

Get the default host API.

version

my $version_number = Audio::PortAudio::version();

The version number of the portaudio library.

version_text

my $version = Audio::PortAudio::version_text();

Human readable version information from the portaudio library.

error_text

my $text = Audio::PortAudio::error_text($error_num);

Translate an error number into a human readable error text.

is_format_supported

my $error = is_format_supported($input_parameters,$output_parameters,$sample_rate);

$error is not 0 if the specified format isn't available. You can use error_text() to translate the $error.

open_read_stream

 my $stream = Audio::PortAudio::open_read_stream(
	$stream_parameters,
	$sample_rate,
	$frames_per_buffer,
	$stream_flags
 );

Open a stream for reading only.

open_write_stream

 my $stream = Audio::PortAudio::open_write_stream(
	$stream_parameters,
	$sample_rate,
	$frames_per_buffer,
	$stream_flags
 );

Open a stream for writing only.

open_stream / open_rw_stream

 my $stream = Audio::PortAudio::open_rw_stream(
	$input_stream_parameters,
	$output_stream_parameters,
	$sample_rate,
	$frames_per_buffer,
	$stream_flags
 );

Open a stream for reading and writing.

stream parameters

Stream parameters as specified for the open_*stream calls are hash refs with the following keys:

device

The Audio::PortAudio::Device to use.

channel_count

The number of channels to use

sample_format

One of 'float32', 'int16', 'int32', 'int24', 'int8', 'uint8'.

Default is 'float32'.

latency

Suggest latency in seconds (floating point).

stream flags

Stream flags is an integer containing a binary or of zero or more of the following constants in Audio::PortAudio::Stream:

CLIP_OFF

No clipping

DITHER_OFF

No dithering

NEVER_DROP_INPUT

This is probably not a valid option for blocking IO.

Audio::PortAudio::HostAPI

name

my $name = $api->name;

Human readable name for this API (OSS, ALSA ...)

devices

my @devices = $api->devices;

Returns all available Audio::PortAudio::Devices for this host API.

default_input_device

my $device = $api->default_input_device;

Get the default device for this API.

default_output_device

my $device = $api->default_output_device;

Get the default device for this API.

Audio::PortAudio::Device

name

my $name = $device->name;

Returns the human readable name of this device.

host_api

my $api =  $device->host_api;

The API that provides this device.

max_input_channels

my $max = $device->max_input_channels;

Maximum number of input channels available for this device. Channels are always monophonic, so there should be two channels for each stereo input.

max_output_channels

my $max = $device->max_output_channels;

Maximum number of output channels available for this device.

default_low_input_latency, default_high_input_latency, default_low_output_latency, default_high_output_latency

my $latency = $device->default_low_input_latency;
# etc.

Default latencies for this device in seconds (floating point).

open_read_stream, open_write_stream, open_stream, open_rw_stream

 my $stream = $device->open_read_stream( 
	$stream_parameters, 
	$sample_rate, 
	$frames_per_buffer, 
	$stream_flags
 );

 my $stream = $device->open_rw_stream( 
	$input_stream_parameters, 
	$output_stream_parameters, 
	$sample_rate, 
	$frames_per_buffer, 
	$stream_flags
 );

Like their counterparts in Audio::PortAudio, only default to the $device.

Audio::PortAudio::Stream

Currently blocking IO only.

read

my $buffer = "";
$stream->read($buffer,$frames);

Fill buffer with $frames * channels samples. Samples are interleaved and packed in the format as specified during open_stream.

write

$stream->write($buffer);

Write $buffer to $stream. Samples should be in the format specified during open_stream.

close

$stream->close;

Flush buffers (if writing) and close stream. Called automatically on destruction of $stream.

read_available;

my $frames = $stream->read_available;

Number of frames that can be read before read() will block.

write_available;

my $frames = $stream->write_available;

Number of frames that can be written before write() will block.

CHANGES

 0.03 - distribution/building improvements only:
	now uses pkg-config (if available) to detect portaudio version
        and LIBS flags
	moved vumeter example to eg directory
	removed Makefile from distribution

 0.02 - fixed makefile; no longer reports dependency on Audio::SndFile
	fixed embarrassing typo in the name of this document :-)
      - fixed some conversion problems with multiple channels

 0.01 - initial release

COPYRIGHT AND LICENSE

Audio::PortAudio perl modules for portable audio I/O
Copyright (C) 2007  Joost Diepenmaat.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

See the COPYING file for more information.