Audio System (aud)

Audaspace (pronounced “outer space”) is a high level audio library.

Basic Sound Playback

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

import aud

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

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

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

aud.AP_LOCATION

constant value 3

aud.AP_ORIENTATION

constant value 4

aud.AP_PANNING

constant value 1

aud.AP_PITCH

constant value 2

aud.AP_VOLUME

constant value 0

aud.CHANNELS_INVALID

constant value 0

aud.CHANNELS_MONO

constant value 1

aud.CHANNELS_STEREO

constant value 2

aud.CHANNELS_STEREO_LFE

constant value 3

aud.CHANNELS_SURROUND4

constant value 4

aud.CHANNELS_SURROUND5

constant value 5

aud.CHANNELS_SURROUND51

constant value 6

aud.CHANNELS_SURROUND61

constant value 7

aud.CHANNELS_SURROUND71

constant value 8

aud.CODEC_AAC

constant value 1

aud.CODEC_AC3

constant value 2

aud.CODEC_FLAC

constant value 3

aud.CODEC_INVALID

constant value 0

aud.CODEC_MP2

constant value 4

aud.CODEC_MP3

constant value 5

aud.CODEC_OPUS

constant value 8

aud.CODEC_PCM

constant value 6

aud.CODEC_VORBIS

constant value 7

aud.CONTAINER_AC3

constant value 1

aud.CONTAINER_FLAC

constant value 2

aud.CONTAINER_INVALID

constant value 0

aud.CONTAINER_MATROSKA

constant value 3

aud.CONTAINER_MP2

constant value 4

aud.CONTAINER_MP3

constant value 5

aud.CONTAINER_OGG

constant value 6

aud.CONTAINER_WAV

constant value 7

aud.DISTANCE_MODEL_EXPONENT

constant value 5

aud.DISTANCE_MODEL_EXPONENT_CLAMPED

constant value 6

aud.DISTANCE_MODEL_INVALID

constant value 0

aud.DISTANCE_MODEL_INVERSE

constant value 1

aud.DISTANCE_MODEL_INVERSE_CLAMPED

constant value 2

aud.DISTANCE_MODEL_LINEAR

constant value 3

aud.DISTANCE_MODEL_LINEAR_CLAMPED

constant value 4

aud.FORMAT_FLOAT32

constant value 36

aud.FORMAT_FLOAT64

constant value 40

aud.FORMAT_INVALID

constant value 0

aud.FORMAT_S16

constant value 18

aud.FORMAT_S24

constant value 19

aud.FORMAT_S32

constant value 20

aud.FORMAT_U8

constant value 1

aud.RATE_11025

constant value 11025

aud.RATE_16000

constant value 16000

aud.RATE_192000

constant value 192000

aud.RATE_22050

constant value 22050

aud.RATE_32000

constant value 32000

aud.RATE_44100

constant value 44100

aud.RATE_48000

constant value 48000

aud.RATE_8000

constant value 8000

aud.RATE_88200

constant value 88200

aud.RATE_96000

constant value 96000

aud.RATE_INVALID

constant value 0

aud.STATUS_INVALID

constant value 0

aud.STATUS_PAUSED

constant value 2

aud.STATUS_PLAYING

constant value 1

aud.STATUS_STOPPED

constant value 3

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.

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

classmethod play(sound, keep=False)

Plays a sound.

Parameters

• sound (Sound) – The sound to play.

• keep (bool) – See Handle.keep.

Returns

The playback handle with which playback can be controlled with.

Return type

Handle

classmethod stopAll()

Stops all playing and paused sounds.

classmethod 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

OpenAL Documentation

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.3 m/s.

volume

The overall volume of the device.

class aud.DynamicMusic

The DynamicMusic object allows to play music depending on a current scene, scene changes are managed by the class, with the possibility of custom transitions. The default transition is a crossfade effect, and the default scene is silent and has id 0

classmethod addScene(scene)

Adds a new scene.

Parameters

scene (Sound) – The scene sound.

Returns

The new scene id.

Return type

int

classmethod addTransition(ini, end, transition)

Adds a new scene.

Parameters

• ini (int) – the initial scene foor the transition.

• end (int) – The final scene for the transition.

• transition (Sound) – The transition sound.

Returns

false if the ini or end scenes don’t exist, true othrwise.

Return type

bool

classmethod pause()

Pauses playback of the scene.

Returns

Whether the action succeeded.

Return type

bool

classmethod resume()

Resumes playback of the scene.

Returns

Whether the action succeeded.

Return type

bool

classmethod stop()

Stops playback of the scene.

Returns

Whether the action succeeded.

Return type

bool

fadeTime

The length in seconds of the crossfade transition

position

The playback position of the scene in seconds.

scene

The current scene

status

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

volume

The volume of the scene.

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.

classmethod pause()

Pauses playback.

Returns

Whether the action succeeded.

Return type

bool

classmethod resume()

Resumes playback.

Returns

Whether the action succeeded.

Return type

bool

classmethod 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.PlaybackManager

A PlabackManager object allows to easily control groups os sounds organized in categories.

classmethod addCategory(volume)

Adds a category with a custom volume.

Parameters

volume (float) – The volume for ther new category.

Returns

The key of the new category.

Return type

int

classmethod clean()

Cleans all the invalid and finished sound from the playback manager.

classmethod getVolume(catKey)

Retrieves the volume of a category.

Parameters

catKey (int) – the key of the category.

Returns

The volume of the cateogry.

Return type

float

classmethod pause(catKey)

Pauses playback of the category.

Parameters

catKey (int) – the key of the category.

Returns

Whether the action succeeded.

Return type

bool

classmethod play(sound, catKey)

Plays a sound through the playback manager and assigns it to a category.

Parameters

• sound (Sound) – The sound to play.

• catKey (int) – the key of the category in which the sound will be added, if it doesn’t exist, a new one will be created.

Returns

The playback handle with which playback can be controlled with.

Return type

Handle

classmethod resume(catKey)

Resumes playback of the catgory.

Parameters

catKey (int) – the key of the category.

Returns

Whether the action succeeded.

Return type

bool

classmethod setVolume(volume, catKey)

Changes the volume of a category.

Parameters

• volume (float) – the new volume value.

• catKey (int) – the key of the category.

Returns

Whether the action succeeded.

Return type

int

classmethod stop(catKey)

Stops playback of the category.

Parameters

catKey (int) – the key of the category.

Returns

Whether the action succeeded.

Return type

bool

class aud.Sequence

This sound represents sequenced entries to play a sound sequence.

classmethod add()

Adds a new entry to the sequence.

Parameters

• sound (Sound) – The sound this entry should play.

• begin (double) – The start time.

• end (double) – The end time or a negative value if determined by the sound.

• skip (double) – How much seconds should be skipped at the beginning.

Returns

The entry added.

Return type

SequenceEntry

classmethod remove()

Removes an entry from the sequence.

Parameters

entry (SequenceEntry) – The entry to remove.

classmethod setAnimationData()

Writes animation data to a sequence.

Parameters

• type (int) – The type of animation data.

• frame (int) – The frame this data is for.

• data (sequence of float) – The data to write.

• animated (bool) – Whether the attribute is animated.

channels

The channel count of the sequence.

distance_model

The distance model of the sequence.

See also

OpenAL Documentation

doppler_factor

The doppler factor of the sequence. 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.

fps

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

muted

Whether the whole sequence is muted.

rate

The sampling rate of the sequence in Hz.

speed_of_sound

The speed of sound of the sequence. The speed of sound in air is typically 343.3 m/s.

class aud.SequenceEntry

SequenceEntry objects represent an entry of a sequenced sound.

classmethod move()

Moves the entry.

Parameters

• begin (double) – The new start time.

• end (double) – The new end time or a negative value if unknown.

• skip (double) – How many seconds to skip at the beginning.

classmethod setAnimationData()

Writes animation data to a sequenced entry.

Parameters

• type (int) – The type of animation data.

• frame (int) – The frame this data is for.

• data (sequence of float) – The data to write.

• animated (bool) – Whether the attribute is animated.

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

muted

Whether the entry is muted.

relative

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

sound

The sound the entry is representing and will be played in the sequence.

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

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

classmethod buffer(data, rate)

Creates a sound from a data buffer.

Parameters

• data (numpy.ndarray) – The data as two dimensional numpy array.

• rate (double) – The sample rate.

Returns

The created Sound object.

Return type

Sound

classmethod file(filename)

Creates a sound object of a sound file.

Parameters

filename (string) – Path of the file.

Returns

The created Sound object.

Return type

Sound

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

classmethod list()

Creates an empty sound list that can contain several sounds.

Parameters

random (int) – whether the playback will be random or not.

Returns

The created Sound object.

Return type

Sound

classmethod sawtooth(frequency, rate=48000)

Creates a sawtooth sound which plays a sawtooth wave.

Parameters

• frequency (float) – The frequency of the sawtooth 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 Sound object.

Return type

Sound

classmethod silence(rate=48000)

Creates a silence sound which plays simple silence.

Parameters

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 Sound object.

Return type

Sound

classmethod sine(frequency, rate=48000)

Creates a sine sound 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 Sound object.

Return type

Sound

classmethod square(frequency, rate=48000)

Creates a square sound which plays a square wave.

Parameters

• frequency (float) – The frequency of the square 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 Sound object.

Return type

Sound

classmethod triangle(frequency, rate=48000)

Creates a triangle sound which plays a triangle wave.

Parameters

• frequency (float) – The frequency of the triangle 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 Sound object.

Return type

Sound

classmethod ADSR(attack, decay, sustain, release)

Attack-Decay-Sustain-Release envelopes the volume of a sound. Note: there is currently no way to trigger the release with this API.

Parameters

• attack (float) – The attack time in seconds.

• decay (float) – The decay time in seconds.

• sustain (float) – The sustain level.

• release (float) – The release level.

Returns

The created Sound object.

Return type

Sound

classmethod accumulate(additive=False)

Accumulates a sound by summing over positive input differences thus generating a monotonic sigal. If additivity is set to true negative input differences get added too, but positive ones with a factor of two.

Note that with additivity the signal is not monotonic anymore.

Parameters

additive – Whether the accumulation should be additive or not.

Returns

The created Sound object.

Return type

Sound

classmethod addSound(sound)

Adds a new sound to a sound list.

Parameters

sound (Sound) – The sound that will be added to the list.

Note

You can only add a sound to a sound list.

classmethod cache()

Caches a sound into RAM.

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

Returns

The created Sound object.

Return type

Sound

Note

Only known-length factories can be buffered.

Warning

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

classmethod data()

Retrieves the data of the sound as numpy array.

Returns

A two dimensional numpy float array.

Return type

numpy.ndarray

Note

Best efficiency with cached sounds.

classmethod delay(time)

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

Parameters

time (float) – How many seconds of silence should be added before the sound.

Returns

The created Sound object.

Return type

Sound

classmethod envelope(attack, release, threshold, arthreshold)

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

Parameters

• attack (float) – The attack factor.

• release (float) – The release factor.

• threshold (float) – The general threshold value.

• arthreshold (float) – The attack/release threshold value.

Returns

The created Sound object.

Return type

Sound

classmethod fadein(start, length)

Fades a sound 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 Sound object.

Return type

Sound

Note

Before the fade starts it plays silence.

classmethod fadeout(start, length)

Fades a sound 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 Sound object.

Return type

Sound

Note

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

classmethod filter(b, a=1)

Filters a sound 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 Sound object.

Return type

Sound

classmethod 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 Sound object.

Return type

Sound

classmethod join(sound)

Plays two factories in sequence.

Parameters

sound (Sound) – The sound to play second.

Returns

The created Sound object.

Return type

Sound

Note

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

classmethod limit(start, end)

Limits a sound within a specific start and end time.

Parameters

• start (float) – Start time in seconds.

• end (float) – End time in seconds.

Returns

The created Sound object.

Return type

Sound

classmethod loop(count)

Loops a sound.

Parameters

count (integer) – How often the sound should be looped. Negative values mean endlessly.

Returns

The created Sound object.

Return type

Sound

Note

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

classmethod 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 Sound object.

Return type

Sound

classmethod mix(sound)

Mixes two factories.

Parameters

sound (Sound) – The sound to mix over the other.

Returns

The created Sound object.

Return type

Sound

Note

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

classmethod modulate(sound)

Modulates two factories.

Parameters

sound (Sound) – The sound to modulate over the other.

Returns

The created Sound object.

Return type

Sound

Note

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

classmethod mutable()

Creates a sound that will be restarted when sought backwards. If the original sound is a sound list, the playing sound can change.

Returns

The created Sound object.

Return type

Sound

classmethod pingpong()

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

Returns

The created Sound object.

Return type

Sound

classmethod pitch(factor)

Changes the pitch of a sound with a specific factor.

Parameters

factor (float) – The factor to change the pitch with.

Returns

The created Sound object.

Return type

Sound

Note

This is done by changing the sample rate of the underlying sound, 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.

classmethod rechannel(channels)

Rechannels the sound.

Parameters

channels (int) – The new channel configuration.

Returns

The created Sound object.

Return type

Sound

classmethod resample(rate, high_quality)

Resamples the sound.

Parameters

• rate (double) – The new sample rate.

• high_quality (bool) – When true use a higher quality but slower resampler.

Returns

The created Sound object.

Return type

Sound

classmethod reverse()

Plays a sound reversed.

Returns

The created Sound object.

Return type

Sound

Note

The sound 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 cache() before being played reversed.

Warning

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

classmethod sum()

Sums the samples of a sound.

Returns

The created Sound object.

Return type

Sound

classmethod threshold(threshold=0)

Makes a threshold 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 Sound object.

Return type

Sound

classmethod volume(volume)

Changes the volume of a sound.

Parameters

volume (float) – The new volume..

Returns

The created Sound object.

Return type

Sound

Note

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

Note

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

classmethod write(filename, rate, channels, format, container, codec, bitrate, buffersize)

Writes the sound to a file.

Parameters

• filename (string) – The path to write to.

• rate (int) – The sample rate to write with.

• channels (int) – The number of channels to write with.

• format (int) – The sample format to write with.

• container (int) – The container format for the file.

• codec (int) – The codec to use in the file.

• bitrate (int) – The bitrate to write with.

• buffersize (int) – The size of the writing buffer.

length

The sample specification of the sound as a tuple with rate and channel count.

specs

The sample specification of the sound as a tuple with rate and channel count.

class aud.Source

The source object represents the source position of a binaural sound.

azimuth

The azimuth angle.

distance

The distance value. 0 is min, 1 is max.

elevation

The elevation angle.

class aud.ThreadPool

A ThreadPool is used to parallelize convolution efficiently.

class aud.error