Features

• Plays MP3, FLAC and WAV, with tags read from ID3, Vorbis comments and RIFF INFO
• Folder browser and now-playing screen on the Pirate Audio’s 240×240 ST7789 LCD, with album cover art from embedded images or cover.jpg/folder.jpg
• Four-button control: tap, hold and repeat gestures for navigation, volume, play/pause and track skipping, plus an A+B combo to power off
• Resume playback: remembers your playlist, track, position and volume across reboots, and resumes paused
• Battery monitoring for the Waveshare UPS HAT (C) and PiSugar 2/3, with an on-screen battery gauge and automatic clean shutdown on low battery
• Power saving: the screen turns off after 30 seconds idle
• Desktop simulator: test the player on Linux, macOS or Windows in a pygame window that emulates the screen, buttons, battery and audio

Easy setup

A single install script configures Raspberry Pi OS (Bookworm or later, including Lite). It installs mpv and the Python dependencies, enables SPI, I2C and the HiFiBerry DAC overlay, and sets pirateplayer up as a systemd service that starts at boot. To add music, copy files to ~/Music over the network with scp or rsync. Settings such as the music folder, screen timeout, battery type and audio device can be changed in a simple TOML config file.

Who it’s for

pirateplayer suits anyone building a DIY MP3 player, Raspberry Pi music player or offline portable audio player: maker projects, kids’ music players, or a distraction-free alternative to a phone.

Keywords: Raspberry Pi Zero music player, Pirate Audio MP3 player, DIY portable audio player, Raspberry Pi FLAC player, mpv Python music player, PiSugar, Waveshare UPS HAT.