# Convenience Functions using NumPy Arrays

Overview

`play` | Play back a NumPy array containing audio data.
`rec` | Record audio data into a NumPy array.
`playrec` | Simultaneous playback and recording of NumPy arrays.
`wait` | Wait for `play()`/`rec()`/`playrec()` to be finished.
`stop` | Stop playback/recording.
`get_status` | Get info about over-/underflows in `play()`/`rec()`/`playrec()`.
`get_stream` | Get a reference to the current stream.

sounddevice.play(data, samplerate=None, mapping=None, blocking=False, loop=False, **kwargs)

  Play back a NumPy array containing audio data.

  This is a convenience function for interactive use and for small scripts. It cannot be used for multiple overlapping playbacks.

  This function does the following steps internally:

  - Call `stop()` to terminate any currently running invocation of `play()`, `rec()` and `playrec()`.

  - Create an `OutputStream` and a callback function for taking care of the actual playback.

  - Start the stream.

  - If `blocking=True` was given, wait until playback is done. If not, return immediately (to start waiting at a later point, `wait()` can be used).

  If you need more control (e.g. block-wise gapless playback, multiple overlapping playbacks, …), you should explicitly create an `OutputStream` yourself. If NumPy is not available, you can use a `RawOutputStream`.

  Parameters:

    - data (array_like) – Audio data to be played back. The columns of a two-dimensional array are interpreted as channels, one-dimensional arrays are treated as mono data. The data types float64, float32, int32, int16, int8 and uint8 can be used. float64 data is simply converted to float32 before passing it to PortAudio, because it’s not supported natively.

    - mapping (array_like, optional) – List of channel numbers (starting with 1) where the columns of data shall be played back on. Must have the same length as number of channels in data (except if data is mono, in which case the signal is played back on all given output channels). Each channel number may only appear once in mapping.

    - blocking (bool, optional) – If `False` (the default), return immediately (but playback continues in the background), if `True`, wait until playback is finished. A non-blocking invocation can be stopped with `stop()` or turned into a blocking one with `wait()`.

    - loop (bool, optional) – Play data in a loop.

  Other Parameters:

    samplerate, **kwargs – All parameters of `OutputStream` – except channels, dtype, callback and finished_callback – can be used.

  Notes

  If you don’t specify the correct sampling rate (either with the samplerate argument or by assigning a value to `default.samplerate`), the audio data will be played back, but it might be too slow or too fast!

  See also

  `rec`, `playrec`

sounddevice.rec(frames=None, samplerate=None, channels=None, dtype=None, out=None, mapping=None, blocking=False, **kwargs)

  Record audio data into a NumPy array.

  This is a convenience function for interactive use and for small scripts.

  This function does the following steps internally:

  - Call `stop()` to terminate any currently running invocation of `play()`, `rec()` and `playrec()`.

  - Create an `InputStream` and a callback function for taking care of the actual recording.

  - Start the stream.

  - If `blocking=True` was given, wait until recording is done. If not, return immediately (to start waiting at a later point, `wait()` can be used).

  If you need more control (e.g. block-wise gapless recording, overlapping recordings, …), you should explicitly create an `InputStream` yourself. If NumPy is not available, you can use a `RawInputStream`.

  Parameters:

    - frames (int, sometimes optional) – Number of frames to record. Not needed if out is given.

    - channels (int, optional) – Number of channels to record. Not needed if mapping or out is given. The default value can be changed with `default.channels`.

    - dtype (str or numpy.dtype, optional) – Data type of the recording. Not needed if out is given. The data types float64, float32, int32, int16, int8 and uint8 can be used. For `dtype='float64'`, audio data is recorded in float32 format and converted afterwards, because it’s not natively supported by PortAudio. The default value can be changed with `default.dtype`.

    - mapping (array_like, optional) – List of channel numbers (starting with 1) to record. If mapping is given, channels is silently ignored.

    - blocking (bool, optional) – If `False` (the default), return immediately (but recording continues in the background), if `True`, wait until recording is finished. A non-blocking invocation can be stopped with `stop()` or turned into a blocking one with `wait()`.

  Returns:

    numpy.ndarray or type(out) – The recorded data.

    Note

    By default (`blocking=False`), an array of data is returned which is still being written to while recording! The returned data is only valid once recording has stopped. Use `wait()` to make sure the recording is finished.

  Other Parameters:

    - out (numpy.ndarray or subclass, optional) – If out is specified, the recorded data is written into the given array instead of creating a new array. In this case, the arguments frames, channels and dtype are silently ignored! If mapping is given, its length must match the number of channels in out.

    - samplerate, **kwargs – All parameters of `InputStream` – except callback and finished_callback – can be used.

  Notes

  If you don’t specify a sampling rate (either with the samplerate argument or by assigning a value to `default.samplerate`), the default sampling rate of the sound device will be used (see `query_devices()`).

  See also

  `play`, `playrec`

sounddevice.playrec(data, samplerate=None, channels=None, dtype=None, out=None, input_mapping=None, output_mapping=None, blocking=False, **kwargs)

  Simultaneous playback and recording of NumPy arrays.

  This function does the following steps internally:

  - Call `stop()` to terminate any currently running invocation of `play()`, `rec()` and `playrec()`.

  - Create a `Stream` and a callback function for taking care of the actual playback and recording.

  - Start the stream.

  - If `blocking=True` was given, wait until playback/recording is done. If not, return immediately (to start waiting at a later point, `wait()` can be used).

  If you need more control (e.g. block-wise gapless playback and recording, realtime processing, …), you should explicitly create a `Stream` yourself. If NumPy is not available, you can use a `RawStream`.

  Parameters:

    - data (array_like) – Audio data to be played back. See `play()`.

    - channels (int, sometimes optional) – Number of input channels, see `rec()`. The number of output channels is obtained from data.shape.

    - dtype (str or numpy.dtype, optional) – Input data type, see `rec()`. If dtype is not specified, it is taken from data.dtype (i.e. `default.dtype` is ignored). The output data type is obtained from data.dtype anyway.

    - input_mapping, output_mapping (array_like, optional) – See the parameter mapping of `rec()` and `play()`, respectively.

    - blocking (bool, optional) – If `False` (the default), return immediately (but continue playback/recording in the background), if `True`, wait until playback/recording is finished. A non-blocking invocation can be stopped with `stop()` or turned into a blocking one with `wait()`.

  Returns:

    numpy.ndarray or type(out) – The recorded data. See `rec()`.

  Other Parameters:

    - out (numpy.ndarray or subclass, optional) – See `rec()`.

    - samplerate, **kwargs – All parameters of `Stream` – except channels, dtype, callback and finished_callback – can be used.

  Notes

  If you don’t specify the correct sampling rate (either with the samplerate argument or by assigning a value to `default.samplerate`), the audio data will be played back, but it might be too slow or too fast!

  See also

  `play`, `rec`

sounddevice.wait(ignore_errors=True)

  Wait for `play()`/`rec()`/`playrec()` to be finished.

  Playback/recording can be stopped with a `KeyboardInterrupt`.

  Returns:

    CallbackFlags or None – If at least one buffer over-/underrun happened during the last playback/recording, a `CallbackFlags` object is returned.

  See also

  `get_status`

sounddevice.stop(ignore_errors=True)

  Stop playback/recording.

  This only stops `play()`, `rec()` and `playrec()`, but has no influence on streams created with `Stream`, `InputStream`, `OutputStream`, `RawStream`, `RawInputStream`, `RawOutputStream`.

sounddevice.get_status()

  Get info about over-/underflows in `play()`/`rec()`/`playrec()`.

  Returns:

    CallbackFlags – A `CallbackFlags` object that holds information about the last invocation of `play()`, `rec()` or `playrec()`.

  See also

  `wait`

sounddevice.get_stream()

  Get a reference to the current stream.

  This applies only to streams created by calls to `play()`, `rec()` or `playrec()`.

  Returns:

    Stream – An `OutputStream`, `InputStream` or `Stream` associated with the last invocation of `play()`, `rec()` or `playrec()`, respectively.