The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
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.