Miniaudio Python Bindings

1.61 · active · verified Thu Apr 16

miniaudio provides Python bindings for the `miniaudio` C library, offering cross-platform audio playback and decoding capabilities. It includes built-in decoders for common formats like MP3, FLAC, OGG Vorbis, and WAV. The library is actively maintained, with frequent releases (roughly monthly to bi-monthly) often focusing on updates to the underlying C library and Python version compatibility. The current version is 1.61.

Common errors

```
miniaudio.exceptions.MiniaudioError: failed to initialize playback device: MA_NO_DEVICE
```
cause miniaudio could not find or access any audio playback devices on the system, or the default device is unavailable.

fix Check if an audio output device is connected and properly configured in your operating system settings. Ensure audio drivers are installed. On some systems, restarting the audio service or the computer may resolve temporary issues.
```
miniaudio.exceptions.MiniaudioError: failed to open decoder for file: File not found
```
cause The audio file specified for `miniaudio.decoders.FileDecoder` does not exist at the given path.

fix Verify the file path is correct and absolute, or relative to the script's execution directory. Check for typos in the filename or extension. Ensure the process has read permissions for the file.
```
TypeError: 'bytes' object is not an iterator
```
cause You attempted to pass a raw `bytes` object directly to `device.play()` expecting it to be an audio stream, instead of an iterable stream generator.

fix Wrap your raw PCM `bytes` data using `miniaudio.stream_raw_pcm_memory` (or a custom generator function) to create an iterable stream that `device.play()` can consume, e.g., `device.play(miniaudio.stream_raw_pcm_memory(my_bytes_data, ...))`.
```
ImportError: cannot import name 'decoders' from 'miniaudio'
```
cause Attempting to import a submodule directly from the top-level `miniaudio` package using `from miniaudio import decoders`.

fix Import submodules by their full path: `import miniaudio.decoders`. You can then access members like `miniaudio.decoders.FileDecoder`.

Warnings

gotcha The `PlaybackDevice.play()` method is blocking by default. It will pause your program's execution until the entire audio stream or decoder is exhausted.
Fix: For non-blocking playback or real-time applications, run playback in a separate thread, use an asynchronous framework, or implement custom buffer management with callbacks.
gotcha Device initialization can fail if no suitable audio device is found, if the device is in use, or due to insufficient permissions, leading to a `MiniaudioError`.
Fix: Wrap `miniaudio.PlaybackDevice()` instantiation in a `try...except miniaudio.exceptions.MiniaudioError` block. Ensure necessary audio drivers are installed and the device is not exclusively locked by another application.
gotcha When using `stream_raw_pcm_memory` or providing custom raw PCM data, parameters like `sample_rate`, `nchannels`, and `output_format` must exactly match the data's characteristics. Mismatches will result in distorted, static, or silent playback.
Fix: Carefully verify that the `sample_rate`, number of channels, and sample format (e.g., `miniaudio.SampleFormat.SIGNED16`) passed to `stream_raw_pcm_memory` or custom stream callbacks precisely correspond to the raw audio data being provided.
gotcha The `miniaudio.decoders.FileDecoder` supports common formats (MP3, FLAC, OGG, WAV). Attempting to decode unsupported formats or malformed files will result in a `MiniaudioError`.
Fix: Ensure the audio file is a valid and supported format. If decoding fails, catch `miniaudio.exceptions.MiniaudioError` and provide user feedback. Consider using a utility to verify file format integrity if issues persist.

Install

pip install miniaudio Install stable version

Imports

PlaybackDevice
wrong:
```
from miniaudio import PlaybackDevice
```
correct:
```
import miniaudio
miniaudio.PlaybackDevice
```
While 'from miniaudio import PlaybackDevice' works, the recommended pattern in official examples is to import the top-level 'miniaudio' and access its members as attributes.
FileDecoder
wrong:
```
from miniaudio.decoders import FileDecoder
```
correct:
```
import miniaudio.decoders
miniaudio.decoders.FileDecoder
```
Importing 'miniaudio.decoders' as a submodule is the canonical way to access decoders. Direct import from the submodule is also common but the fully qualified path is often seen in examples.

stream_raw_pcm_memory

import miniaudio
miniaudio.stream_raw_pcm_memory

Quickstart

This example demonstrates how to generate a sine wave using NumPy and play it directly using `miniaudio.stream_raw_pcm_memory`. It sets up a `PlaybackDevice`, creates a stream from the raw audio data, plays it, and then waits for the playback duration. This avoids reliance on external audio files.

import miniaudio
import numpy as np
import time

def get_sine_wave(frequency, duration, sample_rate=44100, amplitude=0.5):
    """Generates a raw 16-bit PCM sine wave as bytes."""
    t = np.linspace(0, duration, int(sample_rate * duration), False)
    amplitude_scale = np.iinfo(np.int16).max * amplitude
    data = (amplitude_scale * np.sin(2 * np.pi * frequency * t)).astype(np.int16)
    return data.tobytes()

# Play a 440 Hz sine wave for 3 seconds
with miniaudio.PlaybackDevice() as device:
    print("Playing a 440 Hz sine wave for 3 seconds...")
    sine_data = get_sine_wave(440, 3)
    # Create a stream from raw PCM bytes
    stream = miniaudio.stream_raw_pcm_memory(
        sine_data,
        sample_rate=44100,
        nchannels=1,
        output_format=miniaudio.SampleFormat.SIGNED16
    )
    device.play(stream)
    time.sleep(3) # Wait for playback to finish
    print("Finished playing.")

view raw JSON →