{"id":1203,"library":"soundfile","title":"soundfile (PySoundFile)","description":"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.","status":"active","version":"0.13.1","language":"python","source_language":"en","source_url":"https://github.com/bastibe/python-soundfile","tags":["audio","sound","signal processing","libsndfile","numpy","cffi","wav","flac","ogg","mp3"],"install":[{"cmd":"pip install soundfile","lang":"bash","label":"Install `soundfile` with pre-compiled `libsndfile` for common platforms"},{"cmd":"pip install soundfile --no-binary :all:\nsudo apt install libsndfile1 # on Debian/Ubuntu","lang":"bash","label":"Install `soundfile` from source (requires system `libsndfile`)"}],"dependencies":[{"reason":"Audio data is represented as NumPy arrays.","package":"numpy","optional":false},{"reason":"Used for the foreign function interface to `libsndfile`.","package":"cffi","optional":false},{"reason":"The underlying C library for reading and writing sound files. Often bundled in wheels, but may require system installation.","package":"libsndfile","optional":false}],"imports":[{"note":"The import name changed from `pysoundfile` to `soundfile` in version 0.7.","wrong":"import pysoundfile","symbol":"soundfile","correct":"import soundfile as sf"}],"quickstart":{"code":"import soundfile as sf\nimport numpy as np\nimport os\n\n# Create dummy audio data (mono, 44.1 kHz)\nsamplerate = 44100  # samples per second\nduration = 1.0     # seconds\nf_hz = 440         # sine wave frequency\nt = np.linspace(0., duration, int(samplerate * duration), endpoint=False)\ndata = 0.5 * np.sin(2 * np.pi * f_hz * t)\n\noutput_filename = 'dummy_audio.wav'\n\n# Write the audio data to a WAV file\nsf.write(output_filename, data, samplerate)\nprint(f\"Audio written to {output_filename}\")\n\n# Read the audio data back from the file\nread_data, read_samplerate = sf.read(output_filename)\nprint(f\"Audio read from {output_filename} with sample rate {read_samplerate}\")\nprint(f\"Read data shape: {read_data.shape}\")\n\n# Verify data\nassert np.allclose(data, read_data[:len(data)])\nassert samplerate == read_samplerate\n\n# Clean up the dummy file\nos.remove(output_filename)\nprint(f\"Cleaned up {output_filename}\")","lang":"python","description":"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()`."},"warnings":[{"fix":"Update your import statements from `import pysoundfile` to `import soundfile as sf`.","message":"The primary import name changed from `pysoundfile` to `soundfile` in version 0.7. Using the old import will result in an `ImportError`.","severity":"breaking","affected_versions":"<0.7"},{"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.","message":"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).","severity":"breaking","affected_versions":"0.8.0+"},{"fix":"Ensure `file` (path or file-like object) is the first argument and `data` (NumPy array) is the second argument in `sf.write()` calls.","message":"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.","severity":"breaking","affected_versions":"0.8.0+"},{"fix":"After calling `sf.write(memory_file, ...)` and before `sf.read(memory_file)`, add `memory_file.seek(0)`.","message":"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.","severity":"gotcha","affected_versions":"All versions (behavior of `libsndfile`)"},{"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:`).","message":"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.","severity":"gotcha","affected_versions":"0.12.0+"},{"fix":"For RAW files, use `data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100, subtype='FLOAT')` and potentially `endian` if needed.","message":"Reading RAW (un-headered) audio files requires explicitly specifying `channels`, `samplerate`, and `subtype` in `sf.read()`, as the format cannot be auto-detected.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':56 'also':6 'applic':53 'array':44 'audio':40,49,61 'built':20 'c':23 'cffi':26,67 'file':19 'flac':69 'format':41 'handl':38 'high':34 'high-level':33 'ideal':47 'interfac':36 'known':7 'level':35 'librari':13,24 'libsndfil':25,65 'maintain':57 'make':45 'modul':5 'mp3':71 'numpi':28,43,66 'ogg':70 'process':50,64 'provid':30 'pysoundfil':2,9 'python':12 'read':15 'regular':59 'releas':60 'scientif':52 'signal':63 'simpl':32 'sound':18,62 'soundfil':1,4 'upon':21 'various':39 'wav':68 'write':17","created_at":"2026-04-05T14:32:32.930489+00:00","updated_at":"2026-04-17T14:56:23.574383+00:00","problems":[{"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).","cause":"The underlying C library `libsndfile`, which `soundfile` depends on, is not installed or not discoverable on your system's PATH.","error":"soundfile.LibsndfileError: libsndfile not found"},{"fix":"Install the package using pip: `pip install soundfile`","cause":"The `soundfile` Python package has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'soundfile'"},{"fix":"Ensure the file path is correct and the file exists, or provide an absolute path to the audio file.","cause":"The audio file specified in `sf.read()` or `sf.SoundFile()` does not exist at the provided path.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_audio_file.wav'"},{"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).","cause":"The shape of the audio data array (e.g., `(frames, channels)`) does not correspond to the `channels` argument provided when writing the sound file.","error":"ValueError: Data and channels do not match."},{"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`).","cause":"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.","error":"ImportError: libsndfile.so.1: cannot open shared object file: No such file or directory"}],"ecosystem":"pypi","meta_description":null,"install_score":37,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.14.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/bastibe/python-soundfile","docs":null,"changelog":null,"pypi":"https://pypi.org/project/soundfile/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"stale"}}