{"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":"en","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,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}