Streams using NumPy Arrays

Overview

Stream	PortAudio stream for simultaneous input and output (using NumPy).
InputStream	PortAudio input stream (using NumPy).
OutputStream	PortAudio output stream (using NumPy).

class sounddevice.Stream(samplerate=None, blocksize=None, device=None, channels=None, dtype=None, latency=None, extra_settings=None, callback=None, finished_callback=None, clip_off=None, dither_off=None, never_drop_input=None, prime_output_buffers_using_stream_callback=None)

PortAudio stream for simultaneous input and output (using NumPy).

To open an input-only or output-only stream use InputStream or OutputStream, respectively. If you want to handle audio data as plain buffer objects instead of NumPy arrays, use RawStream, RawInputStream or RawOutputStream.

A single stream can provide multiple channels of real-time streaming audio input and output to a client application. A stream provides access to audio hardware represented by one or more devices. Depending on the underlying host API, it may be possible to open multiple streams using the same device, however this behavior is implementation defined. Portable applications should assume that a device may be simultaneously used by at most one stream.

The arguments device, channels, dtype and latency can be either single values (which will be used for both input and output parameters) or pairs of values (where the first one is the value for the input and the second one for the output).

All arguments are optional, the values for unspecified parameters are taken from the default object. If one of the values of a parameter pair is None, the corresponding value from default will be used instead.

The created stream is inactive (see active, stopped). It can be started with start().

Every stream object is also a context manager, i.e. it can be used in a with statement to automatically call start() in the beginning of the statement and stop() and close() on exit.

Parameters:

• samplerate (float, optional) – The desired sampling frequency (for both input and output). The default value can be changed with default.samplerate.

• blocksize (int, optional) – The number of frames passed to the stream callback function, or the preferred block granularity for a blocking read/write stream. The special value blocksize=0 (which is the default) may be used to request that the stream callback will receive an optimal (and possibly varying) number of frames based on host requirements and the requested latency settings. The default value can be changed with default.blocksize.

  Note

  With some host APIs, the use of non-zero blocksize for a callback stream may introduce an additional layer of buffering which could introduce additional latency. PortAudio guarantees that the additional latency will be kept to the theoretical minimum however, it is strongly recommended that a non-zero blocksize value only be used when your algorithm requires a fixed number of frames per stream callback.

• device (int or str or pair thereof, optional) – Device index(es) or query string(s) specifying the device(s) to be used. The default value(s) can be changed with default.device. If a string is given, the device is selected which contains all space-separated parts in the right order. Each device string contains the name of the corresponding host API in the end. The string comparison is case-insensitive.

• channels (int or pair of int, optional) – The number of channels of sound to be delivered to the stream callback or accessed by read() or write(). It can range from 1 to the value of 'max_input_channels' or 'max_output_channels' in the dict returned by query_devices(). By default, the maximum possible number of channels for the selected device is used (which may not be what you want; see query_devices()). The default value(s) can be changed with default.channels.

• dtype (str or numpy.dtype or pair thereof, optional) – The sample format of the numpy.ndarray provided to the stream callback, read() or write(). It may be any of float32, int32, int16, int8, uint8. See numpy.dtype. The float64 data type is not supported, this is only supported for convenience in play()/rec()/playrec(). The packed 24 bit format 'int24' is only supported in the “raw” stream classes, see RawStream. The default value(s) can be changed with default.dtype. If NumPy is available, the corresponding numpy.dtype objects can be used as well. The floating point representations 'float32' and 'float64' use +1.0 and -1.0 as the maximum and minimum values, respectively. 'uint8' is an unsigned 8 bit format where 128 is considered “ground”.

• latency (float or {‘low’, ‘high’} or pair thereof, optional) – The desired latency in seconds. The special values 'low' and 'high' (latter being the default) select the device’s default low and high latency, respectively (see query_devices()). 'high' is typically more robust (i.e. buffer under-/overflows are less likely), but the latency may be too large for interactive applications.

  Note

  Specifying the desired latency as 'high' does not guarantee a stable audio stream. For reference, by default Audacity specifies a desired latency of 0.1 seconds and typically achieves robust performance.

  The default value(s) can be changed with default.latency. Actual latency values for an open stream can be retrieved using the latency attribute.

• extra_settings (settings object or pair thereof, optional) – This can be used for host-API-specific input/output settings. See default.extra_settings.

• callback (callable, optional) – User-supplied function to consume, process or generate audio data in response to requests from an active stream. When a stream is running, PortAudio calls the stream callback periodically. The callback function is responsible for processing and filling input and output buffers, respectively.

  If no callback is given, the stream will be opened in “blocking read/write” mode. In blocking mode, the client can receive sample data using read() and write sample data using write(), the number of frames that may be read or written without blocking is returned by read_available and write_available, respectively.

  The callback must have this signature:

  callback(indata: ndarray, outdata: ndarray, frames: int,
           time: CData, status: CallbackFlags) -> None
  

  The first and second argument are the input and output buffer, respectively, as two-dimensional numpy.ndarray with one column per channel (i.e. with a shape of (frames, channels)) and with a data type specified by dtype. The output buffer contains uninitialized data and the callback is supposed to fill it with proper audio data. If no data is available, the buffer should be filled with zeros (e.g. by using outdata.fill(0)).

  Note

  In Python, assigning to an identifier merely re-binds the identifier to another object, so this will not work as expected:

  outdata = my_data  # Don't do this!
  

  To actually assign data to the buffer itself, you can use indexing, e.g.:

  outdata[:] = my_data
  

  … which fills the whole buffer, or:

  outdata[:, 1] = my_channel_data
  

  … which only fills one channel.

  The third argument holds the number of frames to be processed by the stream callback. This is the same as the length of the input and output buffers.

  The forth argument provides a CFFI structure with timestamps indicating the ADC capture time of the first sample in the input buffer (time.inputBufferAdcTime), the DAC output time of the first sample in the output buffer (time.outputBufferDacTime) and the time the callback was invoked (time.currentTime). These time values are expressed in seconds and are synchronised with the time base used by time for the associated stream.

  The fifth argument is a CallbackFlags instance indicating whether input and/or output buffers have been inserted or will be dropped to overcome underflow or overflow conditions.

  If an exception is raised in the callback, it will not be called again. If CallbackAbort is raised, the stream will finish as soon as possible. If CallbackStop is raised, the stream will continue until all buffers generated by the callback have been played. This may be useful in applications such as soundfile players where a specific duration of output is required. If another exception is raised, its traceback is printed to sys.stderr. Exceptions are not propagated to the main thread, i.e. the main Python program keeps running as if nothing had happened.

  Note

  The callback must always fill the entire output buffer, no matter if or which exceptions are raised.

  If no exception is raised in the callback, it automatically continues to be called until stop(), abort() or close() are used to stop the stream.

  The PortAudio stream callback runs at very high or real-time priority. It is required to consistently meet its time deadlines. Do not allocate memory, access the file system, call library functions or call other functions from the stream callback that may block or take an unpredictable amount of time to complete. With the exception of cpu_load it is not permissible to call PortAudio API functions from within the stream callback.

  In order for a stream to maintain glitch-free operation the callback must consume and return audio data faster than it is recorded and/or played. PortAudio anticipates that each callback invocation may execute for a duration approaching the duration of frames audio frames at the stream’s sampling frequency. It is reasonable to expect to be able to utilise 70% or more of the available CPU time in the PortAudio callback. However, due to buffer size adaption and other factors, not all host APIs are able to guarantee audio stability under heavy CPU load with arbitrary fixed callback buffer sizes. When high callback CPU utilisation is required the most robust behavior can be achieved by using blocksize=0.

• finished_callback (callable, optional) – User-supplied function which will be called when the stream becomes inactive (i.e. once a call to stop() will not block).

  A stream will become inactive after the stream callback raises an exception or when stop() or abort() is called. For a stream providing audio output, if the stream callback raises CallbackStop, or stop() is called, the stream finished callback will not be called until all generated sample data has been played. The callback must have this signature:

  finished_callback() -> None
  

• clip_off (bool, optional) – See default.clip_off.

• dither_off (bool, optional) – See default.dither_off.

• never_drop_input (bool, optional) – See default.never_drop_input.

• prime_output_buffers_using_stream_callback (bool, optional) – See default.prime_output_buffers_using_stream_callback.

abort(ignore_errors=True)

Terminate audio processing immediately.

This does not wait for pending buffers to complete.

See also

start, stop

property active

True when the stream is active, False otherwise.

A stream is active after a successful call to start(), until it becomes inactive either as a result of a call to stop() or abort(), or as a result of an exception raised in the stream callback. In the latter case, the stream is considered inactive after the last buffer has finished playing.

See also

stopped

property blocksize

Number of frames per block.

The special value 0 means that the blocksize can change between blocks. See the blocksize argument of Stream.

property channels

The number of input/output channels.

close(ignore_errors=True)

Close the stream.

If the audio stream is active any pending buffers are discarded as if abort() had been called.

property closed

True after a call to close(), False otherwise.

property cpu_load

CPU usage information for the stream.

The “CPU Load” is a fraction of total CPU time consumed by a callback stream’s audio processing routines including, but not limited to the client supplied stream callback. This function does not work with blocking read/write streams.

This may be used in the stream callback function or in the application. It provides a floating point value, typically between 0.0 and 1.0, where 1.0 indicates that the stream callback is consuming the maximum number of CPU cycles possible to maintain real-time operation. A value of 0.5 would imply that PortAudio and the stream callback was consuming roughly 50% of the available CPU time. The value may exceed 1.0. A value of 0.0 will always be returned for a blocking read/write stream, or if an error occurs.

property device

IDs of the input/output device.

property dtype

Data type of the audio samples.

See also

default.dtype, samplesize

property latency

The input/output latency of the stream in seconds.

This value provides the most accurate estimate of input/output latency available to the implementation. It may differ significantly from the latency value(s) passed to Stream().

read(frames)

Read samples from the stream into a NumPy array.

The function doesn’t return until all requested frames have been read – this may involve waiting for the operating system to supply the data (except if no more than read_available frames were requested).

This is the same as RawStream.read(), except that it returns a NumPy array instead of a plain Python buffer object.

Parameters:

frames (int) – The number of frames to be read. This parameter is not constrained to a specific range, however high performance applications will want to match this parameter to the blocksize parameter used when opening the stream.

Returns:

• data (numpy.ndarray) – A two-dimensional numpy.ndarray with one column per channel (i.e. with a shape of (frames, channels)) and with a data type specified by dtype.

• overflowed (bool) – True if input data was discarded by PortAudio after the previous call and before this call.

property read_available

The number of frames that can be read without waiting.

Returns a value representing the maximum number of frames that can be read from the stream without blocking or busy waiting.

property samplerate

The sampling frequency in Hertz (= frames per second).

In cases where the hardware sampling frequency is inaccurate and PortAudio is aware of it, the value of this field may be different from the samplerate parameter passed to Stream(). If information about the actual hardware sampling frequency is not available, this field will have the same value as the samplerate parameter passed to Stream().

property samplesize

The size in bytes of a single sample.

See also

dtype

start()

Commence audio processing.

See also

stop, abort

stop(ignore_errors=True)

Terminate audio processing.

This waits until all pending audio buffers have been played before it returns.

See also

start, abort

property stopped

True when the stream is stopped, False otherwise.

A stream is considered to be stopped prior to a successful call to start() and after a successful call to stop() or abort(). If a stream callback is cancelled (by raising an exception) the stream is not considered to be stopped.

See also

active

property time

The current stream time in seconds.

This is according to the same clock used to generate the timestamps passed with the time argument to the stream callback (see the callback argument of Stream). The time values are monotonically increasing and have unspecified origin.

This provides valid time values for the entire life of the stream, from when the stream is opened until it is closed. Starting and stopping the stream does not affect the passage of time as provided here.

This time may be used for synchronizing other events to the audio stream, for example synchronizing audio to MIDI.

write(data)

Write samples to the stream.

This function doesn’t return until the entire buffer has been consumed – this may involve waiting for the operating system to consume the data (except if data contains no more than write_available frames).

This is the same as RawStream.write(), except that it expects a NumPy array instead of a plain Python buffer object.

Parameters:

data (array_like) – A two-dimensional array-like object with one column per channel (i.e. with a shape of (frames, channels)) and with a data type specified by dtype. A one-dimensional array can be used for mono data. The array layout must be C-contiguous (see numpy.ascontiguousarray()).

The length of the buffer is not constrained to a specific range, however high performance applications will want to match this parameter to the blocksize parameter used when opening the stream.

Returns:

underflowed (bool) – True if additional output data was inserted after the previous call and before this call.

property write_available

The number of frames that can be written without waiting.

Returns a value representing the maximum number of frames that can be written to the stream without blocking or busy waiting.

class sounddevice.InputStream(samplerate=None, blocksize=None, device=None, channels=None, dtype=None, latency=None, extra_settings=None, callback=None, finished_callback=None, clip_off=None, dither_off=None, never_drop_input=None, prime_output_buffers_using_stream_callback=None)

PortAudio input stream (using NumPy).

This has the same methods and attributes as Stream, except write() and write_available. Furthermore, the stream callback is expected to have a different signature (see below).

Parameters:

callback (callable) – User-supplied function to consume audio in response to requests from an active stream. The callback must have this signature:

callback(indata: numpy.ndarray, frames: int,
         time: CData, status: CallbackFlags) -> None

The arguments are the same as in the callback parameter of Stream, except that outdata is missing.

See also

Stream, RawInputStream

class sounddevice.OutputStream(samplerate=None, blocksize=None, device=None, channels=None, dtype=None, latency=None, extra_settings=None, callback=None, finished_callback=None, clip_off=None, dither_off=None, never_drop_input=None, prime_output_buffers_using_stream_callback=None)

PortAudio output stream (using NumPy).

This has the same methods and attributes as Stream, except read() and read_available. Furthermore, the stream callback is expected to have a different signature (see below).

Parameters:

callback (callable) – User-supplied function to generate audio data in response to requests from an active stream. The callback must have this signature:

callback(outdata: numpy.ndarray, frames: int,
         time: CData, status: CallbackFlags) -> None

The arguments are the same as in the callback parameter of Stream, except that indata is missing.

See also

Stream, RawOutputStream