soundfile

library0.14.0pypypi✓ verified 25d ago

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.

data ai-ml

pip install soundfile

github ↗package ↗

INSTALL

IMPORT

SIG · SOUNDFILE

soundfile

datapythonv0.14.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.14.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

1/2 runs

py 3.11

1/2 runs

py 3.12

1/2 runs

py 3.13

1/2 runs

py 3.9

1/2 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

soundfile

✓ import soundfile as sf

✗ import pysoundfile

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

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}")

Debug

Known issues

breakingThe 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`.

affects: <0.7

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

affects: 0.8.0+

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

affects: 0.8.0+

gotchaWhen 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)`.

affects: All versions (behavior of `libsndfile`)

gotchaThe 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:`).

affects: 0.12.0+

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

affects: All versions

Errors

Common errors & fixes

soundfile.LibsndfileError: libsndfile not found

The underlying C library `libsndfile`, which `soundfile` depends on, is not installed or not discoverable on your system's PATH.

fix

Install `libsndfile` using your system's package manager (e.g., `sudo apt-get install libsndfile1` on Debian/Ubuntu, `brew install libsndfile` on macOS, or download binaries for Windows).

ModuleNotFoundError: No module named 'soundfile'

The `soundfile` Python package has not been installed in your current Python environment.

fix

Install the package using pip: `pip install soundfile`

FileNotFoundError: [Errno 2] No such file or directory: 'your_audio_file.wav'

The audio file specified in `sf.read()` or `sf.SoundFile()` does not exist at the provided path.

fix

Ensure the file path is correct and the file exists, or provide an absolute path to the audio file.

ValueError: Data and channels do not match.

The shape of the audio data array (e.g., `(frames, channels)`) does not correspond to the `channels` argument provided when writing the sound file.

fix

Ensure the `channels` argument matches the second dimension of your data array, or reshape the array appropriately (e.g., `data.reshape(-1, 1)` for mono, `data.reshape(-1, 2)` for stereo).

ImportError: libsndfile.so.1: cannot open shared object file: No such file or directory

The `soundfile` Python package requires the underlying C library `libsndfile` to be installed on your system, which is missing or not discoverable in your system's library paths.

fix

Install `libsndfile` using your system's package manager (e.g., `sudo apt-get install libsndfile1` on Debian/Ubuntu, `brew install libsndfile` on macOS, or download binaries for Windows from `libsndfile.github.io`).

Upgrade

Version history

0.14.0latest on PyPI · released Jun 6, 2026

Audit

Dependencies

numpyrequiredAudio data is represented as NumPy arrays.

cffirequiredUsed for the foreign function interface to `libsndfile`.

libsndfilerequiredThe underlying C library for reading and writing sound files. Often bundled in wheels, but may require system installation.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bastibe/python-soundfile ↗

packagehttps://pypi.org/project/soundfile/ ↗