Audio IO (dsptoolbox.audio_io)¶
Audio IO¶
This module handles audio playback and recording. It is based on sounddevice (see link down below).
Setting audio device:
set_device()
print_device_info()
default_config
set_latency()
set_blocksize()
Playing audio:
play()
play_and_record()
output_stream()
Recording:
record()
Others:
CallbackStop() (used for stopping callbacks)
sleep() (sleep while audio playback is finished)
References¶
- dsptoolbox.audio_io.CallbackStop()¶
Wrapper around sounddevice’s CallbackStop. Used for stopping audio streamings.
- dsptoolbox.audio_io.output_stream(signal: Signal, blocksize=2048, device=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)¶
Creates and return a sounddevice’s OutputStream object. See sounddevice’s documentation for more information.
- Parameters:
- signalSignal
Signal for which the output stream will be created.
- blocksizeint, optional
Block size to be used during the stream. Default: 2048.
- devicestr, optional
Device to be used. Pass None to use default device. Default: None.
- callbackcallable
Function that defines the audio callback:
callback(outdata: NDArray[np.float64], frames: int, time: CData, status: CallbackFlags) -> None
- finished_callbackcallable
- clip_offoptional
- dither_offoptional
- never_drop_inputoptional
- prime_output_buffers_using_stream_callbackoptional
- Returns:
- streamsd.OutputStream
Stream object.
References
- dsptoolbox.audio_io.play(signal: Signal, duration_seconds: float | None = None, normalized_dbfs: float | None = -6, device: str | None = None, play_channels: int | list | tuple | None = None)¶
Playback of signal using some available device. Note that the channel numbers start here with 1.
- Parameters:
- signalSignal
Signal to be reproduced. Its channel number must match the the length of the play_channels vector.
- duration_secondsfloat, optional
If None, the whole signal is played, otherwise it is trimmed to the given length. Default: None.
- normalized_dbfs: float, optional
Normalizes the signal (dBFS peak level) before playing it. Set to None to ignore normalization. Default: -6.
- devicestr, optional
I/O device to be used. If None, the default device is used. Default: None.
- play_channelsint or array-like, optional
Output channels that will play the signal. The number of channels should match the number of channels in signal. When None, the channels are automatically set. Default: None.
- dsptoolbox.audio_io.play_and_record(signal: Signal, duration_seconds: float | None = None, normalized_dbfs: float | None = -6, device: str | None = None, play_channels=None, rec_channels=[1]) Signal¶
Play and record using some available device. Note that the channel numbers start here with 1.
- Parameters:
- signalSignal
Signal object to be played. The number of channels has to match the total length and order of play_channels. The sampling rate of signal will define the sampling rate of the recorded signals.
- duration_secondsfloat, optional
If None, the whole signal is played, otherwise it is trimmed to the given length. Default: None.
- normalized_dbfs: float, optional
Normalizes the signal (dBFS peak level) before playing it. Set to None to ignore normalization. Default: -6.
- devicestr, optional
I/O device to be used. If None, the default device is used. Default: None.
- play_channelsint or array-like, optional
Output channels that will play the signal. The number of channels should match the number of channels in signal. When None, the channels are automatically set. Default: None.
- rec_channelsint or array-like, optional
Channel numbers that will be recorded. Default: [1].
- Returns:
- rec_sigSignal
Recorded signal.
- dsptoolbox.audio_io.print_device_info(device_number: int | None = None)¶
Prints available audio devices or information about a certain device when the device number is given.
- Parameters:
- device_numberint, optional
Prints information about the specific device and returns it as a dictionary. Use None to only print information about all devices without returning anything. Default: None.
- Returns:
- ddict or sounddevice.DeviceList
dict of a device when device number is passed or DeviceList when None is passed.
- dsptoolbox.audio_io.record(duration_seconds: float = 5, sampling_rate_hz: int = 48000, device: str | int | None = None, rec_channels=[1]) Signal¶
Record using some available device. Note that the channel numbers start here with 1.
- Parameters:
- duration_secondsfloat, optional
Duration of recording in seconds. Default: 5.
- sampling_rate_hzint, optional
Sampling rate used for recording. Default: 48000.
- devicestr, optional
I/O device to be used. If None, the default device is used. Default: None.
- rec_channelsint or array-like, optional
Number that will be recorded. Default: [1].
- Returns:
- rec_sigSignal
Recorded signal.
- dsptoolbox.audio_io.set_blocksize(blocksize: int)¶
Set a default blocksize for any stream. This can lead to a stable latency for most interfaces. Not setting it will lead to a default value.
This method modifies the global default value.
- Parameters:
- blocksizeint
Desired block size.
- dsptoolbox.audio_io.set_device(device: list[int] | list[str] | str | int | None = None, sampling_rate_hz: int | None = None)¶
Takes in a device number to set it as the default for the input and the output. If None is passed, the available devices are first shown and then the user is asked for input to set the device two values separated by a comma “input_int, output_int”.
- Parameters:
- devicelist[int | str] with length 2, str, int, None, optional
Sets the input and output devices from two integers, e.g. [1, 2]. Alternatively, two strings contained in the interface’s name (or the name itself) can be passed. The first interface to match will be taken. If passing only one string or integer, the interface will be taken for both input and output. Use None to be prompted with the options and pass only two values separated by a comma, e.g., 1, 2. Default: None.
- sampling_rate_hzint, None, optional
Pass a default sampling rate to the devices. Pass None to ignore. Default: None.
- Returns:
- device_listsounddevice.DeviceList
Device List with dictionaries containing information about each available device if device=None.
- dsptoolbox.audio_io.set_latency(input_low: bool, output_low: bool)¶
Set the desired latency (Default is high). This can vary for each device and host. Sounddevice only allows for setting a low or a high latency. High latency is more robust, but it might be too large for some applications.
This method modifies the global default value.
- Parameters:
- input_lowbool
When True, low latency will be requested to the host for input streams.
- output_lowbool
When True, low latency will be requested to the host for output streams.