Checking Available Hardware§

sounddevice.query_devices(device=None, kind=None)[source]§

Return information about available devices.

Information and capabilities of PortAudio devices. Devices may support input, output or both input and output.

To find the default input/output device(s), use default.device.

Parameters:
  • device (int or str, optional) – Numeric device ID or device name substring(s). If specified, information about only the given device is returned in a single dictionary.

  • kind ({‘input’, ‘output’}, optional) – If device is not specified and kind is 'input' or 'output', a single dictionary is returned with information about the default input or output device, respectively.

Returns:

dict or DeviceList – A dictionary with information about the given device or – if no arguments were specified – a DeviceList containing one dictionary for each available device. The dictionaries have the following keys:

'name'

The name of the device.

'index'

The device index.

'hostapi'

The ID of the corresponding host API. Use query_hostapis() to get information about a host API.

'max_input_channels', 'max_output_channels'

The maximum number of input/output channels supported by the device. See default.channels.

'default_low_input_latency', 'default_low_output_latency'

Default latency values for interactive performance. This is used if default.latency (or the latency argument of playrec(), Stream etc.) is set to 'low'.

'default_high_input_latency', 'default_high_output_latency'

Default latency values for robust non-interactive applications (e.g. playing sound files). This is used if default.latency (or the latency argument of playrec(), Stream etc.) is set to 'high'.

'default_samplerate'

The default sampling frequency of the device. This is used if default.samplerate is not set.

Notes

The list of devices can also be displayed in a terminal:

python3 -m sounddevice

Examples

The returned DeviceList can be indexed and iterated over like any sequence type (yielding the abovementioned dictionaries), but it also has a special string representation which is shown when used in an interactive Python session.

Each available device is listed on one line together with the corresponding device ID, which can be assigned to default.device or used as device argument in play(), Stream etc.

The first character of a line is > for the default input device, < for the default output device and * for the default input/output device. After the device ID and the device name, the corresponding host API name is displayed. In the end of each line, the maximum number of input and output channels is shown.

On a GNU/Linux computer it might look somewhat like this:

>>> import sounddevice as sd
>>> sd.query_devices()
   0 HDA Intel: ALC662 rev1 Analog (hw:0,0), ALSA (2 in, 2 out)
   1 HDA Intel: ALC662 rev1 Digital (hw:0,1), ALSA (0 in, 2 out)
   2 HDA Intel: HDMI 0 (hw:0,3), ALSA (0 in, 8 out)
   3 sysdefault, ALSA (128 in, 128 out)
   4 front, ALSA (0 in, 2 out)
   5 surround40, ALSA (0 in, 2 out)
   6 surround51, ALSA (0 in, 2 out)
   7 surround71, ALSA (0 in, 2 out)
   8 iec958, ALSA (0 in, 2 out)
   9 spdif, ALSA (0 in, 2 out)
  10 hdmi, ALSA (0 in, 8 out)
* 11 default, ALSA (128 in, 128 out)
  12 dmix, ALSA (0 in, 2 out)
  13 /dev/dsp, OSS (16 in, 16 out)

Note that ALSA provides access to some “real” and some “virtual” devices. The latter sometimes have a ridiculously high number of (virtual) inputs and outputs.

On macOS, you might get something similar to this:

>>> sd.query_devices()
  0 Built-in Line Input, Core Audio (2 in, 0 out)
> 1 Built-in Digital Input, Core Audio (2 in, 0 out)
< 2 Built-in Output, Core Audio (0 in, 2 out)
  3 Built-in Line Output, Core Audio (0 in, 2 out)
  4 Built-in Digital Output, Core Audio (0 in, 2 out)
class sounddevice.DeviceList(iterable=(), /)[source]§

A list with information about all available audio devices.

This class is not meant to be instantiated by the user. Instead, it is returned by query_devices(). It contains a dictionary for each available device, holding the keys described in query_devices().

This class has a special string representation that is shown as return value of query_devices() if used in an interactive Python session. It will also be shown when using the print() function. Furthermore, it can be obtained with repr() and str().

sounddevice.query_hostapis(index=None)[source]§

Return information about available host APIs.

Parameters:

index (int, optional) – If specified, information about only the given host API index is returned in a single dictionary.

Returns:

dict or tuple of dict – A dictionary with information about the given host API index or – if no index was specified – a tuple containing one dictionary for each available host API. The dictionaries have the following keys:

'name'

The name of the host API.

'devices'

A list of device IDs belonging to the host API. Use query_devices() to get information about a device.

'default_input_device', 'default_output_device'

The device ID of the default input/output device of the host API. If no default input/output device exists for the given host API, this is -1.

Note

The overall default device(s) – which can be overwritten by assigning to default.device – take(s) precedence over default.hostapi and the information in the abovementioned dictionaries.

See also

query_devices

sounddevice.check_input_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None)[source]§

Check if given input device settings are supported.

All parameters are optional, default settings are used for any unspecified parameters. If the settings are supported, the function does nothing; if not, an exception is raised.

Parameters:
  • device (int or str, optional) – Device ID or device name substring(s), see default.device.

  • channels (int, optional) – Number of input channels, see default.channels.

  • dtype (str or numpy.dtype, optional) – Data type for input samples, see default.dtype.

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

  • samplerate (float, optional) – Sampling frequency, see default.samplerate.

sounddevice.check_output_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None)[source]§

Check if given output device settings are supported.

Same as check_input_settings(), just for output device settings.