feat(audio): 32-voice polyphony, smooth retriggering, and silent panic

- increase `Audio::kVoiceCount` and `StreamManager::kMaxStreams` to 32
- change retrigger behavior to start a new voice while fading out older voices in the same group
- make panic clear the trigger queue and quickly fade out active voices instead of hard-cut stopping
- remove all `Serial` logging from firmware code
- delete `todo.md`
- update `README.md` and `docs/documentation.md` to match current behavior

Author: jakubthedeveloper

README.md

@@ -15,10 +15,11 @@ Architecture note: `src/main.cpp` is a thin entrypoint, while runtime orchestrat
 ## Current Features
 
 - WAV sample playback from `/samples` on SD.
-- 8-voice polyphony with deterministic oldest-voice stealing.
+- 32-voice polyphony with deterministic oldest-voice stealing.
+- Retrigger starts a new voice instance and softly fades older voices from the same sample group.
 - Playback format for assigned samples is enforced to WAV PCM16, 44.1kHz, mono.
 - Audio playback runs in a dedicated FreeRTOS task/core with trigger events passed by queue.
-- SD stream refill runs in a dedicated task; audio-domain stream reads are served from RAM read-ahead buffers.
+- SD and RAM playback share the same voice engine and mixer pipeline.
 - OLED UI with 2 encoders (via MCP23017).
 - On-device MIDI note to sample assignment.
 - Per-sample `SHOT/LOOP` playback mode (stored in config).
@@ -37,8 +38,6 @@ Architecture note: `src/main.cpp` is a thin entrypoint, while runtime orchestrat
 - optionally add `sampler_config.json` (if missing, firmware starts with defaults).
 3. Flash firmware:
 - `make upload-main`
-4. Open serial log:
-- `make monitor`
 
 ## Flashing Prebuilt Firmware (from GitHub Releases)
 

docs/documentation.md

@@ -100,7 +100,7 @@ Minimal format:
 Notes:
 
 - `note`: `0..127`
-- `panic_note`: optional `0..127`; when received as MIDI NOTE ON, all active voices are stopped immediately
+- `panic_note`: optional `0..127`; when received as MIDI NOTE ON, all active voices are quickly faded out
 - `playback_mode`: optional `"shot"` or `"loop"` stored per assignment/sample
 - `volume`: clamped to `0..100`
 - `volume = 100`: full per-voice level (before dynamic mixer headroom)
@@ -124,14 +124,13 @@ Current pipeline (recently updated):
 
 Playback engine behavior:
 
-- fixed `8`-voice playback pool (`Audio::kVoiceCount`),
+- fixed `32`-voice playback pool (`Audio::kVoiceCount`),
 - each trigger allocates a free voice slot when available,
-- retriggering the same sample reuses its active voice slot when possible (previous instance is stopped and restarted from frame `0`, so the sample does not layer with itself),
+- retriggering the same sample starts a new voice instance and requests short fade-out on already active voices in the same retrigger group,
 - if all voices are active, the incoming trigger steals the oldest active voice (deterministic `oldest-voice` policy),
-- if incoming MIDI NOTE ON matches configured panic note, all currently active voices are stopped,
+- if incoming MIDI NOTE ON matches configured panic note, all currently active voices are quickly faded out and pending trigger backlog is cleared,
 - works for both SD-streamed and RAM-backed sample playback,
-- SD-streamed voices use per-voice read-ahead RAM buffers that are refilled by a dedicated `stream_refill`
-  task; the audio update loop consumes already buffered data (no direct SD read in the critical mix loop),
+- voice update loop applies bounded per-voice decode budget (`kVoiceLoopSampleBudget`) to keep scheduling predictable,
 - per-voice mixer gain uses dynamic headroom (`kDynamicMixMinGain..kDynamicMixMaxGain`) based on active voice count; master output passes through a limiter with make-up gain to increase loudness while controlling clipping.
 - trigger events are sent through a queue from UI/MIDI domain to dedicated audio task (no direct playback calls from UI code path).
 
@@ -170,21 +169,16 @@ Assignment rules:
 
 ### `include/audio.h`
 
-- Audio voice count: `Audio::kVoiceCount = 8`
+- Audio voice count: `Audio::kVoiceCount = 32`
 
 ### `include/boot_screen_flow.h`
 
 - Boot screen dismiss timeout: `BootScreenFlow::kDefaultDismissTimeoutMs = 5000`
 
 ### `include/debug_flags.h`
 
-- Global debug logs switch: `DebugFlags::kEnableDebugLogs`
-- Per-trigger playback logs switch: `DebugFlags::kEnablePerTriggerPlaybackLogs`
-- Input event logs switch: `DebugFlags::kEnableInputEventLogs`
-- Runtime audio diagnostics log switch: `DebugFlags::kEnableRuntimeAudioDiagLogs`
-- Runtime RAM diagnostics log switch: `DebugFlags::kEnableRuntimeRamUsageLogs`
-- Runtime RAM diagnostics interval: `DebugFlags::kRuntimeRamUsageLogIntervalMs = 5000`
-- To enable/disable a log group, edit `include/debug_flags.h` and set the given flag to `true`/`false`, then rebuild and flash firmware (`make upload-main`).
+- Debug flag constants are still defined in code, but main firmware no longer emits diagnostic logs to `Serial`.
+- `DebugFlags::kRuntimeRamUsageLogIntervalMs = 5000` remains as a timing constant used by gated runtime checks.
 
 ### `include/input.h`
 
@@ -209,10 +203,9 @@ Assignment rules:
 
 ### `src/audio.cpp`
 
-- Voice fade-in to reduce trigger click: `kVoiceFadeInUs` (default `0`, feature inactive to avoid transient chopping on percussive sounds; set non-zero microseconds to enable)
 - Audio mixer buffer size: `kMixerBufferSamples = 512`
-- `AUDIO_DIAG` includes trigger handling timing: `play_max_us`, `slow_plays`, `play_count`
-- `AUDIO_DIAG` includes I2S rate-set counters: `rate_set_calls`, `rate_set_skipped`, `rate_set_applied`
+- Retrigger fade-in (new voice): `kRetriggerFadeInUs = 800`
+- Retrigger fade-out (older voices in same group): `kRetriggerFadeOutUs = 1200`
 
 ### `src/sampler_app.cpp`
 
@@ -222,7 +215,6 @@ Assignment rules:
 - Trigger queue length: `32`
 - Loader command queue length: `12`
 - UI status queue length: `16`
-- `RAM_DIAG` includes heap/psram occupancy: `heap_free`, `heap_min`, `heap_size`, `psram_free`, `psram_size`
 
 ### `src/settings_store.cpp`
 
@@ -244,7 +236,7 @@ Assignment rules:
 - `make upload-debug`
 - `make build-debug-midi`
 - `make upload-debug-midi`
-- `make monitor`
+- `make monitor` (optional raw UART monitor; firmware does not print diagnostic logs by default)
 - `make convert-samples SAMPLES_DIR=/path/to/samples` (requires `ffmpeg`, converts `*.wav` in that folder to PCM16/44.1kHz/mono in-place)
 - `make convert-samples /path/to/samples` (equivalent positional form)
   - conversion runs `ffmpeg` with `-nostdin` to avoid stdin conflicts in batch processing.
@@ -255,7 +247,7 @@ Assignment rules:
 - `pio run -e esp-wrover-kit -t upload`
 - `pio run -e esp-wrover-kit-debug-input -t upload`
 - `pio run -e esp-wrover-kit-debug-midi -t upload`
-- `pio device monitor -b 115200`
+- `pio device monitor -b 115200` (optional raw UART monitor)
 
 ## 10. Module Map (Code Orientation)
 
@@ -278,5 +270,5 @@ Assignment rules:
 - `src/sample_classifier.cpp`: assigned sample classification (RAM/STREAM/error modes)
 - `src/sample_ram_manager.cpp`: pool allocation and WAV data preload into RAM
 - `src/active_sample_registry.cpp`: final active-sample registry after fallback handling
-- `src/audio.cpp`: 8-voice playback engine (SD + RAM), mixer, and oldest-voice stealing
-- `src/stream_manager.cpp`: buffered SD stream sources and background refill task for streamed voices
+- `src/audio.cpp`: 32-voice playback engine (SD + RAM), mixer, retrigger fade behavior, and oldest-voice stealing
+- `src/stream_manager.cpp`: per-voice SD stream source wrappers and stream diagnostics

include/audio.h

@@ -5,7 +5,7 @@
 
 class Audio {
  public:
-  static constexpr uint8_t kVoiceCount = 8;
+  static constexpr uint8_t kVoiceCount = 32;
   static constexpr uint16_t kWaveformPointCount = 128;
 
   struct RuntimeStats {
@@ -31,6 +31,7 @@ class Audio {
                       int16_t retriggerGroupId = -1,
                       bool loopEnabled = false);
   void stopAllVoices();
+  void fadeOutAllVoices(uint32_t fadeOutUs);
   void stopLoopingVoicesForGroup(int16_t retriggerGroupId);
   void setLoopEnabledForGroup(int16_t retriggerGroupId, bool loopEnabled);
   bool playSampleRam(const uint8_t *pcmData,

include/stream_manager.h

@@ -8,7 +8,7 @@ class AudioFileSource;
 
 class StreamManager {
  public:
-  static constexpr uint8_t kMaxStreams = 8;
+  static constexpr uint8_t kMaxStreams = 32;
 
   struct Diagnostics {
     uint32_t sourceReadCount = 0;