miniaudio

library1.71pypypi✓ verified 85d ago

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.

communication

pip install miniaudio

github ↗package ↗

INSTALL

IMPORT

SIG · MINIAUDIO

miniaudio

communicationpythonv1.71

Install

1.8s avg

Import

161ms

Disk

19MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.71 · 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

glibc

py 3.10

✓ —

✓ 1.88s

py 3.11

✓ —

✓ 1.9s

py 3.12

✓ —

✓ 1.75s

py 3.13

✓ —

✓ 1.8s

py 3.9

✕ build_error

19MB installed

● package 19MB

Code

Verified usage

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

PlaybackDevice

✓ import miniaudio miniaudio.PlaybackDevice

✗ from miniaudio import 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

✓ import miniaudio.decoders miniaudio.decoders.FileDecoder

✗ from miniaudio.decoders import 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

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

Debug

Known issues

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

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

miniaudio.exceptions.MiniaudioError: failed to initialize playback device: MA_NO_DEVICE

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

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

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'

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

Upgrade

Version history

1.71latest on PyPI · released Apr 29, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/irmen/pyminiaudio ↗

packagehttps://pypi.org/project/miniaudio/ ↗