0
# sounddevice
1

2
Python bindings for the PortAudio library, providing cross-platform audio input and output functionality. The library enables playing and recording NumPy arrays containing audio signals, with support for real-time streaming, callback-based processing, and integration with scientific computing workflows.
3

4
## Package Information
5

6
- **Package Name**: sounddevice
7
- **Language**: Python
8
- **Installation**: `pip install sounddevice`
9

10
## Core Imports
11

12
```python
13
import sounddevice as sd
14
```
15

16
Alternative imports:
17

18
```python
19
import sounddevice
20
from sounddevice import play, rec, query_devices
21
```
22

23
## Basic Usage
24

25
```python
26
import sounddevice as sd
27
import numpy as np
28

29
# Record audio for 5 seconds
30
duration = 5.0  # seconds
31
samplerate = 44100  # Hz
32
recording = sd.rec(int(duration * samplerate), samplerate=samplerate, channels=2)
33
sd.wait()  # Wait until recording is finished
34
print("Recording complete!")
35

36
# Play the recorded audio
37
sd.play(recording, samplerate=samplerate)
38
sd.wait()  # Wait until playback is finished
39

40
# Query available audio devices
41
devices = sd.query_devices()
42
print(devices)
43

44
# Set default device and parameters
45
sd.default.device = 'USB Audio Device'
46
sd.default.samplerate = 48000
47
sd.default.channels = 2
48
```
49

50
## Architecture
51

52
sounddevice provides multiple levels of abstraction for audio processing:
53

54
- **Convenience Functions**: High-level functions for simple audio operations (`play()`, `rec()`, `playrec()`)
55
- **Stream Classes**: Low-level stream objects for advanced control and real-time processing
56
- **Raw Streams**: Buffer-based streams when NumPy is not available
57
- **Device Management**: Functions to query and configure audio hardware
58
- **Platform Integration**: OS-specific settings classes for optimal performance
59

60
## Capabilities
61

62
### Convenience Functions
63

64
High-level functions for simple audio playback, recording, and simultaneous operations. These functions provide the easiest way to work with audio data using NumPy arrays.
65

66
```python { .api }
67
def play(data, samplerate=None, mapping=None, blocking=False, loop=False, **kwargs): ...
68
def rec(frames=None, samplerate=None, channels=None, dtype=None, out=None, mapping=None, blocking=False, **kwargs): ...  
69
def playrec(data, samplerate=None, channels=None, dtype=None, out=None, input_mapping=None, output_mapping=None, blocking=False, **kwargs): ...
70
def wait(ignore_errors=True): ...
71
def stop(ignore_errors=True): ...
72
def get_status(): ...
73
def get_stream(): ...
74
```
75

76
[Convenience Functions](./convenience-functions.md)
77

78
### Device Management
79

80
Functions to discover, query, and validate audio devices and host APIs. Essential for configuring audio hardware and ensuring compatibility across different systems.
81

82
```python { .api }
83
def query_devices(device=None, kind=None): ...
84
def query_hostapis(index=None): ...
85
def check_input_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None): ...
86
def check_output_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None): ...
87
```
88

89
[Device Management](./device-management.md)
90

91
### Stream Processing  
92

93
Low-level stream classes for advanced audio processing with full control over buffering, callbacks, and real-time operation. Supports both NumPy arrays and raw Python buffers.
94

95
```python { .api }
96
class Stream: ...
97
class InputStream: ...
98
class OutputStream: ...
99
class RawStream: ...
100
class RawInputStream: ...
101
class RawOutputStream: ...
102
```
103

104
[Stream Processing](./stream-processing.md)
105

106
### Configuration and Settings
107

108
Module-wide defaults and platform-specific audio settings for optimal performance on different operating systems.
109

110
```python { .api }
111
class default: ...
112
class AsioSettings: ...
113
class CoreAudioSettings: ...
114
class WasapiSettings: ...
115
```
116

117
[Configuration and Settings](./configuration.md)
118

119
### Utilities and Error Handling
120

121
Utility functions and exception classes for audio processing workflows and error management.
122

123
```python { .api }
124
def sleep(msec): ...
125
def get_portaudio_version(): ...
126

127
class PortAudioError(Exception): ...
128
class CallbackStop(Exception): ...
129
class CallbackAbort(Exception): ...
130
```
131

132
[Utilities and Error Handling](./utilities.md)
133

134
## Types
135

136
```python { .api }
137
class DeviceList(tuple):
138
    """Special tuple subclass containing device information."""
139
    
140
class CallbackFlags:
141
    """Status flags for stream callback functions."""
142
    input_underflow: bool
143
    input_overflow: bool
144
    output_underflow: bool
145
    output_overflow: bool
146
    priming_output: bool
147

148
class PortAudioError(Exception):
149
    """Exception raised for PortAudio-related errors."""
150

151
class CallbackStop(Exception):
152
    """Exception to signal stream callback should stop gracefully."""
153

154
class CallbackAbort(Exception):
155
    """Exception to signal stream callback should abort immediately."""
156
```
157

158
## Module Attributes
159

160
```python { .api }
161
__version__: str  # Module version string (e.g., '0.5.2')
162
```