0
# Device Management
1

2
Functions to discover, query, and validate audio devices and host APIs. These functions are essential for configuring audio hardware, ensuring compatibility across different systems, and optimizing audio performance for specific platforms.
3

4
## Capabilities
5

6
### Device Discovery
7

8
Query information about available audio devices, including input and output capabilities, supported sample rates, and channel configurations.
9

10
```python { .api }
11
def query_devices(device=None, kind=None):
12
    """
13
    Query information about available audio devices.
14
    
15
    Parameters:
16
    - device (int or str, optional): Device index or name to query specific device
17
    - kind (str, optional): 'input' or 'output' to filter device types
18
    
19
    Returns:
20
    DeviceList or dict: List of all devices or single device information dict
21
    """
22
```
23

24
### Host API Information
25

26
Query information about available host APIs (audio system backends) such as ASIO, DirectSound, WASAPI, Core Audio, ALSA, and JACK.
27

28
```python { .api }
29
def query_hostapis(index=None):
30
    """
31
    Query information about available host APIs.
32
    
33
    Parameters:
34
    - index (int, optional): Host API index to query specific API
35
    
36
    Returns:
37
    tuple or dict: Tuple of all host APIs or single host API information dict
38
    """
39
```
40

41
### Settings Validation
42

43
Validate input and output device settings before use, ensuring compatibility and preventing runtime errors.
44

45
```python { .api }
46
def check_input_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None):
47
    """
48
    Check if input device settings are valid.
49
    
50
    Parameters:
51
    - device (int or str, optional): Input device to check
52
    - channels (int, optional): Number of input channels
53
    - dtype (str or numpy.dtype, optional): Input data type
54
    - extra_settings (settings object, optional): Host-API-specific settings
55
    - samplerate (float, optional): Sample rate in Hz
56
    
57
    Returns:
58
    None
59
    
60
    Raises:
61
    PortAudioError: If settings are invalid
62
    """
63

64
def check_output_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None):
65
    """
66
    Check if output device settings are valid.
67
    
68
    Parameters:
69
    - device (int or str, optional): Output device to check  
70
    - channels (int, optional): Number of output channels
71
    - dtype (str or numpy.dtype, optional): Output data type
72
    - extra_settings (settings object, optional): Host-API-specific settings
73
    - samplerate (float, optional): Sample rate in Hz
74
    
75
    Returns:
76
    None
77
    
78
    Raises:
79
    PortAudioError: If settings are invalid
80
    """
81
```
82

83
## Usage Examples
84

85
### Listing Available Devices
86

87
```python
88
import sounddevice as sd
89

90
# List all available devices
91
devices = sd.query_devices()
92
print(devices)
93

94
# List only input devices
95
input_devices = sd.query_devices(kind='input')
96
print("Input devices:")
97
for i, device in enumerate(input_devices):
98
    print(f"  {i}: {device['name']}")
99

100
# List only output devices  
101
output_devices = sd.query_devices(kind='output')
102
print("Output devices:")
103
for i, device in enumerate(output_devices):
104
    print(f"  {i}: {device['name']}")
105
```
106

107
### Getting Specific Device Information
108

109
```python
110
import sounddevice as sd
111

112
# Get information about default input device
113
default_input = sd.query_devices(kind='input')
114
print(f"Default input device: {default_input}")
115

116
# Get information about a specific device by index
117
device_info = sd.query_devices(device=1)
118
print(f"Device 1: {device_info}")
119

120
# Get information about a device by name (partial match)
121
usb_devices = [d for d in sd.query_devices() if 'USB' in d['name']]
122
if usb_devices:
123
    print(f"USB device: {usb_devices[0]}")
124
```
125

126
### Querying Host APIs
127

128
```python
129
import sounddevice as sd
130

131
# List all available host APIs
132
hostapis = sd.query_hostapis()
133
print("Available host APIs:")
134
for i, api in enumerate(hostapis):
135
    print(f"  {i}: {api['name']} ({api['device_count']} devices)")
136

137
# Get information about a specific host API
138
if len(hostapis) > 0:
139
    api_info = sd.query_hostapis(index=0)
140
    print(f"Host API 0: {api_info}")
141
```
142

143
### Validating Device Settings
144

145
```python
146
import sounddevice as sd
147

148
try:
149
    # Check if we can record from default input device
150
    sd.check_input_settings(
151
        channels=2, 
152
        samplerate=44100, 
153
        dtype='float32'
154
    )
155
    print("Input settings are valid")
156
    
157
    # Check if we can play to default output device
158
    sd.check_output_settings(
159
        channels=2,
160
        samplerate=44100,
161
        dtype='float32'
162
    )
163
    print("Output settings are valid")
164
    
165
except sd.PortAudioError as e:
166
    print(f"Invalid settings: {e}")
167
```
168

169
### Finding Best Device Configuration
170

171
```python
172
import sounddevice as sd
173

174
def find_best_input_device():
175
    """Find the best input device with highest sample rate support."""
176
    devices = sd.query_devices(kind='input')
177
    best_device = None
178
    best_samplerate = 0
179
    
180
    for i, device in enumerate(devices):
181
        if device['max_input_channels'] > 0:
182
            # Test supported sample rates
183
            for rate in [96000, 48000, 44100, 22050]:
184
                try:
185
                    sd.check_input_settings(
186
                        device=i,
187
                        samplerate=rate,
188
                        channels=min(2, device['max_input_channels'])
189
                    )
190
                    if rate > best_samplerate:
191
                        best_device = i
192
                        best_samplerate = rate
193
                    break
194
                except sd.PortAudioError:
195
                    continue
196
    
197
    return best_device, best_samplerate
198

199
device_idx, samplerate = find_best_input_device()
200
if device_idx is not None:
201
    device_info = sd.query_devices(device=device_idx)
202
    print(f"Best input device: {device_info['name']} at {samplerate} Hz")
203
```
204

205
## Device Information Structure
206

207
Device information dictionaries contain the following keys:
208

209
```python
210
{
211
    'name': str,                    # Device name
212
    'index': int,                   # Device index  
213
    'hostapi': int,                 # Host API index
214
    'max_input_channels': int,      # Maximum input channels
215
    'max_output_channels': int,     # Maximum output channels
216
    'default_low_input_latency': float,    # Low latency for input
217
    'default_low_output_latency': float,   # Low latency for output
218
    'default_high_input_latency': float,   # High latency for input  
219
    'default_high_output_latency': float,  # High latency for output
220
    'default_samplerate': float     # Default sample rate
221
}
222
```
223

224
Host API information dictionaries contain:
225

226
```python
227
{
228
    'name': str,           # Host API name (e.g., 'WASAPI', 'DirectSound', 'ASIO')
229
    'device_count': int,   # Number of devices using this host API
230
    'default_input_device': int,   # Default input device index (-1 if none)
231
    'default_output_device': int,  # Default output device index (-1 if none)  
232
    'type': int           # Host API type identifier
233
}
234
```