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.