Skip to content

adafruit_vs1053

Works with

Feather boards paired with the Music Maker FeatherWing. The VS1053b codec chip is on the FeatherWing; the library communicates with it over SPI.

What it does

Controls the VS1053b audio codec chip on Adafruit's Music Maker FeatherWing to play audio files stored on the wing's onboard SD card. The chip handles all decoding in hardware, so CircuitPython only sends file data over SPI — your microcontroller is free to do other work while audio plays. Supported formats include MP3, AAC, OGG Vorbis, WMA, WAV, MIDI files, and FLAC.

Installing the library

Copy the adafruit_vs1053/ folder from the bundle's lib/ folder to your board's lib/ folder.

Quick start

import board
import busio
import digitalio
import adafruit_vs1053

# SPI bus
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)

# Chip-select and data-request pins (adjust for your Feather/FeatherWing combo)
cs = digitalio.DigitalInOut(board.D6)
xdcs = digitalio.DigitalInOut(board.D10)
dreq = digitalio.DigitalInOut(board.D9)

vs = adafruit_vs1053.VS1053(spi, cs, xdcs, dreq)

# Set volume (0 = loudest, 100 = quietest for the underlying register)
vs.set_volume(10, 10)   # left channel, right channel (lower = louder)

# Play a file from the SD card
vs.play_file("song.mp3")

# Wait for playback to finish
while vs.playing:
    pass

# Stop early if needed
# vs.stop()

Key things you can do

What you want How to do it
Play an audio file vs.play_file("filename.mp3") — file must be on the SD card
Check if still playing while vs.playing: pass
Stop playback vs.stop()
Set volume vs.set_volume(left, right) — 0 (loud) to 100 (quiet)
Pause / resume vs.pause() / vs.resume()
Supported formats MP3, AAC, OGG Vorbis, WMA, WAV (PCM), MIDI, FLAC
Store audio files Copy files to the SD card; use 8.3 filenames for compatibility

SD card access

Audio files live on the SD card slot built into the Music Maker FeatherWing. The VS1053 library handles SD file streaming internally; you do not need a separate SD library for playback. However, if you want to list or manage files from CircuitPython, you can mount the SD card separately using sdcardio and storage.

Reading the official docs

https://docs.circuitpython.org/projects/vs1053/en/latest/

The API reference documents VS1053.__init__() pin assignments, set_volume(), play_file(), stop(), pause(), resume(), and the playing property. Check there for the sine_test() method, which is useful for confirming your wiring produces audio output before troubleshooting file playback issues.

Projects using this library

  • Adafruit Music Maker FeatherWing — The primary guide for the hardware; covers wiring, SD card setup, and CircuitPython playback code. Credit: Adafruit Learning System
  • CircuitPython Audio FX — Shows how to trigger audio file playback from sensors and buttons, with VS1053 as one of the supported output options. Credit: Adafruit Learning System