API Documentation

Mixer	PortAudio output stream for realtime mixing.
Recorder	PortAudio input stream for realtime recording.
MixerAndRecorder	PortAudio stream for realtime mixing and recording.
RingBuffer	PortAudio’s single-reader single-writer lock-free ring buffer.

class rtmixer.Mixer(**kwargs)

PortAudio output stream for realtime mixing.

Takes the same keyword arguments as sounddevice.OutputStream, except callback (a callback function implemented in C is used internally) and dtype (which is always 'float32').

Uses default values from sounddevice.default (except dtype, which is always 'float32').

Has the same methods and attributes as sounddevice.OutputStream (except write() and write_available), plus the following:

property actions

The set of active “actions”.

cancel(action, time=0, allow_belated=True)

Initiate stopping a running action.

This creates another action that is sent to the callback in order to stop the given action.

This function typically returns before the action is actually stopped. Use wait() (on either one of the two actions) to wait until it’s done.

fetch_and_reset_stats(time=0, allow_belated=True)

Fetch and reset over-/underflow statistics of the stream.

play_buffer(buffer, channels, start=0, allow_belated=True)

Send a buffer to the callback to be played back.

After that, the buffer must not be written to anymore.

play_ringbuffer(ringbuffer, channels=None, start=0, allow_belated=True)

Send a RingBuffer to the callback to be played back.

By default, the number of channels is obtained from the ring buffer’s elementsize.

property stats

Get over-/underflow statistics from an inactive stream.

To get statistics from an active stream, use fetch_and_reset_stats().

wait(action=None, sleeptime=10)

Wait for action to be finished.

Between repeatedly checking if the action is finished, this waits for sleeptime milliseconds.

If no action is given, this waits for all actions.

class rtmixer.Recorder(**kwargs)

PortAudio input stream for realtime recording.

Takes the same keyword arguments as sounddevice.InputStream, except callback (a callback function implemented in C is used internally) and dtype (which is always 'float32').

Uses default values from sounddevice.default (except dtype, which is always 'float32').

Has the same methods and attributes as Mixer, except that play_buffer() and play_ringbuffer() are replaced by:

record_buffer(buffer, channels, start=0, allow_belated=True)

Send a buffer to the callback to be recorded into.

record_ringbuffer(ringbuffer, channels=None, start=0, allow_belated=True)

Send a RingBuffer to the callback to be recorded into.

By default, the number of channels is obtained from the ring buffer’s elementsize.

class rtmixer.MixerAndRecorder(**kwargs)

PortAudio stream for realtime mixing and recording.

Takes the same keyword arguments as sounddevice.Stream, except callback (a callback function implemented in C is used internally) and dtype (which is always 'float32').

Uses default values from sounddevice.default (except dtype, which is always 'float32').

Inherits all methods and attributes from Mixer and Recorder.

class rtmixer.RingBuffer(elementsize, size=None, buffer=None)

PortAudio’s single-reader single-writer lock-free ring buffer.

C API documentation:

http://portaudio.com/docs/v19-doxydocs-dev/pa__ringbuffer_8h.html

Python wrapper:

https://github.com/spatialaudio/python-pa-ringbuffer

Instances of this class can be used to transport data between Python code and some compiled code running on a different thread.

This only works when there is a single reader and a single writer (i.e. one thread or callback writes to the ring buffer, another thread or callback reads from it).

This ring buffer is not appropriate for passing data from one Python thread to another Python thread. For this, the queue.Queue class from the standard library can be used.

Parameters

• elementsize (int) – The size of a single data element in bytes.

• size (int) – The number of elements in the buffer (must be a power of 2). Can be omitted if a pre-allocated buffer is passed.

• buffer (buffer) – optional pre-allocated buffer to use with RingBuffer. Note that if you pass a read-only buffer object, you still get a writable RingBuffer; it is your responsibility not to write there if the original buffer doesn’t expect you to.

advance_read_index(size)

Advance the read index to the next location to be read.

Parameters

size (int) – The number of elements to advance.

Returns

The new position.

Note

This is only needed when using get_read_buffers(), the methods read() and readinto() take care of this by themselves!

advance_write_index(size)

Advance the write index to the next location to be written.

Parameters

size (int) – The number of elements to advance.

Returns

The new position.

Note

This is only needed when using get_write_buffers(), the method write() takes care of this by itself!

property elementsize

Element size in bytes.

flush()

Reset buffer to empty.

Should only be called when buffer is not being read or written.

get_read_buffers(size)

Get buffer(s) from which we can read data.

When done reading, use advance_read_index() to make the memory available for writing again.

Parameters

size (int) – The number of elements desired.

Returns

• The number of elements available for reading (which might be less than the requested size).

• The first buffer.

• The second buffer.

Return type

tuple (int, buffer, buffer)

get_write_buffers(size)

Get buffer(s) to which we can write data.

When done writing, use advance_write_index() to make the written data available for reading.

Parameters

size (int) – The number of elements desired.

Returns

• The room available to be written or the given size, whichever is smaller.

• The first buffer.

• The second buffer.

Return type

tuple (int, buffer, buffer)

read(size=- 1)

Read data from the ring buffer into a new buffer.

This advances the read index after reading; calling advance_read_index() is not necessary.

Parameters

size (int, optional) – The number of elements to be read. If not specified, all available elements are read.

Returns

A new buffer containing the read data. Its size may be less than the requested size.

property read_available

Number of elements available in the ring buffer for reading.

readinto(data)

Read data from the ring buffer into a user-provided buffer.

This advances the read index after reading; calling advance_read_index() is not necessary.

Parameters

data (CData pointer or buffer) – The memory where the data should be stored.

Returns

The number of elements read, which may be less than the size of data.

write(data, size=- 1)

Write data to the ring buffer.

This advances the write index after writing; calling advance_write_index() is not necessary.

Parameters

• data (CData pointer or buffer or bytes) – Data to write to the buffer.

• size (int, optional) – The number of elements to be written.

Returns

The number of elements written.

property write_available

Number of elements available in the ring buffer for writing.