audio_capture.hpp

Go to the documentation of this file.

#ifndef SBL_COMMON_DIAGNOSTICS_AUDIO_CAPTURE_HPP_
#define SBL_COMMON_DIAGNOSTICS_AUDIO_CAPTURE_HPP_
 
#include <cstdint>
 
#if __has_include(<ff.h>)
#include <ff.h>
#define SBL_HAS_FATFS 1
#endif
 
namespace sbl::diagnostics {
 
/// Always-on audio capture ring buffer for host-side analysis.
///
/// Continuously records the last MaxFrames of audio into a circular buffer.
/// No arming needed — the buffer always has the latest audio. To read:
///
///   1. Freeze the buffer (via SWD write or app trigger) — audio keeps playing
///   2. Read pos_ to know the ring head position
///   3. Read buf_left_/buf_right_ via sbl-debugger
///   4. Unfreeze to resume capture
///   5. Unroll the ring: [pos_..MaxFrames) then [0..pos_) = chronological order
///
/// The sbl-debugger `audio_capture` tool handles all of this automatically.
///
/// Example:
///   static sbl::diagnostics::AudioCapture<4096> s_audio_capture;
///
///   void audio_callback(int32_t* tx, const int32_t* rx, uint16_t frames) {
///       render(left_buf, right_buf, frames);
///       s_audio_capture.feed(left_buf, right_buf, frames);
///       sbl::dsp::types::interleave_from_float(left_buf, right_buf, tx, frames);
///   }
///
/// Cost: ~1us per 48-frame block when active. Single branch when frozen.
///
/// Template parameter MaxFrames controls buffer size and capture duration:
///   2048  -> 16 KB stereo, 42.7 ms @ 48kHz
///   4096  -> 32 KB stereo, 85.3 ms @ 48kHz  (default)
///   8192  -> 64 KB stereo, 170.7 ms @ 48kHz
///   16384 -> 128 KB stereo, 341.3 ms @ 48kHz
template <uint16_t MaxFrames = 4096>
class AudioCapture {
public:
    /// Call from audio callback every block. Always-on ring buffer write.
    /// No-op when frozen. ~1us for 48 stereo frames.
    void feed(const float* left, const float* right, uint16_t frames) {
        if (frozen_) return;
 
        for (uint16_t i = 0; i < frames; ++i) {
            buf_left_[pos_]  = left[i];
            buf_right_[pos_] = right[i];
            pos_ = (pos_ + 1 < MaxFrames) ? pos_ + 1 : 0;
        }
 
        // Track total writes so the reader knows the buffer is full
        if (!ready_) {
            written_ += frames;
            if (written_ >= MaxFrames) ready_ = true;
        }
    }
 
    /// Freeze the buffer — stops writing. Audio callback continues normally.
    /// Safe to call from any context (ISR, main loop, SWD write to frozen_).
    void freeze() { frozen_ = true; }
 
    /// Resume writing after a freeze.
    void unfreeze() { frozen_ = false; }
 
#ifdef SBL_HAS_FATFS
    /// Dump the ring buffer to a 32-bit float WAV file via FatFs.
    /// Freezes capture during write, then resumes. Returns true on success.
    /// On platforms without a filesystem, f_open fails and this returns false.
    bool dump_to_file(const char* path, uint32_t sample_rate = 48000) {
        if (!ready_) return false;
        freeze();
 
        FIL fil;
        if (f_open(&fil, path, FA_CREATE_ALWAYS | FA_WRITE) != FR_OK) {
            unfreeze();
            return false;
        }
 
        // WAV header — 32-bit IEEE float, stereo
        constexpr uint16_t channels = 2;
        constexpr uint16_t bits = 32;
        constexpr uint16_t fmt_pcm_float = 3;
        uint32_t data_size = MaxFrames * channels * sizeof(float);
        uint32_t file_size = 36 + data_size;
        uint32_t fmt_size = 16;
        uint32_t byte_rate = sample_rate * channels * (bits / 8);
        uint16_t block_align = channels * (bits / 8);
        UINT bw;
 
        f_write(&fil, "RIFF", 4, &bw);
        f_write(&fil, &file_size, 4, &bw);
        f_write(&fil, "WAVE", 4, &bw);
        f_write(&fil, "fmt ", 4, &bw);
        f_write(&fil, &fmt_size, 4, &bw);
        f_write(&fil, &fmt_pcm_float, 2, &bw);
        f_write(&fil, &channels, 2, &bw);
        f_write(&fil, &sample_rate, 4, &bw);
        f_write(&fil, &byte_rate, 4, &bw);
        f_write(&fil, &block_align, 2, &bw);
        f_write(&fil, &bits, 2, &bw);
        f_write(&fil, "data", 4, &bw);
        f_write(&fil, &data_size, 4, &bw);
 
        // Unroll ring: [pos..MaxFrames) then [0..pos), interleaved stereo
        uint16_t p = pos_;
        for (uint16_t pass = 0; pass < 2; ++pass) {
            uint16_t start = (pass == 0) ? p : 0;
            uint16_t end   = (pass == 0) ? MaxFrames : p;
            for (uint16_t i = start; i < end; ++i) {
                f_write(&fil, &buf_left_[i], sizeof(float), &bw);
                f_write(&fil, &buf_right_[i], sizeof(float), &bw);
            }
        }
 
        f_close(&fil);
        unfreeze();
        return true;
    }
#endif // SBL_HAS_FATFS
 
    // ── State fields — readable/writable via sbl-debugger ──
 
    volatile bool     frozen_  = false;  // When true, feed() is a no-op
    volatile bool     ready_   = false;  // True once buffer has been fully written
    volatile uint16_t pos_     = 0;      // Ring head: next write position
    volatile uint32_t written_ = 0;      // Total samples written (for ready_ detection)
 
    // ── Sample buffers — readable via sbl-debugger read_memory ──
 
    float buf_left_[MaxFrames]  = {};
    float buf_right_[MaxFrames] = {};
 
    static constexpr uint16_t max_frames = MaxFrames;
};
 
} // namespace sbl::diagnostics
 
#endif // SBL_COMMON_DIAGNOSTICS_AUDIO_CAPTURE_HPP_