Audio System (aud)

This module provides access to the audaspace audio library.

Basic Sound Playback

This script shows how to use the classes: Device, Factory and Handle.

import aud

device = aud.device()
# load sound file (it can be a video file with audio)
factory = aud.Factory('music.ogg')

# play the audio, this return a handle to control play/pause
handle = device.play(factory)
# if the audio is not too big and will be used often you can buffer it
factory_buffered = aud.Factory.buffer(factory)
handle_buffered = device.play(factory_buffered)

# stop the sounds (otherwise they play until their ends)
handle.stop()
handle_buffered.stop()

aud.AUD_DEVICE_JACK

constant value 3

aud.AUD_DEVICE_NULL

constant value 0

aud.AUD_DEVICE_OPENAL

constant value 1

aud.AUD_DEVICE_SDL

constant value 2

aud.AUD_DISTANCE_MODEL_EXPONENT

constant value 5

aud.AUD_DISTANCE_MODEL_EXPONENT_CLAMPED

constant value 6

aud.AUD_DISTANCE_MODEL_INVALID

constant value 0

aud.AUD_DISTANCE_MODEL_INVERSE

constant value 1

aud.AUD_DISTANCE_MODEL_INVERSE_CLAMPED

constant value 2

aud.AUD_DISTANCE_MODEL_LINEAR

constant value 3

aud.AUD_DISTANCE_MODEL_LINEAR_CLAMPED

constant value 4

aud.AUD_FORMAT_FLOAT32

constant value 36

aud.AUD_FORMAT_FLOAT64

constant value 40

aud.AUD_FORMAT_INVALID

constant value 0

aud.AUD_FORMAT_S16

constant value 18

aud.AUD_FORMAT_S24

constant value 19

aud.AUD_FORMAT_S32

constant value 20

aud.AUD_FORMAT_U8

constant value 1

aud.AUD_STATUS_INVALID

constant value 0

aud.AUD_STATUS_PAUSED

constant value 2

aud.AUD_STATUS_PLAYING

constant value 1

device()

Returns the application’s Device.

return:The application’s Device. rtype:Device

class aud.Device

Device objects represent an audio output backend like OpenAL or SDL, but might also represent a file output or RAM buffer output.

lock()

Locks the device so that it’s guaranteed, that no samples are read from the streams until unlock() is called. This is useful if you want to do start/stop/pause/resume some sounds at the same time.

Note

The device has to be unlocked as often as locked to be able to continue playback.

Warning

Make sure the time between locking and unlocking is as short as possible to avoid clicks.

play(factory, keep=False)

Plays a factory.

Parameters:

• factory (Factory) – The factory to play.
• keep (bool) – See Handle.keep.

Returns:

The playback handle with which playback can be controlled with.

Return type:

Handle

stopAll()

Stops all playing and paused sounds.

unlock()

Unlocks the device after a lock call, see lock() for details.

channels

The channel count of the device.

distance_model

The distance model of the device.

See also

http://connect.creativelabs.com/openal/Documentation/OpenAL%201.1%20Specification.htm#_Toc199835864

doppler_factor

The doppler factor of the device. This factor is a scaling factor for the velocity vectors in doppler calculation. So a value bigger than 1 will exaggerate the effect as it raises the velocity.

format

The native sample format of the device.

listener_location

The listeners’s location in 3D space, a 3D tuple of floats.

listener_orientation

The listener’s orientation in 3D space as quaternion, a 4 float tuple.

listener_velocity

The listener’s velocity in 3D space, a 3D tuple of floats.

rate

The sampling rate of the device in Hz.

speed_of_sound

The speed of sound of the device. The speed of sound in air is typically 343 m/s.

volume

The overall volume of the device.

class aud.Factory

Factory objects are immutable and represent a sound that can be played simultaneously multiple times. They are called factories because they create reader objects internally that are used for playback.

file(filename)

Creates a factory object of a sound file.

Parameters:filename (string) – Path of the file. Returns:The created Factory object. Return type:Factory

Warning

If the file doesn’t exist or can’t be read you will not get an exception immediately, but when you try to start playback of that factory.

sine(frequency, rate=44100)

Creates a sine factory which plays a sine wave.

Parameters:

• frequency (float) – The frequency of the sine wave in Hz.
• rate (int) – The sampling rate in Hz. It’s recommended to set this value to the playback device’s samling rate to avoid resamping.

Returns:

The created Factory object.

Return type:

Factory

buffer()

Buffers a factory into RAM. This saves CPU usage needed for decoding and file access if the underlying factory reads from a file on the harddisk, but it consumes a lot of memory.

Returns:The created Factory object. Return type:Factory

Note

Only known-length factories can be buffered.

Warning

Raw PCM data needs a lot of space, only buffer short factories.

delay(time)

Delays by playing adding silence in front of the other factory’s data.

Parameters:time (float) – How many seconds of silence should be added before the factory. Returns:The created Factory object. Return type:Factory

fadein(start, length)

Fades a factory in by raising the volume linearly in the given time interval.

Parameters:

• start (float) – Time in seconds when the fading should start.
• length (float) – Time in seconds how long the fading should last.

Returns:

The created Factory object.

Return type:

Factory

Note

Before the fade starts it plays silence.

fadeout(start, length)

Fades a factory in by lowering the volume linearly in the given time interval.

Parameters:

• start (float) – Time in seconds when the fading should start.
• length (float) – Time in seconds how long the fading should last.

Returns:

The created Factory object.

Return type:

Factory

Note

After the fade this factory plays silence, so that the length of the factory is not altered.

filter(b, a = (1))

Filters a factory with the supplied IIR filter coefficients. Without the second parameter you’ll get a FIR filter. If the first value of the a sequence is 0 it will be set to 1 automatically. If the first value of the a sequence is neither 0 nor 1, all filter coefficients will be scaled by this value so that it is 1 in the end, you don’t have to scale yourself.

Parameters:

• b (sequence of float) – The nominator filter coefficients.
• a (sequence of float) – The denominator filter coefficients.

Returns:

The created Factory object.

Return type:

Factory

highpass(frequency, Q=0.5)

Creates a second order highpass filter based on the transfer function H(s) = s^2 / (s^2 + s/Q + 1)

Parameters:

• frequency (float) – The cut off trequency of the highpass.
• Q (float) – Q factor of the lowpass.

Returns:

The created Factory object.

Return type:

Factory

join(factory)

Plays two factories in sequence.

Parameters:factory (Factory) – The factory to play second. Returns:The created Factory object. Return type:Factory

Note

The two factories have to have the same specifications (channels and samplerate).

limit(start, end)

Limits a factory within a specific start and end time.

Parameters:

• start (float) – Start time in seconds.
• end (float) – End time in seconds.

Returns:

The created Factory object.

Return type:

Factory

loop(count)

Loops a factory.

Parameters:count (integer) – How often the factory should be looped. Negative values mean endlessly. Returns:The created Factory object. Return type:Factory

Note

This is a filter function, you might consider using Handle.loop_count instead.

lowpass(frequency, Q=0.5)

Creates a second order lowpass filter based on the transfer function H(s) = 1 / (s^2 + s/Q + 1)

Parameters:

• frequency (float) – The cut off trequency of the lowpass.
• Q (float) – Q factor of the lowpass.

Returns:

The created Factory object.

Return type:

Factory

mix(factory)

Mixes two factories.

Parameters:factory (Factory) – The factory to mix over the other. Returns:The created Factory object. Return type:Factory

Note

The two factories have to have the same specifications (channels and samplerate).

pingpong()

Plays a factory forward and then backward. This is like joining a factory with its reverse.

Returns:The created Factory object. Return type:Factory

pitch(factor)

Changes the pitch of a factory with a specific factor.

Parameters:factor (float) – The factor to change the pitch with. Returns:The created Factory object. Return type:Factory

Note

This is done by changing the sample rate of the underlying factory, which has to be an integer, so the factor value rounded and the factor may not be 100 % accurate.

Note

This is a filter function, you might consider using Handle.pitch instead.

reverse()

Plays a factory reversed.

Returns:The created Factory object. Return type:Factory

Note

The factory has to have a finite length and has to be seekable. It’s recommended to use this only with factories with fast and accurate seeking, which is not true for encoded audio files, such ones should be buffered using buffer() before being played reversed.

Warning

If seeking is not accurate in the underlying factory you’ll likely hear skips/jumps/cracks.

square(threshold = 0)

Makes a square wave out of an audio wave by setting all samples with a amplitude >= threshold to 1, all <= -threshold to -1 and all between to 0.

Parameters:threshold (float) – Threshold value over which an amplitude counts non-zero. Returns:The created Factory object. Return type:Factory

volume(volume)

Changes the volume of a factory.

Parameters:volume (float) – The new volume.. Returns:The created Factory object. Return type:Factory

Note

Should be in the range [0, 1] to avoid clipping.

Note

This is a filter function, you might consider using Handle.volume instead.

class aud.Handle

Handle objects are playback handles that can be used to control playback of a sound. If a sound is played back multiple times then there are as many handles.

pause()

Pauses playback.

Returns:Whether the action succeeded. Return type:bool

resume()

Resumes playback.

Returns:Whether the action succeeded. Return type:bool

stop()

Stops playback.

Returns:Whether the action succeeded. Return type:bool

Note

This makes the handle invalid.

attenuation

This factor is used for distance based attenuation of the source.

See also

Device.distance_model

cone_angle_inner

The opening angle of the inner cone of the source. If the cone values of a source are set there are two (audible) cones with the apex at the location of the source and with infinite height, heading in the direction of the source’s orientation. In the inner cone the volume is normal. Outside the outer cone the volume will be cone_volume_outer and in the area between the volume will be interpolated linearly.

cone_angle_outer

The opening angle of the outer cone of the source.

See also

cone_angle_inner

cone_volume_outer

The volume outside the outer cone of the source.

See also

cone_angle_inner

distance_maximum

The maximum distance of the source. If the listener is further away the source volume will be 0.

See also

Device.distance_model

distance_reference

The reference distance of the source. At this distance the volume will be exactly volume.

See also

Device.distance_model

keep

Whether the sound should be kept paused in the device when its end is reached. This can be used to seek the sound to some position and start playback again.

Warning

If this is set to true and you forget stopping this equals a memory leak as the handle exists until the device is destroyed.

location

The source’s location in 3D space, a 3D tuple of floats.

loop_count

The (remaining) loop count of the sound. A negative value indicates infinity.

orientation

The source’s orientation in 3D space as quaternion, a 4 float tuple.

pitch

The pitch of the sound.

position

The playback position of the sound in seconds.

relative

Whether the source’s location, velocity and orientation is relative or absolute to the listener.

status

Whether the sound is playing, paused or stopped (=invalid).

velocity

The source’s velocity in 3D space, a 3D tuple of floats.

volume

The volume of the sound.

volume_maximum

The maximum volume of the source.

See also

Device.distance_model

volume_minimum

The minimum volume of the source.

See also

Device.distance_model

class aud.error