MojoScale Studio Docs
API Reference

microphone

Generic analog and I2S microphone module.

All modules Open Studio
Studio Docs Sensors & I/O

import microphone

The microphone module measures sound level and captures short signed 16-bit mono audio buffers. Use ``Analog`` for ADC microphone amplifier boards such as MAX4466, MAX9814, and analog LM358 modules. Use ``I2S`` for standard digital I2S microphones such as INMP441 and ICS-43434. For I2S microphones, the three required pins are the GPIO numbers you choose on your board. Match the microphone board labels to the constructor names: SCK/BCLK/BCK goes to ``bclk``, WS/LRCLK/LRC goes to ``ws``, and SD/DOUT/DATA goes to ``data``. ``dbfs()`` reports electrical signal level relative to digital full scale. It is useful for comparing quiet and loud sounds on the same board, but it is not calibrated sound-pressure level. ``db_spl()`` returns None until the microphone has been explicitly calibrated with ``calibrate_spl()``.

Quick example

import microphone
import system

mic = microphone.Analog(pin=34)
mic.begin()

def show_sound():
    print({
        "level": mic.level(window_ms=100),
        "peak": mic.peak(window_ms=100),
        "dbfs": mic.dbfs(window_ms=100),
    })

system.schedule("sound", 250, 0, -1, show_sound)

import microphone

mic = microphone.I2S(
    bclk=14,
    ws=15,
    data=32,
    sample_rate=16000,
    channel=microphone.CHANNEL_LEFT,
)
mic.begin()
audio = mic.read(samples=512, timeout_ms=1000)
if audio != None:
    print(audio.count, audio.rms(), audio.dbfs())

importmicrophone

Generic analog and I2S microphone module.

The microphone module measures sound level and captures short signed 16-bit mono audio buffers. Use ``Analog`` for ADC microphone amplifier boards such as MAX4466, MAX9814, and analog LM358 modules. Use ``I2S`` for standard digital I2S microphones such as INMP441 and ICS-43434. For I2S microphones, the three required pins are the GPIO numbers you choose on your board. Match the microphone board labels to the constructor names: SCK/BCLK/BCK goes to ``bclk``, WS/LRCLK/LRC goes to ``ws``, and SD/DOUT/DATA goes to ``data``. ``dbfs()`` reports electrical signal level relative to digital full scale. It is useful for comparing quiet and loud sounds on the same board, but it is not calibrated sound-pressure level. ``db_spl()`` returns None until the microphone has been explicitly calibrated with ``calibrate_spl()``.

API 58 available

microphone.Analog(pin: int, sample_rate: int = None, attenuation: int = None, center: any = None, resolution: int = None) -> microphone_device

Create an analog microphone object using an ESP32 ADC input.

Analog microphone boards must output a biased analog waveform. Boards that expose only a digital threshold output cannot provide audio samples. Wire VCC to 3V3 or the voltage required by the board, GND to GND, and the board's OUT/AO/SIG pin to the ADC GPIO passed as ``pin``.

Parameters
Name Type Pass as Required Description
pin int positional or keyword Yes Required ADC-capable GPIO connected to the microphone analog output pin labeled OUT, AO, or SIG. On ESP32-class boards, ADC2 pins can time out while WiFi is active. Prefer ADC1 pins for scripts that also use WiFi.
sample_rate int positional or keyword No Optional sample rate in samples per second. Defaults to 8000.
attenuation int positional or keyword No Optional ADC attenuation in dB. Use 0, 2, 6, or 12. Defaults to 11, which maps to the firmware's high-range ADC attenuation.
center any positional or keyword No Optional DC midpoint. Use "auto" for automatic estimation or pass a raw ADC value such as 2048. Defaults to "auto".
resolution int positional or keyword No Optional output sample resolution. The current firmware returns signed 16-bit samples.
Returns

microphone_device microphone_device object.

microphone.Analog().begin() -> bool

Start acquisition and allocate hardware resources.

microphone.Analog().stop() -> bool

Stop acquisition and release ADC/I2S resources.

microphone.Analog().is_running() -> bool

Return True when the microphone is active.

microphone.Analog().read(samples=256, timeout_ms=100) -> audio_buffer

Capture signed 16-bit mono samples, or None when no audio is available.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to 256.
timeout_ms int positional or keyword No Optional value. Defaults to 100.

microphone.Analog().level(window_ms=50) -> float

Return normalized RMS level from 0.0 through 1.0.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.Analog().rms(window_ms=50) -> float

Return normalized RMS amplitude.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.Analog().peak(window_ms=50) -> float

Return normalized peak amplitude.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.Analog().peak_to_peak(window_ms=50) -> float

Return normalized max-min movement.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.Analog().dbfs(window_ms=50) -> float

Return RMS level in dBFS. This is not dB SPL.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.Analog().db_spl(window_ms=125) -> float

Return estimated SPL after calibrate_spl(), otherwise None.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 125.

microphone.Analog().is_loud(threshold_dbfs=-20, window_ms=50) -> bool

Return True when dBFS crosses the threshold.

Parameters
Name Type Pass as Required Description
threshold_dbfs float positional or keyword No Optional value. Defaults to -20.
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.Analog().configure(gain_db=0, dc_block=True, noise_floor_dbfs=-120, smoothing=0, clip_detection=True) -> bool

Change processing behavior without recreating the microphone.

Parameters
Name Type Pass as Required Description
gain_db float positional or keyword No Optional value. Defaults to 0.
dc_block bool positional or keyword No Optional value. Defaults to True.
noise_floor_dbfs any positional or keyword No Optional value. Defaults to -120.
smoothing any positional or keyword No Optional value. Defaults to 0.
clip_detection bool positional or keyword No Optional value. Defaults to True.

microphone.Analog().calibrate_silence(duration_ms=1000) -> dict

Measure quiet noise floor and DC offset.

Parameters
Name Type Pass as Required Description
duration_ms int positional or keyword No Optional value. Defaults to 1000.

microphone.Analog().calibrate_spl(reference_db_spl, duration_ms=1000) -> dict

Calibrate SPL estimate against a known reference.

Parameters
Name Type Pass as Required Description
reference_db_spl any positional or keyword Yes Required value.
duration_ms int positional or keyword No Optional value. Defaults to 1000.

microphone.Analog().clear_calibration() -> bool

Clear silence and SPL calibration.

microphone.Analog().on_audio(callback, samples_per_buffer=512) -> bool

Register a callback receiving a bounded audio summary dict. Pass None to stop.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.
samples_per_buffer any positional or keyword No Optional value. Defaults to 512.

microphone.Analog().on_level(interval_ms, callback) -> bool

Register a callback receiving a level measurement dict.

Parameters
Name Type Pass as Required Description
interval_ms int positional or keyword Yes Required value.
callback callback positional or keyword Yes Required value.

microphone.Analog().on_loud(threshold_dbfs, callback, hysteresis_db=3, cooldown_ms=500) -> bool

Register a loud-sound event callback.

Parameters
Name Type Pass as Required Description
threshold_dbfs float positional or keyword Yes Required value.
callback callback positional or keyword Yes Required value.
hysteresis_db any positional or keyword No Optional value. Defaults to 3.
cooldown_ms int positional or keyword No Optional value. Defaults to 500.

microphone.Analog().stats() -> dict

Return source, sample rate, buffer, clipping, and calibration diagnostics.

microphone.Analog().reset_stats() -> bool

Reset cumulative counters.

microphone.Analog().close() -> bool

Stop and close the native microphone object.

microphone.Analog().AudioBuffer Methods

microphone.Analog().sample(index) -> int

Return one signed sample.

Parameters
Name Type Pass as Required Description
index any positional or keyword Yes Required value.

microphone.Analog().samples() -> list

Convert the buffer to a Berry list. This allocates memory.

microphone.Analog().rms() -> float

Return normalized RMS for this buffer.

microphone.Analog().peak() -> float

Return normalized peak for this buffer.

microphone.Analog().dbfs() -> float

Return dBFS for this buffer.

microphone.Analog().bytes() -> bytes

Return little-endian signed 16-bit PCM bytes.

microphone.I2S(bclk: int, ws: int, data: int, sample_rate: int = None, bits: int = None, channel: str = None, i2s: int = None, gain_db: float = None) -> microphone_device

Create a standard I2S microphone object.

This supports standard I2S digital microphones. PDM microphones and proprietary codecs are not treated as standard I2S devices. Wiring is explicit: pass the ESP32 GPIO number connected to each microphone signal. Microphone boards commonly label these pins as SCK/BCLK/BCK, WS/LRCLK/LRC, and SD/DOUT/DATA. The example ``bclk=14, ws=15, data=32`` is just one wiring choice, not a fixed requirement. Most I2S microphone boards also have an L/R or SEL pin. Tie that pin to GND for left channel or 3V3 for right channel, then pass the matching ``microphone.CHANNEL_LEFT`` or ``microphone.CHANNEL_RIGHT`` constant. If the readings are silent, try the other channel.

Parameters
Name Type Pass as Required Description
bclk int positional or keyword Yes Required GPIO number connected to the microphone clock pin labeled SCK, BCLK, or BCK.
ws int positional or keyword Yes Required GPIO number connected to the microphone word-select pin labeled WS, LRCLK, LRC, or WSEL.
data int positional or keyword Yes Required GPIO number connected to the microphone data-output pin labeled SD, DOUT, DATA, or DIN on the ESP32 side.
sample_rate int positional or keyword No Optional audio sample rate. Defaults to 16000.
bits int positional or keyword No Optional bits per I2S slot. Use 16, 24, or 32. Defaults to 32.
channel str positional or keyword No Optional data channel. Use microphone.CHANNEL_LEFT, microphone.CHANNEL_RIGHT, or microphone.CHANNEL_MONO. Defaults to microphone.CHANNEL_LEFT.
i2s int positional or keyword No Optional I2S peripheral number. Defaults to automatic selection.
gain_db float positional or keyword No Optional digital gain applied after sample conversion. Defaults to 0.
Returns

microphone_device microphone_device object.

microphone.I2S().begin() -> bool

Start acquisition and allocate hardware resources.

microphone.I2S().stop() -> bool

Stop acquisition and release ADC/I2S resources.

microphone.I2S().is_running() -> bool

Return True when the microphone is active.

microphone.I2S().read(samples=256, timeout_ms=100) -> audio_buffer

Capture signed 16-bit mono samples, or None when no audio is available.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to 256.
timeout_ms int positional or keyword No Optional value. Defaults to 100.

microphone.I2S().level(window_ms=50) -> float

Return normalized RMS level from 0.0 through 1.0.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.I2S().rms(window_ms=50) -> float

Return normalized RMS amplitude.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.I2S().peak(window_ms=50) -> float

Return normalized peak amplitude.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.I2S().peak_to_peak(window_ms=50) -> float

Return normalized max-min movement.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.I2S().dbfs(window_ms=50) -> float

Return RMS level in dBFS. This is not dB SPL.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.I2S().db_spl(window_ms=125) -> float

Return estimated SPL after calibrate_spl(), otherwise None.

Parameters
Name Type Pass as Required Description
window_ms int positional or keyword No Optional value. Defaults to 125.

microphone.I2S().is_loud(threshold_dbfs=-20, window_ms=50) -> bool

Return True when dBFS crosses the threshold.

Parameters
Name Type Pass as Required Description
threshold_dbfs float positional or keyword No Optional value. Defaults to -20.
window_ms int positional or keyword No Optional value. Defaults to 50.

microphone.I2S().configure(gain_db=0, dc_block=True, noise_floor_dbfs=-120, smoothing=0, clip_detection=True) -> bool

Change processing behavior without recreating the microphone.

Parameters
Name Type Pass as Required Description
gain_db float positional or keyword No Optional value. Defaults to 0.
dc_block bool positional or keyword No Optional value. Defaults to True.
noise_floor_dbfs any positional or keyword No Optional value. Defaults to -120.
smoothing any positional or keyword No Optional value. Defaults to 0.
clip_detection bool positional or keyword No Optional value. Defaults to True.

microphone.I2S().calibrate_silence(duration_ms=1000) -> dict

Measure quiet noise floor and DC offset.

Parameters
Name Type Pass as Required Description
duration_ms int positional or keyword No Optional value. Defaults to 1000.

microphone.I2S().calibrate_spl(reference_db_spl, duration_ms=1000) -> dict

Calibrate SPL estimate against a known reference.

Parameters
Name Type Pass as Required Description
reference_db_spl any positional or keyword Yes Required value.
duration_ms int positional or keyword No Optional value. Defaults to 1000.

microphone.I2S().clear_calibration() -> bool

Clear silence and SPL calibration.

microphone.I2S().on_audio(callback, samples_per_buffer=512) -> bool

Register a callback receiving a bounded audio summary dict. Pass None to stop.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.
samples_per_buffer any positional or keyword No Optional value. Defaults to 512.

microphone.I2S().on_level(interval_ms, callback) -> bool

Register a callback receiving a level measurement dict.

Parameters
Name Type Pass as Required Description
interval_ms int positional or keyword Yes Required value.
callback callback positional or keyword Yes Required value.

microphone.I2S().on_loud(threshold_dbfs, callback, hysteresis_db=3, cooldown_ms=500) -> bool

Register a loud-sound event callback.

Parameters
Name Type Pass as Required Description
threshold_dbfs float positional or keyword Yes Required value.
callback callback positional or keyword Yes Required value.
hysteresis_db any positional or keyword No Optional value. Defaults to 3.
cooldown_ms int positional or keyword No Optional value. Defaults to 500.

microphone.I2S().stats() -> dict

Return source, sample rate, buffer, clipping, and calibration diagnostics.

microphone.I2S().reset_stats() -> bool

Reset cumulative counters.

microphone.I2S().close() -> bool

Stop and close the native microphone object.

microphone.I2S().AudioBuffer Methods

microphone.I2S().sample(index) -> int

Return one signed sample.

Parameters
Name Type Pass as Required Description
index any positional or keyword Yes Required value.

microphone.I2S().samples() -> list

Convert the buffer to a Berry list. This allocates memory.

microphone.I2S().rms() -> float

Return normalized RMS for this buffer.

microphone.I2S().peak() -> float

Return normalized peak for this buffer.

microphone.I2S().dbfs() -> float

Return dBFS for this buffer.

microphone.I2S().bytes() -> bytes

Return little-endian signed 16-bit PCM bytes.