# ESP32-audioI2S for MP3, SD, and network audio

> ESP32-audioI2S decodes several audio formats and sends them through I2S to external DACs and amplifiers. It targets multi-core ESP32 boards, while ESP32-S2, ESP32-C3, and other excluded targets are not compatible.

**schreibfaul1/ESP32-audioI2S** — Play mp3 files from SD via I2S

- Repository: https://github.com/schreibfaul1/ESP32-audioI2S
- Stars: 1,714 · Forks: 426
- Language: C
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/schreibfaul1-esp32-audioi2s

## ESP32-audioI2S scope and supported targets

ESP32-audioI2S addresses the gap between obtaining digital audio and producing usable analog sound on an ESP32. It accepts compressed and uncompressed audio, then exposes it through an I2S interface for an external digital-to-analog converter or a combined DAC and amplifier. The README lists wav, mp3, aac, flac, opus, and vorbis as supported codecs. It also identifies ogg, mp4, and m3u8 as supported container formats. Sample rates can range from 16 to 48 kHz, with sample widths of 8, 16, 24, and 32 bits documented as supported.

The hardware restriction matters more than the format list. The README says the library works only on multi-core chips such as ESP32-S3, ESP32-S31, and ESP32-P4. It describes the original ESP32 as suitable only to a limited extent and explicitly says the library does not work on ESP32-S2 or ESP32-C3. Developers cannot therefore treat the ESP32 family as interchangeable. A project that begins with a C3 or S2 may need different hardware before this library becomes viable.

The library is aimed at embedded firmware developers who need an audio pipeline rather than a bare peripheral example. The repository includes examples for SD playback, SD over MMC, directory playback, Ethernet, Bluetooth transmission, Google TTS, OpenAI speech, web radio, audio recording, filters, and boards with integrated audio codecs. It can be compiled with the Arduino IDE. This repository layout suggests a library intended for device prototypes and firmware integrations, not a desktop command-line player or a general media player.

## Network, SD, and speech input paths

The documented network path begins by connecting the board to Wi-Fi, configuring the I2S pins, selecting a volume, and opening a host URL through `audio.connecttohost()`. The README example uses an AAC internet radio stream, but the format support list covers several local and streamed formats. The examples directory additionally contains `I2Saudio_SD`, `I2Saudio_SD_MMC`, and `plays all files in a directory`, indicating support for local media workflows that are not demonstrated in the main README excerpt.

This breadth is useful when the input changes during development. A prototype can start with a radio URL, move to Google or OpenAI speech examples, and later use files from an SD card. However, the repository does not document one universal input configuration in the README excerpt. The exact behavior for SD card mounting, file selection, codec behavior, or buffering should be checked in the relevant example before assuming that every format works identically from storage and from a network stream.

The callback mechanism exposes playback events as the library works. Documented event types include stream bitrate, station metadata, stream title, ICY URLs and descriptions, images, lyrics, end-of-file messages, and general log messages. This provides a way to display information on a screen, serialize status data, or record playback events. The README does not specify buffering limits, latency guarantees, reconnection behavior, or memory consumption, so those properties should not be inferred from the presence of network playback.

## I2S pinout and external DAC wiring

ESP32-audioI2S expects the target board to expose an I2S data output, bit clock, and left-right clock. The README assigns these signals as `I2S_DOUT`, `I2S_BCLK`, and `I2S_LRC`, then passes them to `audio.setPinout()`. The mapping is passed as bit clock, left-right clock, and data output. The actual GPIO numbers are application choices in the example, so the shown values should not be copied into a different board without checking its pin availability and hardware restrictions.

The explicitly documented output hardware includes MAX98357A, UDA1334A, PCM5102A, and CS4344. MAX98357A is described as a 3 watt amplifier with a DAC connected through three lines: `DOUT`, `BLCK`, and `LRC`. Two MAX98357A devices are required for stereo according to the README. Other hardware may work, but the repository description does not claim that it has been tested. That distinction is important for adoption. Listing a codec as possibly compatible is weaker than documenting a supported board, pin configuration, and verified audio path.

The library can also use external codecs represented by examples such as `ES8311`, `ES8388`, and `ES9038`. The README does not explain their register configuration or electrical requirements, so the corresponding example files are the relevant starting point. I2S pin selection also cannot be separated from board-level concerns such as GPIO availability and peripheral routing, although the README does not state the exact constraints for each supported board.

## First Arduino network stream setup

The shortest documented first use opens an AAC internet stream and prints audio information over the serial connection. Replace the masked network credentials, select suitable I2S pins, and compile the sketch in the Arduino IDE. The callback prints each event, while `audio.loop()` services playback continuously.

```c++
#include "Arduino.h"
#include "WiFi.h"
#include "Audio.h"

#define I2S_DOUT      25
#define I2S_BCLK      27
#define I2S_LRC       26

String ssid =     "*******";
String password = "*******";

Audio audio;
```

This block defines the three signal assignments, connection credentials, and `Audio` instance. The README does not give a library-manager installation command, platform version, or board-selection procedure, so installation through the Arduino IDE must be based on the repository's own instructions or wiki rather than an invented package command. Readers should expect the sketch to upload only after the target is set to a board category supported by the library.

The callback reports status and metadata through the serial port at 115200 baud. Call this before `connecttohost()` when the stream should provide immediate diagnostic output.

```c++
void my_audio_info(Audio::msg_t m) {
    Serial.printf("%s: %s\n", m.s, m.msg);
}
```

The setup sequence waits for Wi-Fi, assigns the I2S pins, sets the documented volume range of 0 through 21, and opens the sample stream.

```c++
void setup() {
    Audio::audio_info_callback = my_audio_info;
    Serial.begin(115200);
    WiFi.begin(ssid.c_str(), password.c_str());
    while (WiFi.status() != WL_CONNECTED) delay(1500);
    audio.setPinout(I2S_BCLK, I2S_LRC, I2S_DOUT);
    audio.setVolume(21);
    audio.connecttohost("http://stream.antennethueringen.de/live/aac-64/stream.antennethueringen.de/");
}
```

The loop calls `audio.loop()` and then yields for one tick. The reader should expect serial messages from the callback as the library starts playback and reports stream information.

```c++
void loop(){
    audio.loop();
    vTaskDelay(1);
}
```

## SD playback examples and source-specific verification

Local playback should start from the repository's SD examples rather than from the network sketch by assumption. The source tree contains `examples/I2Saudio_SD/`, `examples/I2Saudio_SD_MMC/`, and `examples/plays all files in a directory/`. These names establish that SD-card access and directory traversal are intended use cases. They do not, in the README excerpt, document the required card format, mount procedure, supported file naming rules, maximum directory size, or whether every codec can be used from local storage.

That distinction affects engineering decisions. A device intended only to play a fixed set of local files can avoid network credentials, stream metadata, and remote availability. A player that must scan arbitrary folders needs the example's storage and directory assumptions checked directly. The README does not provide enough detail to compare the memory and latency behavior of local SD playback with network playback.

For speech and network integrations, the repository includes `I2Saudio_GoogleTTS`, `I2Saudio_OpenAI`, and `Ethernet` examples. The README states that AudioI2S can play icy streams, Google TTS, and OpenAI speech, but it does not document authentication variables, response formats, polling rules, or error handling in the excerpt. Those examples should be treated as concrete integration references, not as proof of a stable general-purpose API for every service.

## Format, timing, and hardware trade-offs

The documented codec and sample-format coverage is broad, but the fixed output rate introduces an important design constraint. For MAX98357A, the README says the I2S output frequency is always 48 kHz regardless of the input source. That can simplify matching the external device's expected clock. It also means the application cannot assume that an input at 44.1 kHz is emitted unchanged at 44.1 kHz through this path.

The library accepts input rates from 16 to 48 kHz and offers a fixed output setting of 44.1 or 48 kHz when required by an external I2S device, according to the README. The README does not describe the resampling algorithm, its latency, its ratio handling, or its effect on pitch and timing. For speech or music, those details may be decisive. They need direct examination in the relevant example or source before a product makes timing-sensitive assumptions.

The codec list also does not mean that every combination of container, bit depth, sample rate, and output hardware has identical support. The README groups these capabilities broadly, while the examples represent particular integrations. The safest adoption process is to select one real file or stream, one supported board, and one documented DAC, then verify the callback output and physical audio path.

A real alternative is to use a hardware audio codec or board-level audio implementation for designs centered on recording and playback through devices such as ES8311, ES8388, or ES9038. That approach changes the boundary of the project. ESP32-audioI2S is a format, source, and streaming library with an I2S output path. A codec-specific implementation is narrower at the software layer but may be easier to reason about when the target hardware is fixed and its control interface is already known. The README does not provide enough detail to claim one has lower latency or better quality.

## Maintenance, releases, and GPL-3.0 integration

The repository is not archived, and its last push was on 2026-10-12. Recent releases include 4.0.0 on 2026-08-06, 3.4.7 on 2026-07-08, and 3.4.6 on 2026-05-09. Those dates indicate recent repository activity and published releases, but they do not establish compatibility, response time, or long-term support for a particular board. Upgrade planning should therefore inspect the release changes and compare the target example with the selected version.

The library is licensed under GPL-3.0. For a private prototype, the README does not provide legal guidance about obligations. For firmware that is distributed, linked, or incorporated into a product, the license's exact terms and the project's distribution structure need a qualified review. GPL-3.0 is a concrete integration constraint, not a quality signal.

The practical upgrade cost depends on the example path. Changes to pin assignment, source connections, callbacks, or supported board families could affect an existing sketch, although the README does not document a compatibility policy. Keep the selected example and library release identified when evaluating an update, especially if the design depends on metadata callbacks or fixed 48 kHz MAX98357A output.

## Conclusion

ESP32-audioI2S suits developers building network-radio, speech, SD-card, or general audio projects around an ESP32-S3, ESP32-S31, or ESP32-P4 and a supported external I2S device. It is a poor fit for ESP32-S2, ESP32-C3, and other targets that the README excludes. Before adoption, verify the exact board, pin assignment, external codec or amplifier wiring, and the example corresponding to the intended source. Projects distributed under GPL-3.0 must also account for the license when integrating this library. On the stated hardware support and documented 48 kHz MAX98357A output, ESP32-audioI2S is a direct fit for the supported ESP32 audio use cases, but the README does not establish compatibility with arbitrary I2S hardware.

## FAQ

### Which ESP32 boards work with ESP32-audioI2S?

The README says the library works only on multi-core chips such as ESP32-S3, ESP32-S31, and ESP32-P4. It says the original ESP32 is suitable only to a limited extent, while ESP32-S2 and ESP32-C3 are not supported.

### Which audio formats can ESP32-audioI2S play?

The documented codecs are wav, mp3, aac, flac, opus, and vorbis. The README also lists ogg, mp4, and m3u8 as container formats and supports sample rates from 16 to 48 kHz.

### How do I connect a MAX98357A to ESP32-audioI2S?

The documented connection uses the I2S `DOUT`, `BLCK`, and `LRC` lines. The README states that AudioI2S sends output at 48 kHz with MAX98357A, and that two devices are required for stereo.

## Sources

- [Issues](https://github.com/schreibfaul1/ESP32-audioI2S/issues)
- [License: GPL-3.0](https://github.com/schreibfaul1/ESP32-audioI2S/blob/master/LICENSE)
- [README](https://github.com/schreibfaul1/ESP32-audioI2S/blob/master/README.md)
- [Releases](https://github.com/schreibfaul1/ESP32-audioI2S/releases)
- [schreibfaul1/ESP32-audioI2S on GitHub](https://github.com/schreibfaul1/ESP32-audioI2S)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/schreibfaul1-esp32-audioi2s