0
# Core I/O Functions
1

2
Primary functions for reading and writing audio files with support for all major audio formats. These functions provide the most common interface for audio I/O operations with NumPy array data representation.
3

4
## Capabilities
5

6
### Reading Audio Files
7

8
Read complete audio files or portions of files into NumPy arrays with flexible data type and format support.
9

10
```python { .api }
11
def read(file, frames=-1, start=0, stop=None, dtype='float64', always_2d=False,
12
         fill_value=None, out=None, samplerate=None, channels=None,
13
         format=None, subtype=None, endian=None, closefd=True):
14
    """
15
    Read audio data from a sound file.
16
    
17
    Parameters:
18
    - file: str or file-like, path to input file or file-like object
19
    - frames: int, number of frames to read (-1 for all)
20
    - start: int, starting frame offset
21
    - stop: int, stop reading at this frame
22
    - dtype: str or numpy.dtype, data type of output array
23
    - always_2d: bool, return 2D array even for mono files
24
    - fill_value: float, value to use for missing frames
25
    - out: ndarray, pre-allocated output array
26
    - samplerate: int, expected sample rate (for validation)
27
    - channels: int, expected channel count (for validation)  
28
    - format: str, expected format (for validation)
29
    - subtype: str, expected subtype (for validation)
30
    - endian: str, expected endianness (for validation)
31
    - closefd: bool, close file descriptor when done
32
    
33
    Returns:
34
    - tuple: (audiodata: ndarray, samplerate: int)
35
      - audiodata: 1D or 2D NumPy array with shape (frames,) or (frames, channels)
36
      - samplerate: sample rate in Hz
37
    """
38
```
39

40
### Writing Audio Files
41

42
Write NumPy arrays to audio files with flexible format and compression options.
43

44
```python { .api }
45
def write(file, data, samplerate, subtype=None, endian=None, format=None,
46
          closefd=True, compression_level=None, bitrate_mode=None):
47
    """
48
    Write audio data to a sound file.
49
    
50
    Parameters:
51
    - file: str or file-like, output file path or file-like object
52
    - data: ndarray, audio data to write
53
    - samplerate: int, sample rate in Hz
54
    - subtype: str, audio subtype (e.g., 'PCM_16', 'FLOAT')
55
    - endian: str, byte order ('FILE', 'LITTLE', 'BIG', 'CPU')
56
    - format: str, file format (e.g., 'WAV', 'FLAC', 'OGG')
57
    - closefd: bool, close file descriptor when done
58
    - compression_level: float, compression level for applicable formats (0.0-1.0)
59
    - bitrate_mode: str, bitrate mode ('CONSTANT', 'AVERAGE', 'VARIABLE')
60
    
61
    Returns:
62
    - None
63
    """
64
```
65

66
### Block-wise Reading
67

68
Process large audio files memory-efficiently by reading in blocks with optional overlap.
69

70
```python { .api }
71
def blocks(file, blocksize=None, overlap=0, frames=-1, start=0, stop=None,
72
           dtype='float64', always_2d=False, fill_value=None, out=None,
73
           samplerate=None, channels=None, format=None, subtype=None,
74
           endian=None, closefd=True):
75
    """
76
    Return a generator for block-wise reading of audio data.
77
    
78
    Parameters:
79
    - file: str or file-like, input file path or file-like object
80
    - blocksize: int, frames per block (default: 65536)
81
    - overlap: int, overlapping frames between blocks
82
    - frames: int, total frames to read (-1 for all)
83
    - start: int, starting frame offset
84
    - stop: int, stop reading at this frame
85
    - dtype: str or numpy.dtype, data type of output arrays
86
    - always_2d: bool, return 2D arrays even for mono files
87
    - fill_value: float, value to use for missing frames
88
    - out: ndarray, pre-allocated output array template
89
    - samplerate: int, expected sample rate (for validation)
90
    - channels: int, expected channel count (for validation)
91
    - format: str, expected format (for validation)
92
    - subtype: str, expected subtype (for validation)
93
    - endian: str, expected endianness (for validation)
94
    - closefd: bool, close file descriptor when done
95
    
96
    Yields:
97
    - ndarray: audio data blocks with shape (blocksize,) or (blocksize, channels)
98
    """
99
```
100

101
## Usage Examples
102

103
### Basic File Reading and Writing
104

105
```python
106
import soundfile as sf
107
import numpy as np
108

109
# Read entire file
110
data, samplerate = sf.read('input.wav')
111
print(f'Loaded {data.shape[0]} frames at {samplerate} Hz')
112

113
# Read specific portion
114
data_portion, sr = sf.read('input.wav', start=1000, frames=2048)
115

116
# Write with different format
117
sf.write('output.flac', data, samplerate, format='FLAC', subtype='PCM_16')
118
```
119

120
### Block Processing
121

122
```python
123
import soundfile as sf
124
import numpy as np
125

126
# Process large file in blocks
127
def process_large_file(input_file, output_file, effect_function):
128
    with sf.SoundFile(output_file, 'w', samplerate=44100, channels=2, 
129
                      format='WAV') as outfile:
130
        for block in sf.blocks(input_file, blocksize=1024):
131
            processed_block = effect_function(block)
132
            outfile.write(processed_block)
133

134
# Example effect function
135
def apply_gain(audio_block, gain=0.5):
136
    return audio_block * gain
137

138
process_large_file('large_input.wav', 'processed_output.wav', apply_gain)
139
```
140

141
### Type Conversion and Validation
142

143
```python
144
import soundfile as sf
145

146
# Read as specific data type
147
data_int16, sr = sf.read('input.wav', dtype='int16')
148
data_float32, sr = sf.read('input.wav', dtype='float32')
149

150
# Validate file properties during read
151
try:
152
    data, sr = sf.read('input.wav', samplerate=44100, channels=2)
153
    print("File matches expected properties")
154
except RuntimeError as e:
155
    print(f"File validation failed: {e}")
156
```