The legacy I2S driver buffers i2s_write() data in a TX DMA ring (8x64 samples = 64 ms @ 8 kHz) and hands a buffer back to i2s_write() only after the DMA finished playing it. After the last queued event the sound task called i2s_zero_dma_buffer(), which memsets the whole ring instantly — erasing everything not yet played. Any sound <= 64 ms was written into free ring space without ever blocking, so the zeroing wiped it before the DMA reached a single sample: completely silent on hardware. Longer tones force i2s_write() to block on a full ring, pacing rendering to real-time playback — hence only long beeps were audible, and the fade-envelope cap never moved the threshold. Every game beep <= 80 ms (link-active 10, laser 30, sever 40, bleep/ICE 50, feedback 80) sat in the dead zone. The emulator never showed it: its i2s_write shim fed SDL directly and had no ring at all. Fix: replace the instant zeroing with a paced silence purge — once the queue drains, write one ring + one chunk of zero samples through i2s_write(), reusing each DMA buffer only after the DMA played it. The sound plays out fully and the ring then loops silence (still kills the tail-replay bug the zeroing existed for). Keep the envelope cap at total/4 so short tones keep a steady-state portion. Emulator shim gains a TX DMA ring model (write/play cursors + bounded DAC-emitted log) so the bug class reproduces headlessly: unit/ sound_short_tone_reaches_dac fails on the zero_dma code, passes on the purge (A/B verified); shim_zero_dma_erases_unplayed pins model fidelity; sound_long_tone_plays_out_fully guards against truncation. SoundEngine gains a pumpOne() test seam and begin(spawnTask) for deterministic driving. Full suite: 26 unit + 7 integration + 4 E2E, 0 failures.
268 lines
9.2 KiB
C++
268 lines
9.2 KiB
C++
/**
|
|
* @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 <driver/i2s.h>
|
|
|
|
#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<SoundEngine *>(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;
|
|
}
|
|
} |