# 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`