Pysound buffer module

Martin McBride

2021-09-11

The Pysound buffer module contains some functions for working with sound buffers, and the BufferParams object.

Sound buffers are pure NumPy arrays, with a type of np.float. This means that we don't need a lot of extra functions to handle sound buffers, we just use the existing NumPy functions.

A sound buffer always requires an associated BufferParams object to specify the sample rate of the sound, but this is usually passed around separately. In most cases every component uses the same sample rate, and in many cases they all use the same length too. This means that you can get away with using just a single BufferParams object for every component.

The buffer module defines:

The BufferParams object.
The create_buffer function that creates a new sound buffer by either an existing sound buffer or filling a buffer with a constant value.
The mix_buffer function that adds the content of one sound buffer into another.

BufferParams

BufferParams is a simple object that stores the length and sample rate of a sound buffer.

BufferParams is immutable. If you want a BufferParams object with different values, you must create a new object. There are factory methods to do this, see below.

Constructor

Creates a new BufferParams with specified values.

BufferParams(length=44100, sample_rate=44100)

Parameter	Type	Description
length	integer	The required length of the buffer, in samples.
sample_rate	integer	The required sample rate of the buffer.

Creates a new BufferParams object.

get_length

Returns the length of this BufferParams object.

get_length()

Returns the length of the buffer, in samples, as an integer.

get_sample_rate

Returns the sample rate of this BufferParams object.

get_sample_rate()

Returns the sample rate of the buffer, in samples per second, as an integer.

t2s

Converts a time to a sample count using the buffer's sample rate.

t2s(length=44100, sample_rate=44100)

Parameter	Type	Description
time	float	The time in seconds.

For a given duration time, this function resturns the corresponding sample count. For example, if the BufferParams object had a sample rate of 5000 samples per second, and we called t2s with a time of 0.5 seconds, the result would be 2500 (there are 2500 samples in 0.5 seconds).

Note that there is potential for rounding error in this call, because time is a float.

with_length

Creates a new BufferParams with the same sample rate but a new length.

with_length(length)

Parameter	Type	Description
length	integer	The required length of the buffer, in samples.

Returns a new BufferParams object based on an existing object.

with_duration

Creates a new BufferParams with the same sample rate but a new length.

with_duration(duration)

Parameter	Type	Description
duration	float	The required length of the buffer, in seconds.

Returns a new BufferParams object based on an existing object. This is similar to with_length but the buffer length is expressed as a time in seconds rather than a length in samples.

For an original BufferParams object params, this is equivalent to:

params.with_length(params.t2s(duration))

As with the t2s method, this method may be subject to rounding errors.

with_sample_rate

Creates a new BufferParams with the same length but a new sample rate.

with_sample_rate(sample_rate)

Parameter	Type	Description
sample_rate	integer	The required sample rate of the buffer, in samples per second.

Returns a new BufferParams object based on an existing object.

create_buffer

Utility function to create a new buffer based on a value that can either be a float or an existing buffer.

create_buffer(params, value=0.0)

Parameter	Type	Description
params	BufferParams	The parameters for the new buffer.
value	float or np array	The data for the new buffer.

Returns a new BufferParams object. The length and sample rate of the new buffer will be set by params.

If the value is a float, the resulting buffer will be filled with the float value. The default is 0.0, creating an array of zeros,

If the value is a NumPy array, the resulting buffer will contain a copy of the supplied array.

This function assumes that the value buffer has the same sample rate as the output buffer. However, the buffers don't have to be the same length. The output array will always have the length specified in params. If value is too short, the output array will be padded with zeros. If value is too long, the data will be truncated to fit the output array.

mix_buffer

Utility function to mix data into an existing buffer.

mix_buffer(dest, src, at)

Parameter	Type	Description
dest	np array	The destination NumPy array.
src	np array	The source NumPy array.
at	int	The position within the destination buffer where the source will be included.

This function performs simple mixing of a source buffer into a destination buffer.

For example assume the destination buffer is 1000 samples long, the source buffer is 200 sample long, and the at parameter is 100.

In that case, the source buffer will be mixed in to the destination buffer at position 100. It will affect destination samples 100 to 299.

The source sample will be added to whatever values are already in the destination samples in teh affected area.

There are a few limitations:

It is assumed that the source and destination buffers have the same sample rate.
The source buffer must completely fit within the destination buffer. That is to say, at cannot be less than zero, and at plus the length of the soiurce buffer cannot exceed the length of the destination buffer.