soundfile (PySoundFile)

0.13.1 · active · verified Sun Apr 05

The `soundfile` module (also known as PySoundFile) is a Python library for reading and writing sound files, built upon the C library `libsndfile`, CFFI, and NumPy. It provides a simple, high-level interface to handle various audio formats as NumPy arrays, making it ideal for audio processing and scientific applications. It is actively maintained with regular releases.

Warnings

breaking The primary import name changed from `pysoundfile` to `soundfile` in version 0.7. Using the old import will result in an `ImportError`.
Fix: Update your import statements from `import pysoundfile` to `import soundfile as sf`.
breaking The default value of the `always_2d` parameter in `sf.read()` changed from `True` to `False` in version 0.8.0. This affects the shape of the returned NumPy array for mono files (1D instead of 2D).
Fix: Explicitly set `always_2d=True` in `sf.read()` if you require a 2D array for mono files, or adjust your code to handle 1D arrays for mono.
breaking The argument order for `sf.write()` changed in version 0.8.0 from `write(data, file, ...)` to `write(file, data, ...)`. Calling with the old order will likely cause `TypeError` or incorrect data writing.
Fix: Ensure `file` (path or file-like object) is the first argument and `data` (NumPy array) is the second argument in `sf.write()` calls.
gotcha When reading or writing from in-memory file-like objects (e.g., `io.BytesIO`), it's crucial to `seek(0)` to the beginning of the stream after writing and before attempting to read, otherwise `libsndfile` will report an 'unknown format' error.
Fix: After calling `sf.write(memory_file, ...)` and before `sf.read(memory_file)`, add `memory_file.seek(0)`.
gotcha The load order for the `libsndfile` C library changed in version 0.12.0. Packaged `libsndfile` (included in binary wheels) is now preferred over any system-installed version. This might affect applications relying on a specific system `libsndfile` version.
Fix: If you need to use a system-installed `libsndfile`, install `soundfile` from a source package or source wheel (`pip install soundfile --no-binary :all:`).
gotcha Reading RAW (un-headered) audio files requires explicitly specifying `channels`, `samplerate`, and `subtype` in `sf.read()`, as the format cannot be auto-detected.
Fix: For RAW files, use `data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100, subtype='FLOAT')` and potentially `endian` if needed.

Install

pip install soundfile Install `soundfile` with pre-compiled `libsndfile` for common platforms
pip install soundfile --no-binary :all: sudo apt install libsndfile1 # on Debian/Ubuntu Install `soundfile` from source (requires system `libsndfile`)

Imports

soundfile
```
import soundfile as sf
```
The import name changed from `pysoundfile` to `soundfile` in version 0.7.

Quickstart

This quickstart demonstrates how to generate a simple sine wave using NumPy, write it to a WAV file using `soundfile.write()`, and then read it back using `soundfile.read()`.

import soundfile as sf
import numpy as np
import os

# Create dummy audio data (mono, 44.1 kHz)
samplerate = 44100  # samples per second
duration = 1.0     # seconds
f_hz = 440         # sine wave frequency
t = np.linspace(0., duration, int(samplerate * duration), endpoint=False)
data = 0.5 * np.sin(2 * np.pi * f_hz * t)

output_filename = 'dummy_audio.wav'

# Write the audio data to a WAV file
sf.write(output_filename, data, samplerate)
print(f"Audio written to {output_filename}")

# Read the audio data back from the file
read_data, read_samplerate = sf.read(output_filename)
print(f"Audio read from {output_filename} with sample rate {read_samplerate}")
print(f"Read data shape: {read_data.shape}")

# Verify data
assert np.allclose(data, read_data[:len(data)])
assert samplerate == read_samplerate

# Clean up the dummy file
os.remove(output_filename)
print(f"Cleaned up {output_filename}")

view raw JSON →