ESP32-MiniWebRadio: a touchscreen internet radio built on ESP32-S3 and P4
Internetradio with ESP32-S3/P4, I2S DAC and SPI/RGB/DSI TFT Display with Touchpad
At a glance
- What is it?
- ESP32-MiniWebRadio is C++ firmware that turns an ESP32-S3 or P4 board with a TFT touch display, an I2S DAC and a FAT32 SD card into a desk internet radio. It streams stations, serves the card over FTP and can be driven from a browser, but its SD card wiring is fixed and its codec list carries real ceilings.
- Who is it for?
- ESP32-MiniWebRadio fits makers who own an ESP32-S3 or P4 board, an I2S DAC and a SPI, RGB or DSI touch panel and want a radio with a browser interface rather than a bare firmware image. It does not fit anyone expecting a phone app, a screenless WiFi speaker, or a panel whose SD adapter is permanently fitted with series resistors.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 20, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A desk radio built from a board and a cheap panel
ESP32-MiniWebRadio is firmware for a single board that turns an ESP32-S3 or ESP32-P4 module into a network audio appliance with a colour touchscreen. The hardware list asks for a TFT panel with touchpad, an I2S DAC such as a PCM5102A, and an SD card in FAT32. From those parts the project produces a desk radio: it streams internet radio, keeps up to 999 preset stations in a CSV file on the card, plays local files and DLNA shares, keeps a clock, arms a single alarm and dims itself on a sleep timer. The intended user is a maker with a spare ESP32 board and a low-cost SPI display who wants a finished object rather than a generic WiFi music player. No switches, rotary encoders, capacitors or resistors are needed because everything is driven from the screen or a browser.
Two front ends for one firmware: touch panel and browser
Three user interfaces are listed: TFT touchscreen display, web browser and FTP. The browser UI runs on the device itself. On first boot the board raises its own access point, the phone joins it, and the home router SSID and password are entered in the browser, so networks.csv on the SD card is only a manual fallback. The same web UI then handles the local timezone, volume and EQ settings, the IR button codes, and adding stations found through the Community Radio Browser before writing the list and icon file back to the card. The touch panel carries the clock, the alarm days, the sleep timer and the brightness. Audio decoding runs in its own decoupled task, so redrawing the screen or loading a web page does not interrupt the stream. A phone app playing the same URLs is the obvious alternative, but it keeps neither the panel nor the exposed SD card.
The SD card is wired as SD_MMC, and that fixes the pins
The most consequential wiring decision is that the SD card is connected as SD_MMC rather than through software SPI. The stated benefit is stability and speed, and the stated cost is that the GPIOs cannot be chosen freely. The adapter must not have resistors in series, and the project suggests 40MHz for the card, set through SDMMC_FREQUENCY 40000000 in common.h. On an ESP32 board the existing pull-up resistor at pin D0 has to be removed. The consequence for a builder is that the display adapter, the SD slot on the back of some TFT panels and the module header have to agree on pins before anything works, which is where most first assemblies fail.
Software decoding and the ceiling on flac and vorbis
Audio is decoded in software on the module, which is why 4MB of PSRAM matters more than raw flash speed. The supported formats are listed in the project documentation:
|Codec | |
|------------|-------------------------------------------------------|
| mp3 | y |
| aac | y |
| aacp | y (+SBR, +PS) |
| wav | y |
| flac | y (blocksize max 16KB) |
| vorbis | y <=256Kbit/s |
| m4a | y |
| opus | y (except hybrid mode) |Two rows carry explicit limits. FLAC is capped at a 16KB block size and vorbis at 256Kbit/s, so a high bitrate vorbis stream or a large-block FLAC file pulled from a DLNA server will not play as expected. Opus is handled except in hybrid mode. A board needs at least 8MB of flash and 4MB of PSRAM, and 16MB of flash for OTA updates.
Bringing it up: PlatformIO, a FAT32 card and a phone browser
The repository is a PlatformIO project, with platformio.ini, CMakeLists.txt, src/, lib/ and boards/ at the top level, and the documentation states that PlatformIO is definitely recommended as the IDE. Assembly and flashing instructions live in a separate guide, docs/How to install.pdf, rather than in the README, and a Content_on_SD_Card.zip payload is shipped for copying onto the card. The card must be FAT32 and holds stations.csv, networks.csv and any media you want listed. After the first boot sets the router credentials through the access point browser, the file system is reachable over FTP with the username and password esp32, which the project allows changing in common.h. The USB connection and the display bring-up order are the parts the README leaves to the PDF.
stations.csv, the Community Radio Browser and a 999 station ceiling
Station lists live in stations.csv on the SD card, holding up to 999 preset entries and editable from the web UI. Each station can carry its own icon file when saved to the card. The integrated Community Radio Browser works as a search engine, so a station found there can be added from the browser, with its icon when one is available, and the list written back to the SD card. Channels can also be exported and imported in Excel format for backup, and local playlists in m3u format are processed. Station URLs accept inline credentials for servers that expect access data, written as URL|user|pwd. The 999 entry ceiling is a hard one, so a large radio directory has to be trimmed before it reaches the card.
Known problems: series resistors, pin D0 and a six hour sleep timer
Two hardware caveats sit under the project's own known problems heading. Display-bundled SD adapters frequently ship with series resistors, which the project calls useless and in many cases harmful, and it advises replacing them with solder bridges. On an ESP32, the pull-up at pin D0 must be removed. Scope limits are just as real. One alarm time can be preset with weekday selection, the sleep timer switches off sound and screen after a preset time with a maximum of six hours, and the remote control path expects a 38kHz NEC encoded remote whose button codes the user can remap from the web UI. A BH1750 light sensor can dim the panel at night and a KCX_BT_EMITTER V1.7 can add Bluetooth audio, both of which need free GPIOs that the fixed SD_MMC wiring can take away.
A GPL-3.0 firmware project with recent releases and little to merge
The repository is not archived and the last push was on 2026-10-20, with tagged releases V4.1.0 on 2026-02-02, V4.2.0 on 2026-05-09 and an earlier V4.0-rc2 from 2025-04-11. The source is C++ and released under GPL-3.0, so a derived firmware that you distribute to others carries the same licence terms. The repository also holds the wiring schematics, the display layout PDF, the Community Radio Browser guide and the FileZilla settings sheet, which is the practical base for adapting the project to a different panel. For an adopter the work is mostly hardware adaptation rather than feature work: new displays mean new pin assignments and a fresh check of the SD_MMC fixed pins, and the release notes in recent versions read as reliability fixes such as improved web UI reliability and click suppression when changing stations.
Editorial conclusion
ESP32-MiniWebRadio fits makers who own an ESP32-S3 or P4 board, an I2S DAC and a SPI, RGB or DSI touch panel and want a radio with a browser interface rather than a bare firmware image. It does not fit anyone expecting a phone app, a screenless WiFi speaker, or a panel whose SD adapter is permanently fitted with series resistors. Before building, check three things on your own hardware: that the SD card pins match the fixed SD_MMC assignment, that the display controller is one of the listed panels, and that the board carries 16MB of flash if OTA updates are wanted. The last push was on 2026-10-20.
Frequently asked questions
What hardware does ESP32-MiniWebRadio need?
An ESP32-S3 or ESP32-P4 board with 8MB of flash or more and at least 4MB of PSRAM, 16MB of flash if you want OTA, an I2S DAC such as a PCM5102A, a TFT display with touchpad (ILI9341, ILI9486, ILI9488 or ST7796 over SPI, an 800x480 RGB panel or a 1024x600 DSI panel) and a FAT32 SD card.
How do I connect ESP32-MiniWebRadio to my WiFi network?
On first boot you can set the home router SSID and password from a phone browser joined to the access point the board creates, with no source changes. The alternative is to edit the networks.csv file on the SD card by hand.
How many radio stations can ESP32-MiniWebRadio hold?
Up to 999 preset stations stored in the stations.csv file on the SD card, which can also be edited through the web UI. Each station can have its own station icon when saved to the card.
Which audio formats can ESP32-MiniWebRadio play?
Software decoding covers mp3, aac, aacp, wav, m4a, flac with a maximum block size of 16KB, vorbis up to 256Kbit/s and opus except in hybrid mode. Files can be played from the SD card or from DLNA sources on the home network.
How do I get files onto the SD card of ESP32-MiniWebRadio?
The internal SD card is exposed over FTP, so a client such as FileZilla can copy files onto it. The username and password are esp32 by default and can be changed in common.h.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/schreibfaul1-esp32-miniwebradio)Was this useful?