# Checking Available Hardware

Overview

`query_devices` | Return information about available devices.
`DeviceList` | A list with information about all available audio devices.
`query_hostapis` | Return information about available host APIs.
`check_input_settings` | Check if given input device settings are supported.
`check_output_settings` | Check if given output device settings are supported.

sounddevice.query_devices(device=None, kind=None)

  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=(), /)

  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)

  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)

  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)

  Check if given output device settings are supported.

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