{"id":8316,"library":"miniaudio","title":"Miniaudio Python Bindings","description":"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.","status":"active","version":"1.61","language":"en","source_language":"en","source_url":"https://github.com/irmen/pyminiaudio","tags":["audio","playback","decoders","sound","multimedia","mp3","flac","ogg","wav"],"install":[{"cmd":"pip install miniaudio","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from miniaudio import PlaybackDevice","symbol":"PlaybackDevice","correct":"import miniaudio\nminiaudio.PlaybackDevice"},{"note":"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.","wrong":"from miniaudio.decoders import FileDecoder","symbol":"FileDecoder","correct":"import miniaudio.decoders\nminiaudio.decoders.FileDecoder"},{"symbol":"stream_raw_pcm_memory","correct":"import miniaudio\nminiaudio.stream_raw_pcm_memory"}],"quickstart":{"code":"import miniaudio\nimport numpy as np\nimport time\n\ndef get_sine_wave(frequency, duration, sample_rate=44100, amplitude=0.5):\n    \"\"\"Generates a raw 16-bit PCM sine wave as bytes.\"\"\"\n    t = np.linspace(0, duration, int(sample_rate * duration), False)\n    amplitude_scale = np.iinfo(np.int16).max * amplitude\n    data = (amplitude_scale * np.sin(2 * np.pi * frequency * t)).astype(np.int16)\n    return data.tobytes()\n\n# Play a 440 Hz sine wave for 3 seconds\nwith miniaudio.PlaybackDevice() as device:\n    print(\"Playing a 440 Hz sine wave for 3 seconds...\")\n    sine_data = get_sine_wave(440, 3)\n    # Create a stream from raw PCM bytes\n    stream = miniaudio.stream_raw_pcm_memory(\n        sine_data,\n        sample_rate=44100,\n        nchannels=1,\n        output_format=miniaudio.SampleFormat.SIGNED16\n    )\n    device.play(stream)\n    time.sleep(3) # Wait for playback to finish\n    print(\"Finished playing.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"The `PlaybackDevice.play()` method is blocking by default. It will pause your program's execution until the entire audio stream or decoder is exhausted.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `miniaudio.decoders.FileDecoder` supports common formats (MP3, FLAC, OGG, WAV). Attempting to decode unsupported formats or malformed files will result in a `MiniaudioError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"miniaudio could not find or access any audio playback devices on the system, or the default device is unavailable.","error":"miniaudio.exceptions.MiniaudioError: failed to initialize playback device: MA_NO_DEVICE"},{"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.","cause":"The audio file specified for `miniaudio.decoders.FileDecoder` does not exist at the given path.","error":"miniaudio.exceptions.MiniaudioError: failed to open decoder for file: File not found"},{"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, ...))`.","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.","error":"TypeError: 'bytes' object is not an iterator"},{"fix":"Import submodules by their full path: `import miniaudio.decoders`. You can then access members like `miniaudio.decoders.FileDecoder`.","cause":"Attempting to import a submodule directly from the top-level `miniaudio` package using `from miniaudio import decoders`.","error":"ImportError: cannot import name 'decoders' from 'miniaudio'"}]}