{"id":1337,"library":"audioread","title":"audioread","description":"audioread is a Python library that provides a unified, cross-platform interface for decoding audio files using various underlying system libraries such as GStreamer, FFmpeg, or libmad. It aims to offer a simple way to read raw audio data and its properties from many common audio formats. The current version is 3.1.0, and it maintains a moderate release cadence, primarily for bug fixes and compatibility with newer Python versions or backend libraries.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/beetbox/audioread","tags":["audio","decoding","multimedia","sound"],"install":[{"cmd":"pip install audioread","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"audio_open is the primary function for opening audio files.","symbol":"audio_open","correct":"import audioread\n\naudio_open = audioread.audio_open"},{"note":"Common error to catch when no suitable audio backend is found on the system.","symbol":"NoBackendError","correct":"from audioread import NoBackendError"}],"quickstart":{"code":"import audioread\nimport os\n\n# This quickstart assumes an audio file named 'test.mp3' exists in the current directory.\n# Replace 'test.mp3' with the path to your actual audio file.\n# For a real application, ensure the file exists and is accessible.\naudio_file_path = 'test.mp3'\n\ntry:\n    with audioread.audio_open(audio_file_path) as f:\n        print(f\"Input file: {f.name}\")\n        print(f\"Channels: {f.channels}\")\n        print(f\"Samplerate: {f.samplerate} Hz\")\n        print(f\"Duration: {f.duration:.2f} seconds\")\n\n        print(\"\\nReading frames (raw audio data):\")\n        # Read and discard frames for demonstration.\n        # In a real application, 'buf' would be processed (e.g., written to another format, analyzed).\n        frame_count = 0\n        for buf in f:\n            frame_count += 1\n            if frame_count % 100 == 0:\n                print(f\"  ...processed {frame_count} frames, last buffer size: {len(buf)} bytes\")\n        print(f\"Finished processing. Total frames read: {frame_count}\")\n\nexcept audioread.NoBackendError:\n    print(\"\\nERROR: No audio backend found.\")\n    print(\"audioread requires external libraries like GStreamer, FFmpeg, or libmad.\")\n    print(\"Please install one of these system-wide (e.g., 'brew install ffmpeg' or 'apt-get install gstreamer1.0-plugins-base').\")\nexcept FileNotFoundError:\n    print(f\"\\nERROR: Audio file '{audio_file_path}' not found.\")\n    print(\"Please ensure the file exists or update the 'audio_file_path' variable.\")\nexcept Exception as e:\n    print(f\"\\nAn unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to open an audio file using `audioread.audio_open`, access its properties (channels, samplerate, duration), and iterate through its raw audio data buffers. It also includes error handling for the common `NoBackendError` (when no system audio decoding library is found) and `FileNotFoundError`."},"warnings":[{"fix":"Install a compatible audio decoding library on your system (e.g., `sudo apt-get install gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad ffmpeg` on Debian/Ubuntu, or `brew install ffmpeg` on macOS).","message":"audioread itself only provides a Python interface; it does not bundle audio decoding libraries. You *must* install external system libraries like GStreamer, FFmpeg, or libmad for it to function. Without them, `audioread.NoBackendError` will be raised.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually convert the `bytes` buffers to suitable numerical formats (e.g., using `numpy.frombuffer` with appropriate `dtype` and `channels` information) for further processing.","message":"The `f` object (from `audioread.audio_open`) yields raw `bytes` objects representing audio frames. These are not automatically decoded into numerical arrays (e.g., NumPy) by audioread. Users must handle the byte-to-array conversion themselves if higher-level processing is needed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of potential inaccuracies when relying on `duration` for precise timing. For critical applications, consider processing the entire file to determine true length or using backends known for better accuracy if available.","message":"The `duration` attribute is often an estimate, especially for VBR (Variable Bit Rate) compressed formats, and may not be perfectly accurate. Seeking operations (if the backend supports them) might also not be sample-accurate or might be slow for certain formats/backends.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to Python 3.9 or a newer version to use `audioread` 3.x.","message":"As of version 3.0.0, audioread officially supports Python 3.9 and newer. Older Python 2.x or earlier Python 3.x versions are no longer supported, and attempting to use modern `audioread` versions on an incompatible Python environment will lead to installation failures or runtime errors.","severity":"breaking","affected_versions":"3.0.0+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}