or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-io.mdfile-info.mdindex.mdsoundfile-class.md
tile.json

tessl/pypi-soundfile

An audio library based on libsndfile, CFFI and NumPy for reading and writing sound files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/soundfile@0.13.x

To install, run

npx @tessl/cli install tessl/pypi-soundfile@0.13.0

index.mddocs/

SoundFile

A comprehensive Python audio library that enables reading and writing of various sound file formats through libsndfile, CFFI, and NumPy integration. SoundFile provides block-wise audio processing, metadata handling, and virtual I/O operations, with audio data represented as NumPy arrays for efficient manipulation.

Package Information

  • Package Name: soundfile
  • Language: Python
  • Installation: pip install soundfile
  • Dependencies: cffi>=1.0, numpy

Core Imports

import soundfile

Common usage patterns:

import soundfile as sf
from soundfile import read, write, SoundFile

Basic Usage

import soundfile as sf
import numpy as np

# Read an audio file
data, samplerate = sf.read('input.wav')
print(f'Audio shape: {data.shape}, Sample rate: {samplerate}')

# Write audio data to a file
sf.write('output.wav', data, samplerate)

# Read only a portion of a file
data, samplerate = sf.read('input.wav', start=1000, stop=2000)

# Block-wise reading for large files
for block in sf.blocks('large_file.wav', blocksize=1024):
    # Process each block
    processed = block * 0.5  # Example: reduce volume

Architecture

SoundFile provides a flexible, NumPy-based API for audio I/O:

  • Functional Interface: Simple read/write functions for quick operations
  • Object Interface: SoundFile class for advanced file handling with context manager support
  • Block Processing: Generator-based block reading for memory-efficient processing of large files
  • Format Support: Extensive format and subtype support through libsndfile
  • Metadata Handling: Read and write audio file metadata (title, artist, etc.)

Capabilities

Core I/O Functions

Primary functions for reading and writing audio files, supporting all major audio formats with NumPy array data representation.

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.
    
    Returns: tuple (audiodata: ndarray, samplerate: int)
    """

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."""

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."""

Core I/O Functions

SoundFile Class

Object-oriented interface for advanced audio file handling with context manager support, seek operations, and metadata access.

class SoundFile:
    def __init__(self, file, mode='r', samplerate=None, channels=None, 
                 subtype=None, endian=None, format=None, closefd=True,
                 compression_level=None, bitrate_mode=None): ...
    
    def read(self, frames=-1, dtype='float64', always_2d=False, 
             fill_value=None, out=None): ...
    def write(self, data): ...
    def seek(self, frames, whence=0): ...
    def tell(self): ...
    
    # Properties
    samplerate: int
    frames: int
    channels: int
    format: str
    subtype: str

SoundFile Class

File Information and Format Support

Utilities for querying file information, available formats, and format validation.

def info(file, verbose=False):
    """Returns an object with information about a sound file."""

def available_formats():
    """Return a dictionary of available major formats."""

def available_subtypes(format=None):
    """Return a dictionary of available subtypes."""

def check_format(format, subtype=None, endian=None):
    """Check if the combination of format/subtype/endian is valid."""

def default_subtype(format):
    """Return the default subtype for a given format."""

File Information

Constants and Types

Version Information

__version__: str  # Module version
__libsndfile_version__: str  # libsndfile version

Seek Constants

SEEK_SET: int  # Seek from beginning
SEEK_CUR: int  # Seek from current position  
SEEK_END: int  # Seek from end

Exception Classes

class SoundFileError(Exception):
    """Base class for soundfile-specific errors."""

class SoundFileRuntimeError(SoundFileError, RuntimeError):
    """Runtime error in soundfile module."""

class LibsndfileError(SoundFileRuntimeError):
    """libsndfile errors with error code and message."""
    code: int
    prefix: str
    error_string: str