Sound¶

class aud.Sound

class Sound(filename, stream=0)¶

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.

Parameters:

filename (string) – Path of the file.
stream (int) – The index of the audio stream within the file if it contains multiple audio streams, 0 by default.

ADSR()

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

accumulate()

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

addSound(object, /)

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.

animateableTimeStretchPitchScale()

animateableTimeStretchPitchScale(fps[, time_stretch, pitch_scale, quality, preserve_formant])¶

Applies time-stretching and pitch-scaling to the sound.

Parameters:

fps (float) – The FPS of the animation system.
time_stretch (float or AnimateablePropertyP) – The factor by which to stretch or compress time.
pitch_scale (float or AnimateablePropertyP :arg quality: Rubberband stretcher quality (STRETCHER_QUALITY_*).) – The factor by which to adjust the pitch.
preserve_formant (bool) – Whether to preserve the vocal formants during pitch-shifting.

Returns:

The created Sound object.

Return type:

Sound

binaural()

binaural()¶

Creates a binaural sound using another sound as source. The original sound must be mono

Parameters:

hrtfs – An HRTF set.
source (Source) – An object representing the source position of the sound.
threadPool (ThreadPool) – A thread pool used to parallelize convolution.

Returns:

The created Sound object.

Return type:

Sound

classmethod buffer()

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

cache()

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.

convolver()

convolver()¶

Creates a sound that will apply convolution to another sound.

Parameters:

impulseResponse (ImpulseResponse) – The filter with which convolve the sound.
threadPool (ThreadPool) – A thread pool used to parallelize convolution.

Returns:

The created Sound object.

Return type:

Sound

data()

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.

delay()

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

echo()

Echo(delay, feedback, mix)¶

Adds Echo effect to the sound.

Parameters:

delay (float) – The delay time in seconds.
feedback (float) – The feedback amount (0.0 to 1.0).
mix (float) – The wet/dry mix (0.0 to 1.0).
reset_buffer (bool) – Whether to reset the delay buffer on seek.

Returns:

The created Sound object.

Return type:

Sound

envelope()

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

fadein()

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.

fadeout()

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 file()

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.

filter()

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

highpass()

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

join(object, /)

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

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

limit()

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 list()

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

loop()

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.

lowpass()

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

mix(object, /)

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

modulate(object, /)

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

mutable()

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

pingpong()

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

pitch()

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.

rechannel()

rechannel(channels)¶

Rechannels the sound.

Parameters:: channels (int) – The new channel configuration.
Returns:: The created Sound object.
Return type:: Sound

resample()

resample(rate, quality)¶

Resamples the sound.

Parameters:

rate (double) – The new sample rate.
quality (int) – Resampler performance vs quality choice (0=fastest, 3=slowest).

Returns:

The created Sound object.

Return type:

Sound

reverse()

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 sawtooth()

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 sampling rate to avoid resampling.

Returns:

The created Sound object.

Return type:

Sound

classmethod silence()

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 sampling rate to avoid resampling.
Returns:: The created Sound object.
Return type:: Sound

classmethod sine()

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 sampling rate to avoid resampling.

Returns:

The created Sound object.

Return type:

Sound

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

classmethod square()

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 sampling rate to avoid resampling.

Returns:

The created Sound object.

Return type:

Sound

sum()

sum()¶

Sums the samples of a sound.

Returns:: The created Sound object.
Return type:: Sound

threshold()

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

timeStretchPitchScale()

timeStretchPitchScale(time_stretch, pitch_scale, quality, preserve_formant)¶

Applies time-stretching and pitch-scaling to the sound.

Parameters:

time_stretch (float) – The factor by which to stretch or compress time.
pitch_scale (float) – The factor by which to adjust the pitch.
quality (int) – Rubberband stretcher quality (STRETCHER_QUALITY_*).
preserve_formant (bool) – Whether to preserve the vocal formants during pitch-shifting.

Returns:

The created Sound object.

Return type:

Sound

classmethod triangle()

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 sampling rate to avoid resampling.

Returns:

The created Sound object.

Return type:

Sound

volume()

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.

write()

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.

Sound¶

audaspace

Navigation

Related Topics