NAME

Audio::Audiere - use the Audiere sound library in Perl

SYNOPSIS

        use Audio::Audiere qw/AUDIO_STREAM AUDIO_BUFFER/;
        use strict;
        use warnings;

        my $audiere = Audio::Audiere->new();

        if ($audiere->error())
          {
          die ("Cannot get audio device: ". print $audiere->error());
          }

        # now we have the driver, add some sound streams

        # stream the sound from the disk
        my $stream = $audiere->addStream( 'media/sample.ogg', AUDIO_STREAM);

        # always check for errors:
        if ($stream->error())
          {
          print "Cannot load sound: ", $stream->error(),"\n";
          }
        
        # load sound into memory (if possible), this is also the default
        my $sound = $audiere->addStream( 'media/effect.wav', AUDIO_BUFFER);
        
        # always check for errors:
        if ($sound->error())
          {
          print "Cannot load sound: ", $sound->error(),"\n";
          }

        $stream->setVolume(0.5);        # 50%
        $stream->setRepeat(1);          # loooop
        if ($stream->isSeekable())
          {
          $stream->setPosition(100);    # skip some bit
          }
        $stream->play();                # start playing
        
        $sound->play();                 # start playing

        # free sound device is not neccessary, will be done automatically

EXPORTS

Exports nothing on default. Can export AUDIO_BUFFER and AUDIO_STREAM, as well as the following constants for file formats:

        FF_AUTODETECT
        FF_WAV
        FF_OGG
        FF_FLAC
        FF_MP3
        FF_MOD

Also, the following sample source format constants can be exported:

        SF_U8
        SF_S16

DESCRIPTION

This package provides you with an interface to the audio library Audiere.

METHODS

new()

        my $audiere = Audio::Audiere->new( $devicename, $parameters );

Creates a new object that holds the Audiere driver to the optional $devicename and the optional C$parameters>.

The latter is a comma-separated list like buffer=100,rate=44100.

When $audiere goes out of scope or is set to undef, the device will be automatically released.

In case you wonder how you can play multiple sounds at once with only once device: these are handled as separate streams, and once you have the device, you can add (almost infinitely) many of them via addStream (or any of the other add...() methods.

In theory you can open more than one device, however, in praxis usually only one of them is connected to the sound output, so this does not make much sense.

getVersion

        print $audiere->getVersion();

Returns the version of Audiere you are using as string.

getName

        print $audiere->getName();

Returns the name of the audio device, like 'oss' or 'directsound'.

addStream

        $stream = $audiere->addStream( $file, $stream_flag )

Create a new sound stream object from $file, and return it.

See "METHODS ON STREAMS" on what methods you can use to manipulate the stream object. Most popular will be play(), of course :)

You should always check for errors before using the stream object:

        if ($stream->error())
          {
          print "Cannot load sound: ", $stream->error(),"\n";
          }

addTone

        $audiere->addTone( $frequenzy );

Create a stream object that produces a tone at the given $frequenzy.

See also addStream and Audio::Audiere::Stream.

addSquareWave

        $audiere->addSquareWave( $frequenzy );

Create a stream object that produces a swaure wave at the given $frequenzy.

See also addStream and Audio::Audiere::Stream.

addWhiteNoise

        $audiere->addWhiteNoise( );

Create a stream object that produces white noise.

See also addStream and Audio::Audiere::Stream.

addPinkNoise

        $audiere->addPinkNoise( );

Create a stream object that produces pink noise, which is noise with an equal power distribution among octaves (logarithmic), not frequencies.

See also addStream and Audio::Audiere::Stream.

dropStream

        $audiere->dropStream($stream);

This will stop the sound playing from this stream and release it's memory. You can also do it like this or just have $stream go out of scope:

        $stream = undef;

dupeStream

        $second_stream = $audiere->dupeStream($stream);
        $second_stream = $stream->copy();

Create a copy of a stream. The streams will share the memory for the sound data, but have separate volumes, positions, pan etc.

setMasterVolume

        my $new_vol = $audiere->setMasterVolume(0.1);   # = 0.1 (10%)

Sets a new master volume for all (non-3D) streams. The actual volume of a stream will be $master * $local e.g. a stream with a volume of 0.5 and a master volume of also 0.5 would result in an actual volume of 0.25.

getMasterVolume

        my $vol = $audiere->getMasterVolume();

Return the master volume for (non-3D) streams. See setMasterVolume and set3DMasterVolume.

Methods for 3D support

add3DStream

getListenerPosition

setListenerPosition

getListenerRotation

setListenerRotation

update3D

set3dMasterVolume

        my $new_vol = $audiere->set3DMasterVolume(0.1); # = 0.1 (10%)

Sets a new master volume for all 3D streams. The actual volume of a stream will be $master * $local e.g. a stream with a volume of 0.5 and a master volume of also 0.5 would result in an actual volume of 0.25.

get3DMasterVolume

Return the master volume for all 3D streams. See set3DMasterVolume and setMasterVolume.

See also Audio::Audiere::Stream and Audio::Audiere::Stream::3D for a list of methods you can call on 2D and 3D sound streams.

AUTHORS

(c) 2004 Tels <http://bloodgate.com/>

SEE ALSO

http://audiere.sf.net/