ESP32I2SAudio.h

/*
    BackgroundAudio
    Plays an audio file using IRQ driven decompression.  Main loop() writes
    data to the buffer but isn't blocked while playing
 
    Copyright (c) 2025 Earle F. Philhower, III <earlephilhower@yahoo.com>
 
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#pragma once
 
#include <driver/i2s_std.h>
#include <atomic>
#include "WrappedAudioOutputBase.h"
 
#if SOC_I2S_HW_VERSION_2
#undef I2S_STD_CLK_DEFAULT_CONFIG
#define I2S_STD_CLK_DEFAULT_CONFIG(rate) \
  { .sample_rate_hz = rate, .clk_src = I2S_CLK_SRC_DEFAULT, .ext_clk_freq_hz = 0, .mclk_multiple = I2S_MCLK_MULTIPLE_256, }
#endif
 
class ESP32I2SAudio : public AudioOutputBase {
public:
    ESP32I2SAudio(int8_t bclk = 0, int8_t ws = 1, int8_t dout = 2, int8_t mclk = -1) {
        _bclk = bclk;
        _ws = ws;
        _dout = dout;
        _mclk = mclk;
        _running = false;
        _sampleRate = 44100;
        _buffers = 5;
        _bufferWords = 1023;
        _silenceSample = 0;
        _cb = nullptr;
        _underflowed = false;
    }
 
    virtual ~ESP32I2SAudio() {
    }
 
    void setPins(int8_t bclk, int8_t ws, int8_t dout, int8_t mclk = -1) {
        _bclk = bclk;
        _ws = ws;
        _dout = dout;
        _mclk = mclk;
    }
 
    void setInverted(bool bclk, bool ws, bool mclk = false) {
        _bclkInv = bclk;
        _wsInv = ws;
        _mclkInv = mclk;
    }
 
    bool setBuffers(size_t buffers, size_t bufferWords, int32_t silenceSample = 0) override {
        if (!_running) {
            _buffers = buffers;
            _bufferWords = bufferWords;
            // We need DMA buffers of 1023 4-byte samples or less. Adjust behind the scenes.
            // The upper level code will get 2x or 4x the IRQs, but availableForWrite() should
            // still report the proper space and let it do nothing for the extra IRQs.
            while (_bufferWords > 1023) {
                _buffers *= 2;
                _bufferWords /= 2;
            }
            _silenceSample = silenceSample;
        }
        return !_running;
    }
 
    bool setBitsPerSample(int bps) override {
        if (!_running && bps == 16)  {
            return true;
        }
        return false;
    }
 
    bool setFrequency(int freq) override {
        if (_running && (_sampleRate != freq)) {
            i2s_std_clk_config_t clk_cfg;
            clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG((uint32_t)freq);
            i2s_channel_disable(_tx_handle);
            i2s_channel_reconfig_std_clock(_tx_handle, &clk_cfg);
            i2s_channel_enable(_tx_handle);
        }
        _sampleRate = freq;
        return true;
    }
 
    bool setStereo(bool stereo = true) override {
        return stereo;
    }
 
    bool begin() override {
        if (_running) {
            return false;
        }
 
        // Make a new channel of the requested buffers (which may be ignored by the IDF!)
        i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(I2S_NUM_AUTO, I2S_ROLE_MASTER);
        chan_cfg.dma_desc_num = _buffers;
        chan_cfg.dma_frame_num = _bufferWords;
        assert(ESP_OK == i2s_new_channel(&chan_cfg, &_tx_handle, nullptr));
 
        i2s_std_config_t std_cfg = {
            .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(_sampleRate),
            .slot_cfg = I2S_STD_MSB_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO),
            .gpio_cfg = {
                .mclk = _mclk < 0 ? I2S_GPIO_UNUSED : (gpio_num_t)_mclk,
                .bclk = (gpio_num_t)_bclk,
                .ws = (gpio_num_t)_ws,
                .dout = (gpio_num_t)_dout,
                .din = I2S_GPIO_UNUSED,
                .invert_flags = {
                    .mclk_inv = _mclkInv,
                    .bclk_inv = _bclkInv,
                    .ws_inv = _wsInv,
                },
            },
        };
        assert(ESP_OK == i2s_channel_init_std_mode(_tx_handle, &std_cfg));
 
        i2s_chan_info_t _info;
        i2s_channel_get_info(_tx_handle, &_info);
        // If the IDF has changed our buffer size or count then we can't work
        assert(_info.total_dma_buf_size == _buffers * _bufferWords * 4);
        _totalAvailable = _info.total_dma_buf_size;
 
        // Prefill silence and calculate how bug we really have
        int16_t a[2] = {0, 0};
        size_t written = 0;
        do {
            i2s_channel_preload_data(_tx_handle, (void*)a, sizeof(a), &written);
        } while (written);
 
        // The IRQ callbacks which will just trigger the playback task
        i2s_event_callbacks_t _cbs = {
            .on_recv = nullptr,
            .on_recv_q_ovf = nullptr,
            .on_sent = _onSent,
            .on_send_q_ovf = nullptr
        };
        assert(ESP_OK == i2s_channel_register_event_callback(_tx_handle, &_cbs, (void *)this));
        xTaskCreate(_taskShim, "BackgroundAudioI2S", 8192, (void*)this, 2, &_taskHandle);
        _running = ESP_OK == i2s_channel_enable(_tx_handle);
        return _running;
    }
 
    static IRAM_ATTR bool _onSent(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx) {
        return ((ESP32I2SAudio *)user_ctx)->_onSentCB(handle, event);
    }
 
    static void _taskShim(void *pvParameters) {
        ((ESP32I2SAudio *)pvParameters)->_backgroundTask();
    }
 
    void _backgroundTask() {
        while (true) {
            // Pause the task until notification comes in from the IRQ callbacks
            uint32_t ulNotifiedValue;
            xTaskNotifyWait(0, ULONG_MAX, &ulNotifiedValue, portMAX_DELAY);
            // One DMA transfer == one frame
            _frames++;
            // Use the notification value to transmit how much data was in the DMA block.  When negative this was an underflow notification
            // Saturating add: _available = min(_available + size, _totalAvailable)
            _saturating_add_available((uint32_t)ulNotifiedValue);
            // Callback used from within a normal FreeRTOS task, so it can be slow and/or write I2S
            if (_cb) {
                _cb(_cbData);
            }
        }
    }
 
    inline void _saturating_add_available(uint32_t add) {
        uint32_t cur = _available.load(std::memory_order_relaxed);
        do {
            uint64_t sum = (uint64_t)cur + add;
            uint32_t capped = sum;
            if (sum > _totalAvailable) {
                capped = (uint32_t) _totalAvailable;  // Cap to the total available
                _underflowed.store(true, std::memory_order_release);
                _underflows.fetch_add(1, std::memory_order_relaxed);
            }
 
            if (_available.compare_exchange_weak(cur, capped, std::memory_order_release, std::memory_order_relaxed)) {
                return;
            }
            // cur reloaded on failure
        } while (true);
    }
 
    inline void _saturating_sub_available(uint32_t sub) {
        uint32_t cur = _available.load(std::memory_order_relaxed);
        do {
            uint32_t next = (cur > sub) ? (cur - sub) : 0u;
            if (_available.compare_exchange_weak(cur, next, std::memory_order_release, std::memory_order_relaxed)) {
                return;
            }
        } while (true);
    }
 
 
    uint32_t frames() {
        return _frames;
    }
 
    uint32_t irqs() {
        return _irqs;
    }
 
    uint32_t underflows() {
        return _underflows.load(std::memory_order_acquire);
    }
 
    IRAM_ATTR bool _onSentCB(i2s_chan_handle_t handle, i2s_event_data_t *event) {
        BaseType_t xHigherPriorityTaskWoken;
        xHigherPriorityTaskWoken = pdFALSE;
        if (_taskHandle) {
            _irqs++;
            xTaskNotifyFromISR(_taskHandle, event->size, eSetValueWithoutOverwrite, &xHigherPriorityTaskWoken);
        }
        if (xHigherPriorityTaskWoken) {
            portYIELD_FROM_ISR();
        }
        return (bool)xHigherPriorityTaskWoken;
    }
 
 
    bool end() override {
        if (_running) {
            i2s_channel_disable(_tx_handle);
            i2s_del_channel(_tx_handle);
            vTaskDelete(_taskHandle);
            _running = false;
        }
        return true;
    }
 
    bool getUnderflow() override {
        // Atomically read-and-clear
        return _underflowed.exchange(false, std::memory_order_acq_rel);
    }
 
    void onTransmit(void(*cb)(void *), void *cbData) override {
        noInterrupts();
        _cb = cb;
        _cbData = cbData;
        interrupts();
    }
 
    size_t write(const uint8_t *buffer, size_t size) override {
        // The ESP32 i2s_channel_write will stop at a DMA buffer end even if add'l DMA buffers are free
        // So explicitly loop until either we run out of DMA buffers or data to fill them with
        size_t cumWritten = 0;
        while (size) {
            size_t written = 0;
            i2s_channel_write(_tx_handle, buffer, size, &written, 100);
            _saturating_sub_available((uint32_t)written);
            buffer += written;
            size -= written;
            cumWritten += written;
            // If we're full-up, don't block just exit
            if (!written) {
                break;
            }
        }
        return cumWritten;
    }
 
    size_t write(uint8_t d) override {
        return 0; // No bytes!
    }
 
    int availableForWrite() override {
        return (int)_available.load(std::memory_order_acquire);
    }
 
protected:
    bool _running;
    int8_t _bclk = 0;
    int8_t _ws = 1;
    int8_t _dout = 2;
    int8_t _mclk = -1;
    bool _bclkInv = false;
    bool _wsInv = false;
    bool _mclkInv = false;
    std::atomic<bool> _underflowed{false};
    size_t _sampleRate;
    size_t _buffers;
    size_t _bufferWords;
    uint32_t _silenceSample;
    TaskHandle_t _taskHandle = 0;
    void (*_cb)(void *);
    void *_cbData;
    // I2S IDF object and info
    i2s_chan_handle_t _tx_handle;
    size_t _totalAvailable = 0;
    std::atomic<uint32_t> _available{0};
    uint32_t _irqs = 0; // Number of I2S IRQs received
    uint32_t _frames = 0; // Number of DMA buffers sent
    std::atomic<uint32_t> _underflows{0}; // Number of underflowed DMA buffers
};