audioi2sin – Support for recording audio from an I2S input source.
The audioi2sin module contains the I2SIn class for recording audio
from an external I2S source such as a MEMS microphone (e.g. SPH0645LM4H
or INMP441).
All classes change hardware state and should be deinitialized when they
are no longer needed. To do so, either call deinit() or use a
context manager.
Available on these boards
- class audioi2sin.I2SIn(bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, main_clock: microcontroller.Pin | None = None, sample_rate: int = 16000, bit_depth: int = 16, output_bit_depth: int | None = None, mono: bool = True, left_justified: bool = False, samples_signed: bool = True)
Record an input I2S audio stream from an external I2S source such as a MEMS microphone.
Create an I2SIn object associated with the given pins. This allows you to record audio signals from an external I2S source (e.g. an I2S MEMS microphone like the SPH0645LM4H or INMP441).
The pin signature mirrors
audiobusio.I2SOutso users can swap classes; recording parameters mirroraudiobusio.PDMIn.- Parameters:
bit_clock (Pin) – The bit clock (or serial clock) pin
word_select (Pin) – The word select (or left/right clock) pin
data (Pin) – The data input pin
main_clock (Pin) – The main clock pin. Not all ports support this.
sample_rate (int) – Target sample rate of the resulting samples. Check
sample_ratefor actual value.bit_depth (int) –
Number of bits per sample on the I2S bus. Must be 8, 16, 24, or 32. 8-bit only supported on espressif. The destination buffer typecode is determined by
output_bit_depth(orbit_depthwhenoutput_bit_depthisNone):samples_signed
output_bit_depth
Required typecode(s)
True
24 or 32
'i'True
16
'h'True
8
'b'or BYTEARRAYFalse
24 or 32
'I'False
16
'H'False
8
'B'or BYTEARRAYNote that 24-bit samples from mics like the SPH0645LM4H / INMP441 are transported in 32-bit slots, so use
bit_depth=32and an'I'buffer.output_bit_depth (int) – If set, recorded samples are rescaled from
bit_depthto this width before being written to the destination buffer (8, 16, 24, or 32). Widening bit-replicates so full-scale input maps to full-scale output (e.g. 16-bit0xFFFF-> 24-bit0xFFFFFF); narrowing arithmetic-shifts the value right (sign-preserving whensamples_signedis True). WhenNone(the default) the destination buffer holds samples atbit_depth(a 24-bit sample still occupies a 32-bit'i'/'I'slot, sign-extended without rescaling).mono (bool) – True when capturing a single channel of audio, captures two channels otherwise.
left_justified (bool) – True when data bits are aligned with the word select clock. False when they are shifted by one to match classic I2S protocol. Set True for mics like the SPH0645LM4H.
samples_signed (bool) – Samples are signed (True) or unsigned (False). I2S mics deliver signed two’s-complement PCM natively; set False to have the recorded samples converted to unsigned PCM (the top/sign bit is flipped, matching the WAV convention for unsigned samples).
Example, recording 16-bit mono samples from an INMP441:
import array import audioi2sin import board buf = array.array("h", [0] * 16000) with audioi2sin.I2SIn(board.D9, board.D10, board.D11, sample_rate=16000, bit_depth=16) as mic: mic.record(buf, len(buf))
- __exit__() None
Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.
- record(destination: circuitpython_typing.WriteableBuffer, destination_length: int) int
Records destination_length samples to destination. This is blocking.
- Returns:
The number of samples recorded. If this is less than
destination_length, some samples were missed due to processing time.
- sample_rate: int
The actual sample rate of the recording. This may not match the constructed sample rate due to internal clock limitations.