0
# SoundFile Class
1

2
Object-oriented interface for advanced audio file handling with context manager support, seek operations, metadata access, and buffer-based I/O. The SoundFile class provides fine-grained control over audio file operations.
3

4
## Capabilities
5

6
### Class Constructor
7

8
Create SoundFile objects for reading or writing audio files with extensive configuration options.
9

10
```python { .api }
11
class SoundFile:
12
    def __init__(self, file, mode='r', samplerate=None, channels=None,
13
                 subtype=None, endian=None, format=None, closefd=True,
14
                 compression_level=None, bitrate_mode=None):
15
        """
16
        Create a SoundFile object for audio I/O operations.
17
        
18
        Parameters:
19
        - file: str or file-like, file path or file-like object
20
        - mode: str, file mode ('r', 'w', 'x', 'r+', 'w+', 'x+')
21
        - samplerate: int, sample rate for writing (required for write modes)
22
        - channels: int, channel count for writing (required for write modes)
23
        - subtype: str, audio subtype (e.g., 'PCM_16', 'FLOAT')
24
        - endian: str, byte order ('FILE', 'LITTLE', 'BIG', 'CPU')
25
        - format: str, file format (e.g., 'WAV', 'FLAC', 'OGG')
26
        - closefd: bool, close file descriptor when SoundFile is closed
27
        - compression_level: int, compression level for applicable formats
28
        - bitrate_mode: str, bitrate mode ('CONSTANT', 'AVERAGE', 'VARIABLE')
29
        """
30
```
31

32
### Reading Methods
33

34
Read audio data with flexible options for data types, array shapes, and output buffers.
35

36
```python { .api }
37
def read(self, frames=-1, dtype='float64', always_2d=False, 
38
         fill_value=None, out=None):
39
    """
40
    Read audio data from the file.
41
    
42
    Parameters:
43
    - frames: int, number of frames to read (-1 for all remaining)
44
    - dtype: str or numpy.dtype, data type of output array
45
    - always_2d: bool, return 2D array even for mono files
46
    - fill_value: float, value to use for missing frames
47
    - out: ndarray, pre-allocated output array
48
    
49
    Returns:
50
    - ndarray: audio data with shape (frames,) or (frames, channels)
51
    """
52

53
def buffer_read(self, frames=-1, dtype=None):
54
    """
55
    Read raw audio data into a buffer.
56
    
57
    Parameters:
58
    - frames: int, number of frames to read (-1 for all remaining)
59
    - dtype: str or numpy.dtype, data type for raw buffer
60
    
61
    Returns:
62
    - bytes: raw audio data buffer
63
    """
64

65
def buffer_read_into(self, buffer, dtype):
66
    """
67
    Read audio data directly into an existing buffer.
68
    
69
    Parameters:
70
    - buffer: buffer-like, existing buffer to read into
71
    - dtype: str or numpy.dtype, data type of buffer
72
    
73
    Returns:
74
    - int: number of frames actually read
75
    """
76
```
77

78
### Writing Methods
79

80
Write audio data with support for NumPy arrays and raw buffers.
81

82
```python { .api }
83
def write(self, data):
84
    """
85
    Write audio data to the file.
86
    
87
    Parameters:
88
    - data: ndarray, audio data to write
89
    
90
    Returns:
91
    - None
92
    """
93

94
def buffer_write(self, data, dtype):
95
    """
96
    Write raw audio data from a buffer.
97
    
98
    Parameters:
99
    - data: buffer-like, raw audio data buffer
100
    - dtype: str or numpy.dtype, data type of buffer
101
    
102
    Returns:
103
    - None
104
    """
105
```
106

107
### File Positioning and Control
108

109
Navigate within audio files and control file operations.
110

111
```python { .api }
112
def seek(self, frames, whence=0):
113
    """
114
    Seek to a position in the file.
115
    
116
    Parameters:
117
    - frames: int, frame position to seek to
118
    - whence: int, reference point (SEEK_SET, SEEK_CUR, SEEK_END)
119
    
120
    Returns:
121
    - int: new absolute position in frames
122
    """
123

124
def tell(self):
125
    """
126
    Return current position in frames.
127
    
128
    Returns:
129
    - int: current frame position
130
    """
131

132
def seekable(self):
133
    """
134
    Check if the file supports seeking.
135
    
136
    Returns:
137
    - bool: True if file supports seek operations
138
    """
139

140
def truncate(self, frames=None):
141
    """
142
    Truncate the file to a specific length.
143
    
144
    Parameters:
145
    - frames: int, length to truncate to (None for current position)
146
    
147
    Returns:
148
    - None
149
    """
150

151
def flush(self):
152
    """Flush write buffers to disk."""
153

154
def close(self):
155
    """Close the file."""
156
```
157

158
### Block Processing
159

160
Generate blocks of audio data for memory-efficient processing.
161

162
```python { .api }
163
def blocks(self, blocksize=None, overlap=0, frames=-1, dtype='float64',
164
           always_2d=False, fill_value=None, out=None):
165
    """
166
    Return a generator for block-wise reading.
167
    
168
    Parameters:
169
    - blocksize: int, frames per block (default: 65536)
170
    - overlap: int, overlapping frames between blocks
171
    - frames: int, total frames to read (-1 for all remaining)
172
    - dtype: str or numpy.dtype, data type of output arrays
173
    - always_2d: bool, return 2D arrays even for mono files
174
    - fill_value: float, value to use for missing frames
175
    - out: ndarray, pre-allocated output array template
176
    
177
    Yields:
178
    - ndarray: audio data blocks
179
    """
180
```
181

182
### Metadata Operations
183

184
Handle file metadata copying between SoundFile objects.
185

186
```python { .api }
187
def copy_metadata(self):
188
    """
189
    Get all metadata present in this SoundFile.
190
    
191
    Returns:
192
    - dict: dictionary with all metadata. Possible keys are: 'title', 
193
            'copyright', 'software', 'artist', 'comment', 'date', 'album', 
194
            'license', 'tracknumber', 'genre'
195
    """
196
```
197

198
## Properties
199

200
### File Information Properties
201

202
```python { .api }
203
name: str  # File name or path
204
mode: str  # File open mode
205
samplerate: int  # Sample rate in Hz
206
frames: int  # Total number of frames
207
channels: int  # Number of audio channels
208
format: str  # Major format (e.g., 'WAV', 'FLAC')
209
subtype: str  # Audio subtype (e.g., 'PCM_16', 'FLOAT')
210
endian: str  # Byte order ('LITTLE', 'BIG', 'FILE', 'CPU')
211
format_info: str  # Human-readable format description
212
subtype_info: str  # Human-readable subtype description
213
sections: int  # Number of sections in file
214
closed: bool  # Whether file is closed
215
extra_info: str  # Additional information from libsndfile
216
compression_level: float  # Compression level for writing (0.0-1.0)
217
bitrate_mode: str  # Bitrate mode for writing
218
```
219

220
### Metadata Properties
221

222
Readable and writable metadata properties for audio files.
223

224
```python { .api }
225
title: str  # Song/track title
226
copyright: str  # Copyright information
227
software: str  # Software used to create the file
228
artist: str  # Artist/performer name
229
comment: str  # Comments or description
230
date: str  # Creation or recording date
231
album: str  # Album name
232
license: str  # License information
233
tracknumber: str  # Track number
234
genre: str  # Musical genre
235
```
236

237
## Usage Examples
238

239
### Context Manager Usage
240

241
```python
242
import soundfile as sf
243
import numpy as np
244

245
# Reading with context manager
246
with sf.SoundFile('input.wav', 'r') as file:
247
    print(f'Sample rate: {file.samplerate}')
248
    print(f'Channels: {file.channels}')
249
    print(f'Frames: {file.frames}')
250
    
251
    # Read all data
252
    data = file.read()
253
    
254
    # Read in blocks
255
    for block in file.blocks(blocksize=1024):
256
        # Process each block
257
        processed = block * 0.8
258

259
# Writing with context manager
260
data = np.random.randn(44100, 2)  # 1 second stereo
261
with sf.SoundFile('output.wav', 'w', samplerate=44100, channels=2) as file:
262
    file.write(data)
263
```
264

265
### Seek Operations
266

267
```python
268
import soundfile as sf
269

270
with sf.SoundFile('audio.wav', 'r') as file:
271
    # Jump to 1 second mark
272
    file.seek(file.samplerate)
273
    
274
    # Read 0.5 seconds of audio
275
    data = file.read(file.samplerate // 2)
276
    
277
    # Get current position
278
    position = file.tell()
279
    print(f'Current position: {position} frames')
280
    
281
    # Seek relative to current position
282
    file.seek(1000, sf.SEEK_CUR)
283
    
284
    # Seek from end
285
    file.seek(-1000, sf.SEEK_END)
286
```
287

288
### Metadata Handling
289

290
```python
291
import soundfile as sf
292

293
# Read metadata
294
with sf.SoundFile('music.flac', 'r') as file:
295
    print(f'Title: {file.title}')
296
    print(f'Artist: {file.artist}')
297
    print(f'Album: {file.album}')
298
    print(f'Genre: {file.genre}')
299

300
# Write with metadata
301
data = np.random.randn(44100, 2)
302
with sf.SoundFile('output.flac', 'w', samplerate=44100, channels=2, 
303
                  format='FLAC') as file:
304
    file.title = 'My Song'
305
    file.artist = 'My Band'
306
    file.album = 'My Album'
307
    file.genre = 'Electronic'
308
    file.write(data)
309
```
310

311
### Advanced File Operations
312

313
```python
314
import soundfile as sf
315
import numpy as np
316

317
# Copy with processing and metadata
318
with sf.SoundFile('input.wav', 'r') as infile:
319
    with sf.SoundFile('output.wav', 'w', samplerate=infile.samplerate,
320
                      channels=infile.channels, format=infile.format) as outfile:
321
        # Copy metadata
322
        metadata = infile.copy_metadata()
323
        for key, value in metadata.items():
324
            setattr(outfile, key, value)
325
        
326
        # Process in blocks
327
        for block in infile.blocks(blocksize=4096):
328
            # Apply some processing
329
            processed_block = np.tanh(block * 2.0)  # Soft clipping
330
            outfile.write(processed_block)
331
        
332
        # Flush to ensure all data is written
333
        outfile.flush()
334
```