Registry / data / audioread

audioread

JSON →
library3.1.0pypypi✓ verified 25d ago

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.

pip install audioread
INSTALL
IMPORT
SIG · AUDIOREAD
A
audioread
datapythonv3.1.0
Install
1.6s avg
Import
18ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.1.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
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.020s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.016s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

audio_open
import audioread audio_open = audioread.audio_open
audio_open is the primary function for opening audio files.
NoBackendError
from audioread import NoBackendError
Common error to catch when no suitable audio backend is found on the system.

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

import audioread import os # This quickstart assumes an audio file named 'test.mp3' exists in the current directory. # Replace 'test.mp3' with the path to your actual audio file. # For a real application, ensure the file exists and is accessible. audio_file_path = 'test.mp3' try: with audioread.audio_open(audio_file_path) as f: print(f"Input file: {f.name}") print(f"Channels: {f.channels}") print(f"Samplerate: {f.samplerate} Hz") print(f"Duration: {f.duration:.2f} seconds") print("\nReading frames (raw audio data):") # Read and discard frames for demonstration. # In a real application, 'buf' would be processed (e.g., written to another format, analyzed). frame_count = 0 for buf in f: frame_count += 1 if frame_count % 100 == 0: print(f" ...processed {frame_count} frames, last buffer size: {len(buf)} bytes") print(f"Finished processing. Total frames read: {frame_count}") except audioread.NoBackendError: print("\nERROR: No audio backend found.") print("audioread requires external libraries like GStreamer, FFmpeg, or libmad.") print("Please install one of these system-wide (e.g., 'brew install ffmpeg' or 'apt-get install gstreamer1.0-plugins-base').") except FileNotFoundError: print(f"\nERROR: Audio file '{audio_file_path}' not found.") print("Please ensure the file exists or update the 'audio_file_path' variable.") except Exception as e: print(f"\nAn unexpected error occurred: {e}")
Debug
Known issues
gotchaaudioread 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.
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).
affects: All versions
gotchaThe `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.
fix
Manually convert the `bytes` buffers to suitable numerical formats (e.g., using `numpy.frombuffer` with appropriate `dtype` and `channels` information) for further processing.
affects: All versions
gotchaThe `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.
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.
affects: All versions
breakingAs 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.
fix
Upgrade your Python environment to Python 3.9 or a newer version to use `audioread` 3.x.
affects: 3.0.0+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'audioread'
The 'audioread' module is not installed in the Python environment.
fix
Install the module using pip: 'pip install audioread'.
audioread.NoBackendError
No suitable backend is available for audioread to decode audio files.
fix
Ensure that FFmpeg or GStreamer is installed and accessible in your system's PATH.
ImportError: cannot import name 'audio_open' from 'audioread'
The function 'audio_open' is not available in the 'audioread' module.
fix
Use 'from audioread import audio_open' to import the function correctly.
audioread.exceptions.NoBackendError
The audioread library could not find any of its required backend decoding tools (such as FFmpeg, GStreamer, or Libav) installed or accessible on your system.
fix
Install a suitable audio decoding backend for your operating system and ensure its executable is in your system's PATH. For example, on Ubuntu/Debian: `sudo apt-get install ffmpeg` or `sudo apt-get install libav-tools`. On Windows, download FFmpeg, extract it, and add the path to its `bin` directory to your system's PATH environment variable. Restart your terminal or IDE after installation.
audioread.exceptions.DecodeError
The audioread library, even with an available backend, failed to decode the specific audio file, possibly due to corruption or an unsupported format by the chosen backend.
fix
Ensure the audio file is not corrupted and is in a format supported by your installed backend (e.g., MP3, WAV, FLAC). Try playing the file with a standard media player to confirm its integrity. If a backend like FFmpeg is installed, ensure it's up-to-date and correctly configured to handle the file's format.
Upgrade
Version history
3.1.0latest on PyPI · released Oct 26, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
audioread — pip install audioread · libregistry