/** * @file sound_engine.cpp * @brief I2S speaker rendering task (8 kHz, 16-bit, mono). * * Based on the wiring used by examples/SimpleTone: * BCK = GPIO7, WS = GPIO5, DOUT = GPIO6. * * Sounds are rendered strictly in queue order; layering is achieved by * queueing several events back to back (e.g. a rumble sweep followed by a * noise tail reads as one big explosion). */ #include "sound_engine.h" #include "utilities.h" #include #define SND_SAMPLE_RATE 8000 #define SND_I2S_PORT I2S_NUM_0 #define SND_CHUNK 128 // samples per i2s_write call #define SND_FADE_MS 8 // fade in/out to avoid clicks #define SND_DMA_BUFS 8 // TX DMA ring: buffer count (cfg.dma_buf_count) #define SND_DMA_LEN 64 // ... and samples per buffer (cfg.dma_buf_len) // Ring capacity in samples: 512 = 64 ms of audio at 8 kHz. Playback lags // i2s_write() by up to this much — see purgeRing(). #define SND_RING_SAMPLES (SND_DMA_BUFS * SND_DMA_LEN) bool SoundEngine::begin(bool spawnTask) { // Queue first: the headless tests call begin(false) in environments // without an audio device, where i2s_driver_install() legitimately fails // (the shim just runs silent) — the render path itself must still work. q_ = xQueueCreate(12, sizeof(SndEvent)); if (q_ == nullptr) { return false; } i2s_config_t cfg = {}; cfg.mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_TX); cfg.sample_rate = SND_SAMPLE_RATE; cfg.bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT; cfg.channel_format = I2S_CHANNEL_FMT_ONLY_LEFT; cfg.communication_format = I2S_COMM_FORMAT_STAND_I2S; cfg.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1; cfg.dma_buf_count = SND_DMA_BUFS; cfg.dma_buf_len = SND_DMA_LEN; if (i2s_driver_install(SND_I2S_PORT, &cfg, 0, NULL) != ESP_OK) { return false; } i2s_pin_config_t pins = {}; pins.bck_io_num = BOARD_I2S_BCK; pins.ws_io_num = BOARD_I2S_WS; pins.data_out_num = BOARD_I2S_DOUT; pins.data_in_num = I2S_PIN_NO_CHANGE; // MCLK must be explicitly disabled: `= {}` zero-initializes mck_io_num // to 0, and i2s_set_pin() then claims GPIO0 as the MCLK output (GPIO0 is // one of the few MCLK-capable pins) — GPIO0 is the trackball centre / // BOOT line, so the click would go dead. pins.mck_io_num = I2S_PIN_NO_CHANGE; i2s_set_pin(SND_I2S_PORT, &pins); if (!spawnTask) { return true; // tests drive pumpOne() by hand } // Render on core 0; the game loop runs on core 1. return xTaskCreatePinnedToCore(trampoline, "sound", 4096, this, 5, nullptr, 0) == pdTRUE; } void SoundEngine::play(const SndEvent &e) { if (q_) { xQueueSend(q_, &e, 0); // drop instead of blocking the game } } void SoundEngine::trampoline(void *arg) { static_cast(arg)->task(); } void SoundEngine::task() { for (;;) { pumpOne(); } } // One render-loop iteration: take the next queued event, render it, and — // once nothing else is queued — flush the TX DMA ring with silence. Public // test seam: the headless tests call this directly (deterministic, no task // thread); task() simply loops it on the device. void SoundEngine::pumpOne() { if (q_ == nullptr) return; SndEvent e; xQueueReceive(q_, &e, portMAX_DELAY); switch (e.type) { case SND_TONE: renderTone(e.freq, e.dur, e.amp); break; case SND_SWEEP: renderSweep(e.freq, e.freq2, e.dur, e.amp); break; case SND_NOISE: renderNoise(e.dur, e.amp); break; } // Flush only after the LAST queued event — between queued events a flush // would punch silence gaps into back-to-back melodies. if (uxQueueMessagesWaiting(q_) == 0) { purgeRing(); } } // Overwrite the whole TX DMA ring with silence so the DMA wrap-around cannot // replay the sound's tail. This MUST be paced i2s_write() calls, NOT // i2s_zero_dma_buffer(): the legacy driver's zero_dma memsets the entire ring // instantly, erasing everything not yet played. Any sound that fits inside // the ring (512 samples = 64 ms @ 8 kHz — every short beep in the game) was // written into free ring space without ever blocking, so the zeroing wiped it // before the DMA reached a single sample: silent on hardware, while longer // tones survived because i2s_write blocks on a full ring and paces rendering // to real-time playback. Writing zeros through i2s_write instead reuses each // DMA buffer only after the DMA has finished playing it — the sound plays out // fully, and the ring then loops silence (no tail replay either). void SoundEngine::purgeRing() { static int16_t silence[SND_CHUNK]; // zero-initialized for (uint32_t n = 0; n < SND_RING_SAMPLES + SND_CHUNK; n += SND_CHUNK) { size_t bw; i2s_write(SND_I2S_PORT, silence, sizeof(silence), &bw, portMAX_DELAY); } } void SoundEngine::volumeUp() { if (vol_ < VOL_MAX) vol_++; } void SoundEngine::volumeDown() { if (vol_ > 0) vol_--; } void SoundEngine::toggleMute() { if (vol_ > 0) { lastVol_ = vol_; vol_ = 0; } else { vol_ = lastVol_ > 0 ? lastVol_ : VOL_MAX / 2; } } // Restore a saved volume level (from NVS at boot); 0 keeps the device muted // while lastVol_ stays at its default so unmute still works. void SoundEngine::setVolume(uint8_t v) { if (v > VOL_MAX) v = VOL_MAX; vol_ = v; if (vol_ > 0) lastVol_ = vol_; } // Scaled peak amplitude for the current volume level static inline uint32_t scaledAmp(uint16_t amp, uint8_t vol) { return ((uint32_t)amp * vol) / SoundEngine::VOL_MAX; } // Fade envelope over the first/last SND_FADE_MS of the whole event static inline uint32_t envelope(uint32_t pos, uint32_t total, uint32_t fade, uint32_t amp) { if (fade * 4 > total) fade = total / 4; uint32_t s = amp; if (pos < fade) s = s * pos / fade; uint32_t tail = total - pos; if (tail < fade) s = s * tail / fade; return s; } void SoundEngine::renderTone(uint16_t freq, uint16_t durMs, uint16_t amp) { static int16_t buf[SND_CHUNK]; uint32_t a = scaledAmp(amp, vol_); if (a == 0) return; uint32_t total = (uint32_t)SND_SAMPLE_RATE * durMs / 1000; if (total == 0) return; uint32_t half = (freq > 0) ? (SND_SAMPLE_RATE / 2) / freq : 1; if (half == 0) half = 1; uint32_t fade = (uint32_t)SND_SAMPLE_RATE * SND_FADE_MS / 1000; if (fade < 2) fade = 2; uint32_t phase = 0; for (uint32_t i = 0; i < total; ) { uint32_t n = (total - i < SND_CHUNK) ? (total - i) : SND_CHUNK; for (uint32_t k = 0; k < n; k++) { int32_t s = ((phase / half) & 1) ? (int32_t)a : -(int32_t)a; buf[k] = (int16_t)(s * (int32_t)envelope(i + k, total, fade, 256) / 256); phase++; } size_t bw; i2s_write(SND_I2S_PORT, buf, n * sizeof(int16_t), &bw, portMAX_DELAY); i += n; } } // Square wave gliding from freq0 to freq1 (Hz) over the duration. // Phase is carried in a float cycle counter (0..1) so frequency changes // never click. void SoundEngine::renderSweep(uint16_t freq0, uint16_t freq1, uint16_t durMs, uint16_t amp) { static int16_t buf[SND_CHUNK]; uint32_t a = scaledAmp(amp, vol_); if (a == 0) return; uint32_t total = (uint32_t)SND_SAMPLE_RATE * durMs / 1000; if (total == 0) return; uint32_t fade = (uint32_t)SND_SAMPLE_RATE * SND_FADE_MS / 1000; if (fade < 2) fade = 2; float phase = 0.0f; for (uint32_t i = 0; i < total; ) { uint32_t n = (total - i < SND_CHUNK) ? (total - i) : SND_CHUNK; for (uint32_t k = 0; k < n; k++) { uint32_t pos = i + k; float f = (float)freq0 + ((float)(int16_t)(freq1 - freq0) * (float)pos) / (float)total; if (f < 20.0f) f = 20.0f; phase += f / (float)SND_SAMPLE_RATE; if (phase >= 1.0f) phase -= 1.0f; int32_t s = (phase < 0.5f) ? (int32_t)a : -(int32_t)a; buf[k] = (int16_t)(s * (int32_t)envelope(pos, total, fade, 256) / 256); } size_t bw; i2s_write(SND_I2S_PORT, buf, n * sizeof(int16_t), &bw, portMAX_DELAY); i += n; } } void SoundEngine::renderNoise(uint16_t durMs, uint16_t amp) { static int16_t buf[SND_CHUNK]; uint32_t a = scaledAmp(amp, vol_); if (a == 0) return; uint32_t total = (uint32_t)SND_SAMPLE_RATE * durMs / 1000; if (total == 0) return; uint32_t seed = esp_random() | 1; for (uint32_t i = 0; i < total; ) { uint32_t n = (total - i < SND_CHUNK) ? (total - i) : SND_CHUNK; for (uint32_t k = 0; k < n; k++) { // xorshift32 for cheap white noise seed ^= seed << 13; seed ^= seed >> 17; seed ^= seed << 5; int32_t signedS = (int32_t)(seed & 0xFFFF) - 32768; // linear decay over the burst int32_t s = (int32_t)(((int64_t)signedS * a * (int64_t)(total - i - k)) / ((int64_t)32768 * (int64_t)total)); buf[k] = (int16_t)s; } size_t bw; i2s_write(SND_I2S_PORT, buf, n * sizeof(int16_t), &bw, portMAX_DELAY); i += n; } }