NiusAudio

One Arduino-style API for codec boards, I2S DACs and ADCs, digital microphones, analog front ends, amplifiers, and wireless audio modules.

NiusAudio turns the small audio boards sold under many different storefront names into explicit, readable sketches. Pick a module class, state the wiring, start control and transport, then play or capture signed PCM without dynamic allocation in the library’s frame paths.

#include <NiusAudio.h>

NiusAudioWeActEs8311Board audio;

void setup() {
  Serial.begin(115200);

  audio.setControlPins(3, 8, 9, 10);  // SD, SDA, SCL, MCLK
  audio.setAudioPins(14, 12, 13, 11); // BCLK, codec DOUT, WS, codec DIN
  audio.setFormat(16000, 16, 1);

  if (!audio.begin() || !audio.beginAudio()) {
    Serial.println(audio.lastMessage());
    return;
  }

  audio.setOutputVolume(70);
  audio.playTone(660, 500);
}

void loop() {}

Highlights

• ESP32 I2S playback and microphone capture through the current Arduino-ESP32 transport.
• ES8311, WM8960, PCM5122, PCM1863, and ES7243E control-oriented drivers.
• Ready-to-play output classes for MAX98357A, PCM5102A, PT8211, ES9023, CS4344, UDA1334A, and related I2S modules.
• Ready-to-capture classes for PCM1808, CS5343, INMP441, ICS43434, SPH0645, MSM261S4030H0, and related digital microphones.
• Generic I2S input and output classes for compatible no-register-control breakouts, so a new storefront label does not require a new library fork.
• Analog helpers for MAX9814, MAX4466, PAM8403, MAX98306, TPA3116D2, and LM386.
• Control helpers for MH-M18, KCX Bluetooth emitter, JDY-64, and BK3266 boards.
• Fixed-size stack frames, explicit partial-I/O results, and no hidden sample heap in the transport helpers.

The module catalog intentionally follows chip markings and signal interfaces, not seller titles. That keeps the same driver useful when an equivalent module is listed on AliExpress, Amazon, eBay, or a local electronics shop.

Install

Arduino IDE

1. Download a release ZIP from the repository.
2. In Arduino IDE choose Sketch → Include Library → Add .ZIP Library….
3. Open File → Examples → NiusAudio.

Arduino CLI

arduino-cli lib install --git-url https://github.com/dunknowcoding/NiusAudio

Source checkout

Clone this repository into the Arduino sketchbook libraries directory, or install a release archive so only the published library surface is present.

Choose a driver

Your module	Start with	Data path
WeAct ES8311 + NS4150B	NiusAudioWeActEs8311Board	I2C + I2S play/capture
MAX98357A	NiusAudioMax98357Board	I2S playback
PCM5102A	NiusAudioPcm5102Board	I2S stereo playback
PCM5122	NiusAudioPcm5122Board	I2C/hardware mode + I2S
WM8960	NiusAudioWm8960Board	I2C + I2S play/capture
PCM1808 / CS5343	matching module class	I2S capture
INMP441 / ICS43434 / SPH0645	matching microphone class	I2S capture
Unlisted I2S DAC or amplifier without registers	NiusAudioGenericI2sOutput	I2S playback
Unlisted I2S ADC or microphone without registers	NiusAudioGenericI2sInput	I2S capture
MAX9814 / MAX4466	matching analog class	ADC level sampling

The module catalog maps common board markings and pins. The board matrix shows the transport available on each architecture.

Generic I2S modules

Many low-cost modules expose only BCLK, WS/LRCK, and DIN or DOUT. Those modules can use the generic drivers directly:

NiusAudioGenericI2sOutput dac;

void setup() {
  dac.setPins(14, 13, 11);   // BCLK, WS, module DIN
  dac.setFormat(44100, 16, 2);
  if (dac.begin()) {
    dac.playTone(440, 300);
  }
}

The generic classes are for modules whose required mode is established by hardware straps. Codecs that require register programming should use their named driver.

API shape

Module classes use a small common vocabulary:

• setPins(...), or setControlPins(...) plus setAudioPins(...)
• setFormat(sampleRate, bitsPerSample, channels)
• begin() and, for codec modules, beginAudio()
• writeSamples(...) and readSamples(...)
• playTone(...), captureAverageLevel(...), and capturePeakLevel(...)
• endAudio(), audioReady(), and lastMessage()

The current PCM convenience API is signed 16-bit. The ESP32 backend rejects a wider configured sample format instead of silently sending incorrectly packed frames.

Validation

The repository’s automated checks enforce:

• strict Arduino library lint;
• AVR umbrella-header compilation;
• ESP32-S3 ES8311 playback/capture compilation;
• generic I2S input/output compilation;
• absence of generated build products in the release tree.

Hardware qualification uses codec response, transport start, bounded PCM playback, microphone capture, and recovery telemetry. Listening to the speaker is useful diagnostics, while machine-readable transport and capture results remain the reproducible verdict.

See validation notes and the API reference for details.

Ecosystem

NiusAudio is the Arduino member of the nobro-audio ecosystem. NobroRTOS adds bounded frame queues, deadline accounting, backpressure, admission prices, and board-feature evidence without changing the familiar module classes.

License

Apache License 2.0. See LICENSE.