API Documentation§
PortAudio output stream for realtime mixing. |
|
PortAudio input stream for realtime recording. |
|
PortAudio stream for realtime mixing and recording. |
|
PortAudio's single-reader single-writer lock-free ring buffer. |
Common parameters that are shared by most commands:
start
Desired time at which the playback/recording should be started. The actual time will be stored in the
actual_time
field of the returned action.time
Desired time at which the command should be executed. The actual time will be stored in the
actual_time
field of the returned action.channels
This can be either the desired number of channels or a list of (1-based) channel numbers that is used as a channel map for playback/recording.
allow_belated
Use
False
to cancel the command in case the requested time cannot be met. Theactual_time
field will be set to0.0
in this case. UseTrue
to execute the command nevertheless. Even if the requested time was met, theactual_time
might be slightly different due to rounding to the next audio sample.
All commands return a corresponding “action”, which can be compared against the
active actions
, and can be used as input for cancel()
and wait()
.
The fields of action objects are defined in C but can be accessed with
Python (e.g. my_action.stats.min_blocksize
)
after the command is finished:
struct action
{
const enum actiontype type;
const PaTime requested_time;
PaTime actual_time; // Set != 0.0 to allow belated actions
struct action* next; // Used to create singly linked list of actions
union {
float* const buffer;
struct PaUtilRingBuffer* const ringbuffer;
struct action* const action; // Used in CANCEL
};
frame_t total_frames;
frame_t done_frames;
struct stats stats;
// TODO: ringbuffer usage: store smallest available write/read size?
const frame_t channels; // Size of the following array
const frame_t mapping[]; // "flexible array member"
};
The stats
field contains some statistics collected during playback/recording
(again, after the command is finished):
struct stats
{
frame_t blocks;
frame_t min_blocksize;
frame_t max_blocksize;
frame_t input_underflows;
frame_t input_overflows;
frame_t output_underflows;
frame_t output_overflows;
};
These statistics are also collected for the whole runtime of a stream,
where they are available as stats
attribute (but only if the stream is
inactive). The statistics of an active stream can be obtained
(and at the same time reset) with fetch_and_reset_stats()
.
- class rtmixer.Mixer(**kwargs)[source]§
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
(exceptwrite()
andwrite_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.
The statistics will be available in the
stats
field of the returned action.
- play_buffer(buffer, channels, start=0, allow_belated=True)[source]§
Send a buffer to the callback to be played back.
After calling this, the buffer must not be written to anymore.
- play_ringbuffer(ringbuffer, channels=None, start=0, allow_belated=True)[source]§
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, usefetch_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)[source]§
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 thatplay_buffer()
andplay_ringbuffer()
are replaced by:- record_buffer(buffer, channels, start=0, allow_belated=True)[source]§
Send a buffer to the callback to be recorded into.
- record_ringbuffer(ringbuffer, channels=None, start=0, allow_belated=True)[source]§
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)[source]§
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
andRecorder
.
- 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:
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 methodsread()
andreadinto()
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 methodwrite()
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.
- 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.
- 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.
- property write_available§
Number of elements available in the ring buffer for writing.