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 and used for buffering the data. The buffer is split into two parts for decoded data and the remainder is used for pre-decoded data. When playing from a socket, a larger buffer can help reduce playback glitches at the expense of increased memory usage.
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, network 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")
It is possible to seek within a file before playing it:
with open("/test.mp3", "rb") as stream: stream.seek(128000 * 30 // 8) # Seek about 30s into a 128kbit/s stream decoder.file = stream
If the stream is played with
loop = True, the loop will start at the beginning.It is possible to stream an mp3 from a socket, including a secure socket. The MP3Decoder may change the timeout and non-blocking status of the socket. Using a larger decode buffer with a stream can be helpful to avoid data underruns. An
adafruit_requestsrequest must be made withheaders={"Connection": "close"}so that the socket closes when the stream ends.- __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.
- file: BinaryIO
File to play back.
- open(filepath: str) None
Takes in the name of a mp3 file, opens it, and replaces the old playback file.