OXRecorder::OXAudioManager

Overview

OXAudioManager drives an INMP441 I2S MEMS microphone: it installs the I2S peripheral, controls the recording lifecycle (begin / pause / resume / stop), and continuously delivers recorded 16-bit PCM for further processing — writing to disk via OXFileManager, streaming, or encrypting with OXSecurity.

There are two ways to receive audio, usable together or separately:

• Push — register a callback with onAudio(); it fires with each freshly captured chunk when you pump poll().
• Pull — call read() to drain PCM that poll() has buffered, on your own schedule.

The default pin map and audio format match the validated INMP441-ESP32-S3 reference exactly, and every parameter is overridable through AudioConfig. The raw 32-bit I2S words are also exposed for advanced DSP.

Declared in include/OXAudioManager.h; portable core in src/OXAudioManager.cpp; the ESP-IDF I2S backend in src/audio/Esp32I2SDevice.cpp. Diagnostics go through OXLog.

Wiring (INMP441 → ESP32-S3 Super Mini)

Default pins, matching the reference hardware:

With L/R tied to GND, the manager must select the right I2S slot (leftChannel = false, the default) to actually capture the mic. The selector is inverted relative to the WS phase; this is intentional and explained on the internals page.

AudioConfig

All fields default to the validated reference values; override any of them before calling begin().

AudioState enum class

API reference

Lifecycle

Receiving audio

Test seam

Examples

1. Stream the microphone to an SD file (push callback)

The most common pattern: register a callback that writes each PCM chunk to a file via OXFileManager, then pump poll() from loop().

#include <Arduino.h>
#include "OXAudioManager.h"
#include "OXFileManager.h"
#include "OXLog.h"

using namespace OXRecorder;

OXAudioManager audio;
OXFileManager fm;
OXFileStream recFile;

// Called by poll() with each chunk of captured PCM.
void onAudio(const int16_t *pcm, size_t n, void *ctx) {
  if (recFile.isOpen()) {
    recFile.write(reinterpret_cast<const uint8_t *>(pcm), n * sizeof(int16_t));
  }
}

void setup() {
  OXLog::begin(115200);
  fm.beginExternal();                 // mount SD card
  fm.mkdir(Storage::External, "/rec");
  recFile = fm.openWrite(Storage::External, "/rec/take01.pcm");

  audio.onAudio(onAudio);
  if (!audio.begin()) {                  // default pins/format
    OXLog::error("mic start failed");
  }
}

void loop() {
  audio.poll();                         // pump capture -> onAudio()
}

2. Pull samples with read()

If you would rather own the cadence, skip the callback and drain buffered PCM yourself. Still call poll() to pump the hardware.

OXAudioManager audio;

void setup() {
  OXLog::begin(115200);
  audio.begin();
}

void loop() {
  audio.poll();                         // capture into the internal buffer

  int16_t buf[256];
  size_t n = audio.read(buf, 256);   // pull what's available
  if (n > 0) {
    // ... process n samples in buf (FFT, level meter, send over network) ...
  }
}

3. Pause & resume

pause() stops delivery instantly without tearing down the driver, so resume() has no setup latency. Useful for push-to-talk or muting during playback.

// Mute while a button is held, capture otherwise.
if (buttonPressed && audio.isRunning()) {
  audio.pause();
} else if (!buttonPressed && audio.state() == AudioState::Paused) {
  audio.resume();
}
audio.poll();   // while paused, poll() drains DMA but delivers nothing

4. Stop and free the peripheral

audio.stop();   // uninstalls I2S, releases GPIO9/8/7
// The pins are now free for other use; call begin() again to restart.

5. Override the pins / format

Construct an AudioConfig, change what you need, and pass it to begin(). Everything you do not set keeps the reference default.

AudioConfig cfg;
cfg.bclkPin = 4;        // different wiring
cfg.wsPin = 5;
cfg.dataPin = 6;
cfg.sampleRateHz = 8000;  // 8 kHz instead of 16 kHz
cfg.gainShift = 2;       // ~+12 dB
audio.begin(cfg);

Sample output

[31][I] OXAudioManager: started (16000 Hz, right channel)
[42][I] OXAudioManager: paused
[55][I] OXAudioManager: resumed
[80][I] OXAudioManager: stopped

Complete recording sketch

A full, working src/main.cpp that records a fixed-length clip to the SD card and finalizes it safely. It combines everything above: mount the card, open a streaming file, register the callback, pump poll() with no blocking delay, flush periodically so a power cut can't lose buffered data, and close cleanly so the file's size is written to the directory.

#include <Arduino.h>
#include "OXAudioManager.h"
#include "OXFileManager.h"
#include "OXLog.h"

using namespace OXRecorder;

OXAudioManager audio;
OXFileManager fm;
OXFileStream recFile;

// How long to record before finalizing the file, in milliseconds.
static const uint32_t kRecordMs = 10000;  // 10 seconds

// Flush (commit buffered bytes + update the directory size) this often.
// Without periodic sync, a power loss loses everything since the file opened.
static const uint32_t kFlushIntervalMs = 1000;

static uint32_t g_recStartMs = 0;
static uint32_t g_lastFlushMs = 0;
static uint32_t g_bytesWritten = 0;
static bool g_recording = false;

// Called by audio.poll() with each chunk of captured PCM.
void onAudio(const int16_t *pcm, size_t n, void *ctx) {
  if (!recFile.isOpen()) {
    return;
  }
  size_t bytes = n * sizeof(int16_t);
  size_t w = recFile.write(reinterpret_cast<const uint8_t *>(pcm), bytes);
  g_bytesWritten += w;
  if (w != bytes) {
    OXLog::warn("short write (%u/%u) — SD full or too slow?", (unsigned)w,
                (unsigned)bytes);
  }
}

void setup() {
  OXLog::begin(115200);
  delay(1000);  // give the USB CDC serial a moment to come up
  OXLog::info("OXRecorder audio capture starting");

  // SD card on the default ESP32-S3 pins (CS=10, SCK=11, MISO=13, MOSI=12).
  if (!fm.beginExternal()) {
    OXLog::error("SD card mount failed");
    return;
  }

  fm.mkdir(Storage::External, "/rec");
  recFile = fm.openWrite(Storage::External, "/rec/take01.pcm");
  if (!recFile.isOpen()) {
    OXLog::error("could not open /rec/take01.pcm for writing");
    return;
  }

  audio.onAudio(onAudio);
  if (!audio.begin()) {  // default format: 16 kHz mono, BCLK=1 WS=2 DATA=21
    OXLog::error("mic start failed");
    return;
  }

  g_recording = true;
  g_recStartMs = millis();
  g_lastFlushMs = g_recStartMs;
  OXLog::info("recording %lu ms to /rec/take01.pcm ...",
              (unsigned long)kRecordMs);
}

void loop() {
  if (!g_recording) {
    return;  // idle; safe to power off after the "complete" log below
  }

  // Pump the mic as fast as possible — drains the I2S DMA and delivers PCM to
  // onAudio(). Do NOT put blocking delay() here or the DMA overflows.
  audio.poll();

  uint32_t now = millis();

  // Periodically commit buffered data so a power cut doesn't lose it.
  if (now - g_lastFlushMs >= kFlushIntervalMs) {
    recFile.flush();
    g_lastFlushMs = now;
    OXLog::info("... %u bytes written", (unsigned)g_bytesWritten);
  }

  // Finalize when the recording window elapses.
  if (now - g_recStartMs >= kRecordMs) {
    audio.stop();        // stop capture
    recFile.flush();     // commit the last bytes
    recFile.close();     // write the final directory entry (file size)
    g_recording = false;
    OXLog::info("recording complete: %u bytes in /rec/take01.pcm",
                (unsigned)g_bytesWritten);
    OXLog::info("SD free: %u bytes — safe to power off now",
                (unsigned)fm.freeBytes(Storage::External));
  }
}

Recorded PCM format

OXAudioManager delivers — and the sketch above writes — raw, headerless PCM with these properties (the AudioConfig defaults):

That is 16000 × 2 = 32000 bytes per second, so a 10-second clip is about 320 KB. There is no header in the file: the format is implied, not stored. If you change sampleRateHz in AudioConfig, update the conversion command below to match.

Converting the .pcm to a .wav

Players generally can't open a headerless .pcm directly, so either tell the player the format explicitly or wrap the samples in a WAV header. The easiest path is ffmpeg — copy take01.pcm off the SD card to your computer and run:

ffmpeg -f s16le -ar 16000 -ac 1 -i take01.pcm take01.wav

To listen without converting, point a player at the raw file with the same parameters:

ffplay -f s16le -ar 16000 -ch_layout mono take01.pcm
# or with SoX:
play -t raw -e signed -b 16 -r 16000 -c 1 take01.pcm

Prefer a ready-to-play file on the device? Have the firmware write a 44-byte WAV header before the samples and patch in the sizes at close() — then no host-side conversion is needed.

Notes

• Pump regularly. Capture is cooperative: poll() must be called often enough to keep up with the DMA, or the driver's buffers fill and samples are lost. Avoid long blocking work in loop().
• Pull buffer is bounded. If you use read() and drain too slowly, the internal ring (2048 samples) overflows and drops the oldest samples, with an OXLog warning. Drain promptly or rely on the callback.
• Mono, 16-bit. Delivered PCM is single-channel signed 16-bit at sampleRateHz — write it straight into a WAV body or stream it as-is.