Core I/O Functions

def read(file, frames=-1, start=0, stop=None, dtype='float64', always_2d=False,
         fill_value=None, out=None, samplerate=None, channels=None,
         format=None, subtype=None, endian=None, closefd=True):
    """
    Read audio data from a sound file.
    
    Parameters:
    - file: str or file-like, path to input file or file-like object
    - frames: int, number of frames to read (-1 for all)
    - start: int, starting frame offset
    - stop: int, stop reading at this frame
    - dtype: str or numpy.dtype, data type of output array
    - always_2d: bool, return 2D array even for mono files
    - fill_value: float, value to use for missing frames
    - out: ndarray, pre-allocated output array
    - samplerate: int, expected sample rate (for validation)
    - channels: int, expected channel count (for validation)  
    - format: str, expected format (for validation)
    - subtype: str, expected subtype (for validation)
    - endian: str, expected endianness (for validation)
    - closefd: bool, close file descriptor when done
    
    Returns:
    - tuple: (audiodata: ndarray, samplerate: int)
      - audiodata: 1D or 2D NumPy array with shape (frames,) or (frames, channels)
      - samplerate: sample rate in Hz
    """

def write(file, data, samplerate, subtype=None, endian=None, format=None,
          closefd=True, compression_level=None, bitrate_mode=None):
    """
    Write audio data to a sound file.
    
    Parameters:
    - file: str or file-like, output file path or file-like object
    - data: ndarray, audio data to write
    - samplerate: int, sample rate in Hz
    - subtype: str, audio subtype (e.g., 'PCM_16', 'FLOAT')
    - endian: str, byte order ('FILE', 'LITTLE', 'BIG', 'CPU')
    - format: str, file format (e.g., 'WAV', 'FLAC', 'OGG')
    - closefd: bool, close file descriptor when done
    - compression_level: float, compression level for applicable formats (0.0-1.0)
    - bitrate_mode: str, bitrate mode ('CONSTANT', 'AVERAGE', 'VARIABLE')
    
    Returns:
    - None
    """

def blocks(file, blocksize=None, overlap=0, frames=-1, start=0, stop=None,
           dtype='float64', always_2d=False, fill_value=None, out=None,
           samplerate=None, channels=None, format=None, subtype=None,
           endian=None, closefd=True):
    """
    Return a generator for block-wise reading of audio data.
    
    Parameters:
    - file: str or file-like, input file path or file-like object
    - blocksize: int, frames per block (default: 65536)
    - overlap: int, overlapping frames between blocks
    - frames: int, total frames to read (-1 for all)
    - start: int, starting frame offset
    - stop: int, stop reading at this frame
    - dtype: str or numpy.dtype, data type of output arrays
    - always_2d: bool, return 2D arrays even for mono files
    - fill_value: float, value to use for missing frames
    - out: ndarray, pre-allocated output array template
    - samplerate: int, expected sample rate (for validation)
    - channels: int, expected channel count (for validation)
    - format: str, expected format (for validation)
    - subtype: str, expected subtype (for validation)
    - endian: str, expected endianness (for validation)
    - closefd: bool, close file descriptor when done
    
    Yields:
    - ndarray: audio data blocks with shape (blocksize,) or (blocksize, channels)
    """

import soundfile as sf
import numpy as np

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

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

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

import soundfile as sf
import numpy as np

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

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

process_large_file('large_input.wav', 'processed_output.wav', apply_gain)

import soundfile as sf

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

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