ESP32 + VS1053 based network and SD audio player with a responsive web interface.
A very capable audio player with:
- MP3, M4A, AAC, OGG, and 16-bit FLAC playback
- Playlist queue for 100 items
- WebSocket based live UI
- A very fast caching SD card filebrowser
- Radio presets
- Automatic adding of premium/private channels during build
- Internet radio search with radio-browser.info
- Favorites system
- Mobile friendly interface
osap-UI-demo.mp4
Minimal component count, development is done on the following hardware:
- 7x9 cm prototype board
- WEMOS S3 MINI
- WEMOS Micro SD card shield
- Adafruit VS1053 Codec + MicroSD Breakout
- Optional Adafruit 1.3" I²C OLED status indicator
- To connect the OLED a STEMMA QT header cable
- Web browser as main UI
The hardware listed above is the development/reference setup used for OSAP.
Other ESP32-S3 boards, SD card interfaces and VS1053-based audio hardware may also be suitable.
The software is not inherently tied to the specific boards listed here.
The reference player is build on the above 7x9 cm prototype board that fits the cases in the stl folder.
An optional Adafruit 1.3" I²C OLED display can be added for device status information.
It displays boot progress, connection status and the current IP address.
Note: To keep the player unobtrusive and power efficient, the OLED automatically sleeps after startup.
Wake-up is performed using a capacitive touch input, which can be as simple as a GPIO connected to a metal button, screw head or other exposed conductive surface.
The current implementation assumes dedicated SPI buses for SD card and VS1053 access.
Shared SPI configurations may compile, partially function, fully function or fail in creative and confusing ways.
Dedicated SPI wiring is the recommended and supported configuration.
- No accounts
- No telemetry
- No phone app install
- No ads
- No “smart platform”
- Just a websocket UI on your LAN
- VS1053 hardware decoder with MP3, M4A, AAC, OGG and FLAC decoding
- Local SD playback
- Internet radio streaming
- Playlist queue system
- Favorites saving/loading
- Playback state synchronization between UI clients
- Clean UI optimized for mobile use
- Responsive split-pane layout
- Works on all modern browsers
- Touch friendly controls
- Search interface for radio stations
- Overlay "now playing" mode
- Toast notifications and errors
- Very fast caching file browser
The player can be configured with multiple WiFi networks and automatically connects to the strongest available known network.
This allows the same device to be used with different network setups such as a home network and a mobile phone hotspot without requiring reconfiguration.
Multiple simultaneous clients are supported and kept in sync with the player state.
SD requests are quite expensive and are handled async and cached to keep the UI responsive.
- File browser requests are cached if the response takes more than 100 ms to build.
- The favorites folder is cached on every mutation.
The following steps assume you already have a working VSCode/PlatformIO setup.
-
Click here to go to the latest release page.
On the release page, click onSource code (zip)then download and unzip this file. -
Open VSCode and select from the top menu
File->Open folderthen select the folder where you unzipped the repository to.
This is the project folder. -
Provide your wifi secrets by creating the file
src/secrets.hppin the project folder.
See the Building section below on how to format this file. -
Open PlatformIO and select
Project tasks->develop->Upload and monitor.
PlatformIO will download and install all the assets that are needed to build the player firmware.
This might take a while depending on your internet speed and computer capabilities.
If all assets are installed, PlatformIO will start compiling and flash your player.
Note: The first time you build this project, a lot of files will be downloaded and then compiled which might take a long time.
Before compiling create a new file with your WiFi and location secrets:
src/secrets.hpp
Use this example setup as a template:
#pragma once
struct Secret
{
const char *SSID;
const char *PSK;
};
/* OSAP will connect to the strongest available network */
constexpr Secret networks[] =
{
{"network1", "password"},
{"network2", "password"},
};
/* Central European Time - see:
https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv */
const char *TIMEZONE = "CET-1CEST,M3.5.0,M10.5.0/3";
/* Replace "nl" with your own country code:
https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes */
const char *NTP_POOL = "nl.pool.ntp.org";
/* Optional custom mDNS hostname */
//#define OSAP_HOSTNAME "music-player"Preset radio stations are defined in src/presets.hpp.
Adding private or premium radio presets is very easy.
Place one or more .pls playlist files in the project root before compiling.
During build:
.plsfiles are automatically parsed- presets are generated and merged into the main preset list
The added .pls files are ignored by git.
The web UI consists of two panes.
A selectable source tab on the left and a playlist tab on the right.
There are 4 source tabs, library, presets, favorites and search.
Click on a tab button to show a tab.
You will need a FAT32 formatted micro SD card.
Folders are navigated by clicking.
Single files can be added by clicking on the file or added and started with the play button.
Folders can be scanned and all found items added by clicking the play button.
This will add all files in a folder and start playing the first added item if nothing is playing.
Internet radio stations found through the search interface can be saved as favorites.
Favorites are stored on the SD card in the /.favorites folder.
Saved favorites can be inspected by visiting http://player-ip/favorites in a browser.
The generated files are formatted so they can easily be copied into src/presets.hpp if you want to make them permanent presets.
You can search for radio stations on radio-browser.info with the search bar.
Search results are displayed in the search tab.
The Info button at the bottom of the page toggles the Now Playing overlay.
The overlay shows the currently playing station or track and playback progress.
After 30 seconds no activity the overlay is show automatically.
When an Internet radio station originating from the search results is playing, a Save as Favorite button becomes available, allowing the station to be stored on the SD.
These libraries are used internally by the player:
- HTTP traffic and WebSocket UI messaging are handled by PsychicHttp webserver library - MIT
- Audio playback is handled by ESP32_VS1053_Stream library - MIT
- Low level codec access is handled by ESP_VS1053_Library - GPL-3.0
- The OLED is handled by Adafruit SSD1306 library - BSD
All frontend resources are compiled into the player UI:
- Vanilla HTML/CSS/JavaScript is used for the interface and application logic
- SVG icons from Google Fonts are inlined into the generated HTML during build - Apache 2.0
- Reconnecting WebSocket is included (minified) in the UI - MIT
Most of the required parts.
To stack the SD board on top of the CPU board, 3 pieces of 8 pin single row headers are required.
Also an additional countersunk M6 20-25mm long bolt with a fitting nut and a cable lug are required to build the example cases.
Possible parts layout, this layout will fit the cases in the stl folder and both cables and SD card are accesible.
In this layout, the SD board is stacked on top of the CPU board and the default pins are used to save on wiring and assembly time.
After wiring up and smoke testing.
Connecting the case.
Testing touch and OLED.
The assembled player.