0
# File Information and Format Support
1

2
Utilities for querying file information, discovering available formats and subtypes, validating format combinations, and retrieving format defaults. These functions help with format detection and validation.
3

4
## Capabilities
5

6
### File Information
7

8
Query detailed information about audio files without loading the full audio data.
9

10
```python { .api }
11
def info(file, verbose=False):
12
    """
13
    Get information about a sound file.
14
    
15
    Parameters:
16
    - file: str or file-like, path to audio file or file-like object
17
    - verbose: bool, if True include extra format information
18
    
19
    Returns:
20
    - _SoundFileInfo: object with file information attributes:
21
      - name: str, file name
22
      - samplerate: int, sample rate in Hz
23
      - frames: int, total number of frames
24
      - channels: int, number of audio channels
25
      - duration: float, duration in seconds (frames / samplerate)
26
      - format: str, major format
27
      - subtype: str, audio subtype
28
      - endian: str, byte order
29
      - format_info: str, human-readable format description
30
      - subtype_info: str, human-readable subtype description
31
      - sections: int, number of sections
32
      - extra_info: str, additional information
33
      - verbose: bool, whether verbose information was requested
34
    """
35

36
class _SoundFileInfo:
37
    """
38
    Information object returned by info() function.
39
    
40
    Attributes:
41
    - name: str, file name or path
42
    - samplerate: int, sample rate in Hz
43
    - frames: int, total number of frames
44
    - channels: int, number of audio channels
45
    - duration: float, duration in seconds (frames / samplerate)
46
    - format: str, major format
47
    - subtype: str, audio subtype
48
    - endian: str, byte order
49
    - format_info: str, human-readable format description
50
    - subtype_info: str, human-readable subtype description
51
    - sections: int, number of sections
52
    - extra_info: str, additional information
53
    - verbose: bool, whether verbose information was requested
54
    """
55
```
56

57
### Available Formats
58

59
Discover supported file formats and their capabilities.
60

61
```python { .api }
62
def available_formats():
63
    """
64
    Get dictionary of available major file formats.
65
    
66
    Returns:
67
    - dict: mapping of format names to descriptions
68
      Keys include: 'WAV', 'AIFF', 'AU', 'RAW', 'PAF', 'SVX', 'NIST', 
69
                   'VOC', 'IRCAM', 'W64', 'MAT4', 'MAT5', 'PVF', 'XI', 
70
                   'HTK', 'SDS', 'AVR', 'WAVEX', 'SD2', 'FLAC', 'CAF', 
71
                   'WVE', 'OGG', 'MPC2K', 'RF64', 'MP3'
72
    """
73
```
74

75
### Available Subtypes
76

77
Discover supported audio data subtypes, optionally filtered by format.
78

79
```python { .api }
80
def available_subtypes(format=None):
81
    """
82
    Get dictionary of available audio subtypes.
83
    
84
    Parameters:
85
    - format: str, optional format to filter subtypes for
86
    
87
    Returns:
88
    - dict: mapping of subtype names to descriptions
89
      Keys include: 'PCM_S8', 'PCM_16', 'PCM_24', 'PCM_32', 'PCM_U8',
90
                   'FLOAT', 'DOUBLE', 'ULAW', 'ALAW', 'IMA_ADPCM',
91
                   'MS_ADPCM', 'GSM610', 'VOX_ADPCM', 'VORBIS', 'OPUS',
92
                   'ALAC_16', 'ALAC_20', 'ALAC_24', 'ALAC_32',
93
                   'MPEG_LAYER_I', 'MPEG_LAYER_II', 'MPEG_LAYER_III'
94
    """
95
```
96

97
### Format Validation
98

99
Check if format combinations are valid before attempting file operations.
100

101
```python { .api }
102
def check_format(format, subtype=None, endian=None):
103
    """
104
    Check if combination of format/subtype/endian is valid.
105
    
106
    Parameters:
107
    - format: str, major format name (e.g., 'WAV', 'FLAC')
108
    - subtype: str, optional subtype (e.g., 'PCM_16', 'FLOAT')
109
    - endian: str, optional endianness ('FILE', 'LITTLE', 'BIG', 'CPU')
110
    
111
    Returns:
112
    - bool: True if the combination is valid, False otherwise
113
    """
114
```
115

116
### Default Subtypes
117

118
Get the default subtype for a given format.
119

120
```python { .api }
121
def default_subtype(format):
122
    """
123
    Get the default subtype for a given format.
124
    
125
    Parameters:
126
    - format: str, major format name
127
    
128
    Returns:
129
    - str or None: default subtype name, or None if format is invalid
130
    """
131
```
132

133
## Usage Examples
134

135
### File Exploration
136

137
```python
138
import soundfile as sf
139

140
# Get basic file information
141
file_info = sf.info('audio.wav')
142
print(f'File: {file_info.name}')
143
print(f'Duration: {file_info.frames / file_info.samplerate:.2f} seconds')
144
print(f'Sample rate: {file_info.samplerate} Hz')
145
print(f'Channels: {file_info.channels}')
146
print(f'Format: {file_info.format} ({file_info.format_info})')
147
print(f'Subtype: {file_info.subtype} ({file_info.subtype_info})')
148

149
# Get verbose information
150
verbose_info = sf.info('audio.wav', verbose=True)
151
print(f'Extra info: {verbose_info.extra_info}')
152
```
153

154
### Format Discovery
155

156
```python
157
import soundfile as sf
158

159
# List all available formats
160
formats = sf.available_formats()
161
print("Available formats:")
162
for fmt, description in formats.items():
163
    print(f'  {fmt}: {description}')
164

165
# List subtypes for a specific format
166
wav_subtypes = sf.available_subtypes('WAV')
167
print("\\nWAV subtypes:")
168
for subtype, description in wav_subtypes.items():
169
    print(f'  {subtype}: {description}')
170

171
# Get all subtypes
172
all_subtypes = sf.available_subtypes()
173
print(f"\\nTotal subtypes available: {len(all_subtypes)}")
174
```
175

176
### Format Validation and Defaults
177

178
```python
179
import soundfile as sf
180

181
# Check if format combinations are valid
182
combinations = [
183
    ('WAV', 'PCM_16', 'LITTLE'),
184
    ('FLAC', 'PCM_24', None),
185
    ('OGG', 'VORBIS', None),
186
    ('MP3', 'MPEG_LAYER_III', None),
187
    ('WAV', 'VORBIS', None),  # Invalid combination
188
]
189

190
for fmt, subtype, endian in combinations:
191
    is_valid = sf.check_format(fmt, subtype, endian)
192
    print(f'{fmt}/{subtype}/{endian}: {"Valid" if is_valid else "Invalid"}')
193

194
# Get default subtypes for formats
195
formats_to_check = ['WAV', 'FLAC', 'OGG', 'AIFF']
196
for fmt in formats_to_check:
197
    default = sf.default_subtype(fmt)
198
    print(f'{fmt} default subtype: {default}')
199
```
200

201
### Smart Format Selection
202

203
```python
204
import soundfile as sf
205
import numpy as np
206

207
def write_with_best_quality(filename, data, samplerate):
208
    """Write audio with the best quality subtype for the format."""
209
    
210
    # Determine format from filename extension
211
    ext = filename.split('.')[-1].upper()
212
    format_map = {
213
        'WAV': 'WAV',
214
        'FLAC': 'FLAC', 
215
        'OGG': 'OGG',
216
        'AIFF': 'AIFF'
217
    }
218
    
219
    format_name = format_map.get(ext, 'WAV')
220
    
221
    # Get available subtypes for this format
222
    subtypes = sf.available_subtypes(format_name)
223
    
224
    # Choose best quality subtype
225
    quality_preference = ['FLOAT', 'DOUBLE', 'PCM_32', 'PCM_24', 'PCM_16']
226
    best_subtype = None
227
    
228
    for preferred in quality_preference:
229
        if preferred in subtypes:
230
            # Verify this combination is valid
231
            if sf.check_format(format_name, preferred):
232
                best_subtype = preferred
233
                break
234
    
235
    if best_subtype is None:
236
        # Fall back to default
237
        best_subtype = sf.default_subtype(format_name)
238
    
239
    print(f'Writing {filename} as {format_name}/{best_subtype}')
240
    sf.write(filename, data, samplerate, format=format_name, subtype=best_subtype)
241

242
# Example usage
243
data = np.random.randn(44100, 2)  # 1 second stereo
244
write_with_best_quality('output.wav', data, 44100)
245
write_with_best_quality('output.flac', data, 44100)
246
```
247

248
### File Format Analysis
249

250
```python
251
import soundfile as sf
252
import os
253

254
def analyze_audio_directory(directory):
255
    """Analyze all audio files in a directory."""
256
    
257
    audio_extensions = ['.wav', '.flac', '.ogg', '.aiff', '.au', '.mp3']
258
    
259
    print(f"Analyzing audio files in: {directory}")
260
    print("-" * 50)
261
    
262
    for filename in os.listdir(directory):
263
        if any(filename.lower().endswith(ext) for ext in audio_extensions):
264
            filepath = os.path.join(directory, filename)
265
            try:
266
                info = sf.info(filepath)
267
                duration = info.frames / info.samplerate
268
                file_size = os.path.getsize(filepath) / (1024 * 1024)  # MB
269
                
270
                print(f"File: {filename}")
271
                print(f"  Format: {info.format}/{info.subtype}")
272
                print(f"  Duration: {duration:.2f}s")
273
                print(f"  Sample Rate: {info.samplerate} Hz")
274
                print(f"  Channels: {info.channels}")
275
                print(f"  Size: {file_size:.1f} MB")
276
                print()
277
                
278
            except Exception as e:
279
                print(f"Error reading {filename}: {e}")
280

281
# Example usage (commented out since directory may not exist)
282
# analyze_audio_directory('/path/to/audio/files')
283
```