0
# Configuration and Settings
1

2
Module-wide defaults and platform-specific audio settings for optimal performance on different operating systems. These configuration options allow fine-tuning of audio behavior and hardware integration.
3

4
## Capabilities
5

6
### Default Settings
7

8
Module-wide default settings that apply to all audio operations when specific parameters are not provided.
9

10
```python { .api }
11
class default:
12
    """
13
    Module-wide default settings object.
14
    
15
    Attributes:
16
    - device (int or str or tuple): Default audio device(s)
17
    - samplerate (float): Default sample rate in Hz
18
    - blocksize (int): Default block size
19
    - channels (int or tuple): Default number of channels
20
    - dtype (str or numpy.dtype): Default data type for audio samples
21
    - latency (float or str): Default latency setting
22
    - extra_settings (object): Default platform-specific settings
23
    - clip_off (bool): Default clipping behavior
24
    - dither_off (bool): Default dithering behavior
25
    - never_drop_input (bool): Default input dropping behavior
26
    - prime_output_buffers_using_stream_callback (bool): Default buffer priming
27
    - hostapi (int): Default host API (read-only)
28
    """
29
    
30
    device = None
31
    samplerate = None
32
    blocksize = None
33
    channels = None
34
    dtype = None
35
    latency = None
36
    extra_settings = None
37
    clip_off = None
38
    dither_off = None
39
    never_drop_input = None
40
    prime_output_buffers_using_stream_callback = None
41
    
42
    @property
43
    def hostapi(self): ...
44
    
45
    def reset(self):
46
        """Reset all settings to their initial values."""
47
```
48

49
### Platform-Specific Settings
50

51
Specialized settings classes for different operating systems and audio APIs to optimize performance and access advanced features.
52

53
```python { .api }
54
class AsioSettings:
55
    """
56
    ASIO-specific audio settings for Windows.
57
    
58
    Parameters:
59
    - channel_selectors (list of int): Specific ASIO channel selection (zero-based)
60
    
61
    Attributes:
62
    - channel_selectors (list): Selected ASIO channels
63
    """
64
    
65
    def __init__(self, channel_selectors): ...
66
    
67
    channel_selectors: list
68

69
class CoreAudioSettings:
70
    """
71
    Core Audio settings for macOS.
72
    
73
    Parameters:
74
    - channel_map (array_like, optional): Channel mapping for Core Audio
75
    - change_device_parameters (bool, optional): Allow device parameter changes
76
    - fail_if_conversion_required (bool, optional): Fail if conversion is required
77
    - conversion_quality (str, optional): Conversion quality ('min', 'low', 'medium', 'high', 'max')
78
    
79
    Attributes:
80
    - channel_map (array_like): Channel mapping configuration
81
    - change_device_parameters (bool): Device parameter change permission
82
    - fail_if_conversion_required (bool): Conversion requirement setting
83
    - conversion_quality (str): Conversion quality setting
84
    """
85
    
86
    def __init__(self, channel_map=None, change_device_parameters=False, fail_if_conversion_required=False, conversion_quality='max'): ...
87
    
88
    channel_map: object
89
    change_device_parameters: bool
90
    fail_if_conversion_required: bool
91
    conversion_quality: str
92

93
class WasapiSettings:
94
    """
95
    WASAPI settings for Windows.
96
    
97
    Parameters:
98
    - exclusive (bool, optional): Use exclusive mode
99
    - auto_convert (bool, optional): Enable automatic format conversion
100
    
101
    Attributes:
102
    - exclusive (bool): Exclusive mode setting
103
    - auto_convert (bool): Automatic conversion setting
104
    """
105
    
106
    def __init__(self, exclusive=False, auto_convert=False): ...
107
    
108
    exclusive: bool
109
    auto_convert: bool
110
```
111

112
## Usage Examples
113

114
### Setting Module Defaults
115

116
```python
117
import sounddevice as sd
118

119
# Configure default settings for all subsequent operations
120
sd.default.samplerate = 48000
121
sd.default.channels = 2
122
sd.default.dtype = 'float32'
123
sd.default.device = 'USB Audio Device'
124

125
# Now all operations will use these defaults
126
recording = sd.rec(duration=3.0)  # Uses 48000 Hz, 2 channels, float32
127
sd.play(recording)  # Uses the configured default device
128

129
# Check current default settings
130
print(f"Default sample rate: {sd.default.samplerate}")
131
print(f"Default channels: {sd.default.channels}")
132
print(f"Default device: {sd.default.device}")
133
```
134

135
### Device-Specific Defaults
136

137
```python
138
import sounddevice as sd
139

140
# Set different devices for input and output
141
sd.default.device = ('Built-in Microphone', 'Built-in Output')
142

143
# Set different channel counts for input and output
144
sd.default.channels = (1, 2)  # 1 input channel, 2 output channels
145

146
# Simultaneous recording and playbook will use these settings
147
import numpy as np
148
test_signal = np.random.random((44100, 1))  # 1 second mono signal
149
recorded = sd.playrec(test_signal)  # Uses 1 input, 2 output channels
150
```
151

152
### Resetting Defaults
153

154
```python
155
import sounddevice as sd
156

157
# Modify some defaults
158
sd.default.samplerate = 96000
159
sd.default.channels = 8
160

161
# Reset all defaults to initial values
162
sd.default.reset()
163

164
print(f"Sample rate after reset: {sd.default.samplerate}")  # None
165
print(f"Channels after reset: {sd.default.channels}")      # None
166
```
167

168
### Windows ASIO Configuration
169

170
```python
171
import sounddevice as sd
172

173
# Configure ASIO settings for professional audio interfaces
174
asio_settings = sd.AsioSettings(channel_selectors=(0, 1, 2, 3))
175

176
# Use ASIO settings with a stream
177
with sd.Stream(
178
    device='ASIO Device',
179
    channels=4,
180
    samplerate=96000,
181
    extra_settings=asio_settings
182
) as stream:
183
    print("Using ASIO with selected channels")
184
    # Audio processing with ASIO optimizations
185
```
186

187
### macOS Core Audio Configuration
188

189
```python
190
import sounddevice as sd
191
import numpy as np
192

193
# Configure Core Audio settings
194
core_audio_settings = sd.CoreAudioSettings(
195
    channel_map=[0, 1, 4, 5],  # Use channels 0,1,4,5 from device
196
    change_device_parameters=True,
197
    priming_info=(512, 0)  # Prime with 512 frames
198
)
199

200
# Apply Core Audio settings
201
with sd.Stream(
202
    device='Built-in Output',
203
    channels=4,
204
    samplerate=44100,
205
    extra_settings=core_audio_settings
206
) as stream:
207
    print("Using Core Audio with custom channel mapping")
208
    # Use stream with optimized Core Audio settings
209
```
210

211
### Windows WASAPI Configuration
212

213
```python
214
import sounddevice as sd
215

216
# Configure WASAPI for exclusive mode (lower latency)
217
wasapi_settings = sd.WasapiSettings(
218
    exclusive=True,              # Use exclusive mode
219
    auto_convert=False,          # No automatic format conversion
220
    system_sample_rate=False,    # Don't use system sample rate
221
    thread_priority='high'       # High thread priority
222
)
223

224
# Use WASAPI settings for low-latency audio
225
try:
226
    with sd.Stream(
227
        device='Speakers',
228
        samplerate=44100,
229
        channels=2,
230
        latency='low',
231
        extra_settings=wasapi_settings
232
    ) as stream:
233
        print("Using WASAPI exclusive mode")
234
        print(f"Actual latency: {stream.latency}")
235
        # Low-latency audio processing
236
        
237
except sd.PortAudioError as e:
238
    print(f"Exclusive mode failed: {e}")
239
    print("Falling back to shared mode")
240
```
241

242
### Dynamic Configuration
243

244
```python
245
import sounddevice as sd
246

247
def configure_for_recording():
248
    """Configure defaults optimized for high-quality recording."""
249
    sd.default.samplerate = 96000
250
    sd.default.channels = 2
251
    sd.default.dtype = 'float32'
252
    sd.default.latency = 'high'  # Higher latency for stable recording
253
    sd.default.never_drop_input = True
254

255
def configure_for_realtime():
256
    """Configure defaults optimized for real-time processing."""
257
    sd.default.samplerate = 44100
258
    sd.default.channels = 2
259
    sd.default.dtype = 'float32'
260
    sd.default.latency = 'low'   # Lower latency for real-time
261
    sd.default.never_drop_input = False
262

263
# Use different configurations for different scenarios
264
configure_for_recording()
265
long_recording = sd.rec(duration=300.0)  # 5-minute high-quality recording
266

267
configure_for_realtime()
268
# Real-time processing with low latency
269
```
270

271
### Platform Detection and Automatic Configuration
272

273
```python
274
import sounddevice as sd
275
import platform
276

277
def configure_for_platform():
278
    """Automatically configure settings based on the current platform."""
279
    system = platform.system()
280
    
281
    if system == 'Windows':
282
        # Check for ASIO devices
283
        devices = sd.query_devices()
284
        asio_devices = [d for d in devices if 'ASIO' in d['name']]
285
        
286
        if asio_devices:
287
            print("ASIO device found, using ASIO settings")
288
            sd.default.extra_settings = sd.AsioSettings()
289
        else:
290
            print("Using WASAPI settings")
291
            sd.default.extra_settings = sd.WasapiSettings(
292
                exclusive=False,
293
                auto_convert=True
294
            )
295
    
296
    elif system == 'Darwin':  # macOS
297
        print("Using Core Audio settings")
298
        sd.default.extra_settings = sd.CoreAudioSettings(
299
            change_device_parameters=True
300
        )
301
    
302
    else:  # Linux and others
303
        print("Using default settings for ALSA/JACK")
304
        sd.default.extra_settings = None
305
    
306
    # Set reasonable defaults for all platforms
307
    sd.default.samplerate = 44100
308
    sd.default.channels = 2
309
    sd.default.dtype = 'float32'
310

311
# Apply platform-specific configuration
312
configure_for_platform()
313

314
# Check what was configured
315
print(f"Platform: {platform.system()}")
316
print(f"Extra settings: {type(sd.default.extra_settings)}")
317
```
318

319
## Default Settings Reference
320

321
The `default` object contains the following configurable attributes:
322

323
- `device`: Default audio device (int, str, or tuple for input/output)
324
- `samplerate`: Default sample rate in Hz (float)
325
- `blocksize`: Default block size (int)
326
- `channels`: Default channel count (int or tuple for input/output)
327
- `dtype`: Default data type ('float32', 'int16', 'int32', etc.)
328
- `latency`: Default latency ('low', 'high', or float in seconds)
329
- `extra_settings`: Default platform-specific settings object
330
- `clip_off`: Disable sample clipping (bool)
331
- `dither_off`: Disable dithering (bool)  
332
- `never_drop_input`: Never drop input samples (bool)
333
- `prime_output_buffers_using_stream_callback`: Prime output buffers (bool)
334
- `hostapi`: Default host API (int, read-only)
335

336
All attributes default to `None`, which means sounddevice will use its internal defaults or query the system for appropriate values.