audioread

Warnings

• gotcha 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.
  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).
• gotcha 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.
  Fix: Manually convert the `bytes` buffers to suitable numerical formats (e.g., using `numpy.frombuffer` with appropriate `dtype` and `channels` information) for further processing.
• gotcha 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.
  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.
• breaking 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.
  Fix: Upgrade your Python environment to Python 3.9 or a newer version to use `audioread` 3.x.

Install

• pip install audioread Install latest version

Imports

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

Quickstart

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