audiomp3 – Support for MP3-compressed audio files¶
For more information about working with MP3 files in CircuitPython, see this CircuitPython Essentials Learn guide page.
Available on these boards
- class audiomp3.MP3Decoder(file: str | BinaryIO, buffer: circuitpython_typing.WriteableBuffer)¶
Load a mp3 file for audio playback
Note
MP3Decoderuses a lot of contiguous memory, so care should be given to optimizing memory usage. More information and recommendations can be found here: https://learn.adafruit.com/Memory-saving-tips-for-CircuitPython/reducing-memory-fragmentationLoad a .mp3 file for playback with
audioio.AudioOutoraudiobusio.I2SOut.- Parameters:
file (Union[str, BinaryIO]) – The name of a mp3 file (preferred) or an already opened mp3 file
buffer (WriteableBuffer) – Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file.
Playback of mp3 audio is CPU intensive, and the exact limit depends on many factors such as the particular microcontroller, SD card or flash performance, and other code in use such as displayio. If playback is garbled, skips, or plays as static, first try using a “simpler” mp3:
Use constant bit rate (CBR) not VBR or ABR (variable or average bit rate) when encoding your mp3 file
Use a lower sample rate (e.g., 11.025kHz instead of 48kHz)
Use a lower bit rate (e.g., 32kbit/s instead of 256kbit/s)
Reduce activity taking place at the same time as mp3 playback. For instance, only update small portions of a displayio screen if audio is playing. Disable auto-refresh and explicitly call refresh.
Playing a mp3 file from flash:
import board import audiomp3 import audioio import digitalio # Required for CircuitPlayground Express speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) speaker_enable.switch_to_output(value=True) mp3 = audiomp3.MP3Decoder("cplay-16bit-16khz-64kbps.mp3") a = audioio.AudioOut(board.A0) print("playing") a.play(mp3) while a.playing: pass print("stopped")
- file: BinaryIO¶
File to play back.
- sample_rate: int¶
32 bit value that dictates how quickly samples are loaded into the DAC in Hertz (cycles per second). When the sample is looped, this can change the pitch output without changing the underlying sample.
- __enter__() MP3Decoder¶
No-op used by Context Managers.
- __exit__() None¶
Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.