跳到主要内容

麦克风(mic)

mic 是萤火虫T1 固件内置的麦克风采集模块,用 I2S PDM 驱动板载的 SPM1423 数字麦克风,把声音变成 16 位 PCM 数据。你既可以直接取原始采样自己做音频分析,也可以只调用 calculate_stats() 拿到一帧的最大值、最小值、平均值——官方固件里的「Soundlight(声音驱动灯带)」应用就是靠它做的,本文的示例与那套算法一致。

引脚写死在模块里

CLK=GPIO40、DIN=GPIO41,初始化参数里改不了。

两个函数就够

只要音量用 calculate_stats();要原始 PCM 用 read_data()。

读取会阻塞

一次调用会攒满整帧才返回,最长等 1 秒,别放进按键回调。

硬件与引脚​

项目值
麦克风SPM1423(PDM 数字麦克风)
时钟引脚GPIO40(固定,参数不可改)
数据引脚GPIO41(固定,参数不可改)
驱动方式I2S PDM,硬件按 sample_rate 持续采集
数据格式16 位有符号 PCM(int16),量程 -32768 ~ 32767,静音中心为 0
模块名mic

初始化成功后麦克风就开始持续采集,数据由硬件自动送进 DMA 缓冲,你只在需要时把缓冲取走即可。

快速开始​

import mic

mic.init(16000, 16, 1, 1024) # 采样率、位宽、声道、缓冲区字节数

for _ in range(5): # 连读 5 帧
stats = mic.calculate_stats()
if stats is None:
print("这一帧没读到数据")
else:
print("max={} min={} avg={}".format(stats['max'], stats['min'], stats['avg']))

mic.release() # 用完必须释放

运行现象:安静环境下 max 在几百以内、avg 贴着 0;对着麦克风说话或拍一下手,max 会跳到几千甚至上万(满量程 32767),min 则出现对应的负值。

初始化参数怎么填​

mic.init() 的四个参数没有默认值,必须全给。

参数含义单位推荐值说明
sample_rate采样率Hz16000常规声音检测足够;8000 更省资源,44100 更细腻
bit_width每个采样的位宽位16填 16,模块按 16 位有符号解析数据
slot_mode声道模式—11 = 单声道,2 = 立体声
buff_size一次读取的缓冲区大小字节1024后面 bytearray 的长度必须 ≥ 这个值

缓冲区大小同时决定「延迟」和「内存」,因为一次读取会攒满整个缓冲区才返回:

buff_size占用内存16 kHz / 16 位单声道下,一次读取约需
10241 KB约 32 毫秒
20482 KB约 64 毫秒
40964 KB约 128 毫秒

做「声音驱动灯效」这类实时反应,1024 最合适;要录一段完整音频再用 4096。估算公式:耗时 ≈ buff_size ÷ (采样率 × 2)。

API 参考​

初始化 mic.init()​

mic.init(sample_rate, bit_width, slot_mode, buff_size)
参数类型取值
sample_rateint采样率(Hz),常用 16000
bit_widthint位宽,填 16
slot_modeint1 = 单声道,2 = 立体声
buff_sizeint缓冲区字节数

无返回值。三个必须知道的行为:

  • 引脚是写死的:CLK=GPIO40、DIN=GPIO41,参数里改不了,也不需要你传。
  • 四个参数必须全给,少一个直接抛 TypeError: Expected 4 arguments: sample_rate, bit_width, slot_mode, buff_size。
  • 重新配置前必须先 mic.release():底层初始化用的是 ESP_ERROR_CHECK 断言,通道或引脚被占用时会直接触发设备重启,而不是抛 Python 异常。这是本模块最容易踩、也最难查的坑。

初始化成功后模块会记住 buff_size,后面 read_data() 与 calculate_stats() 都按它来读。

读取原始数据 mic.read_data()​

bytes_read = mic.read_data(buffer)
参数类型要求
bufferbytearray长度必须 ≥ 初始化时的 buff_size

返回 int:本次实际读到的字节数。

  • 它会阻塞到缓冲区被填满(底层超时上限 1 秒),所以它不是「立刻返回当前音量」那种接口。
  • 缓冲区太小抛 ValueError: Buffer too small for read;没初始化过抛 RuntimeError: mic not initialized。
  • 数据是 16 位有符号 PCM,用 memoryview 按 'h' 解析最省事:
import mic

mic.init(16000, 16, 1, 1024)
buf = bytearray(1024)
n = mic.read_data(buf) # 阻塞,直到读满 1024 字节

samples = memoryview(buf).cast('h', (n // 2,))
peak = max(abs(s) for s in samples)
print("读了 {} 字节,峰值 {}".format(n, peak))

mic.release()

统计分析 mic.calculate_stats()​

stats = mic.calculate_stats() # 返回 dict,或 None

无参数。它自动分配缓冲区、读一帧、算完再释放,你不用管缓冲区的事。

键类型含义
maxint这一帧里的最大采样值
minint这一帧里的最小采样值
avgint这一帧的平均采样值
  • 它同样会阻塞(读满一帧才返回),耗时见上文缓冲区表。
  • 读不到数据时返回 None,而不是抛异常,所以要判断 if stats is None。
  • 未初始化时抛 RuntimeError: mic not initialized。
  • avg 是正负相消后的平均值,静音时贴着 0,判断音量要用 max 和 -min。

释放资源 mic.release()​

mic.release()

无参数、无返回值。关闭并删除 I2S 接收通道,同时把内部记录的 buff_size 清 0。

  • 调用后 read_data() / calculate_stats() 会抛 RuntimeError: mic not initialized,必须重新 init()。
  • 应用退出前一定要调用,否则下次 init() 会因为通道没释放而重启设备。

时序与阻塞行为​

你的调用实际行为
mic.init(...)立即返回;此后麦克风持续采集,数据进 DMA 缓冲
read_data() / calculate_stats()阻塞到攒满一帧(≈ buff_size ÷ (采样率×2) 秒),最长等 1 秒
安静环境max 在几百以内,avg ≈ 0
说话 / 拍手max 跳到几千以上(满量程 32767)
放在按键回调里调用整个系统被卡住一帧的时长,按键和灯效都会变卡

常见坑点​

  1. init() 的四个参数一个都不能省,否则抛 TypeError。
  2. 重复 init() 之前必须先 release()。 底层是 ESP_ERROR_CHECK 断言,冲突时设备直接重启而不是抛异常,表现为「程序一跑就重启」,非常难查。
  3. buff_size 是字节数,不是采样点数。 buff_size=1024 只够 512 个 16 位采样。
  4. read_data() 传入的 bytearray 长度必须 ≥ buff_size,否则抛 ValueError。
  5. 读取是阻塞的。 它不会返回「当前这一瞬间的音量」,而是先攒满一整帧;buff_size 越大,反应越慢。
  6. 判断音量用 max(以及 -min),不要用 avg。 声音是围绕 0 上下振荡的,平均值几乎不动。
  7. calculate_stats() 可能返回 None。 这不是异常,判断后重试即可。
  8. 不要在按键回调里调用麦克风接口。 回调运行在调度上下文,阻塞一帧会把整个系统拖慢。

更多配方​

声音驱动的灯带(与官方 Soundlight 应用同款算法)​

灵敏度 5、静音阈值 20、参考振幅 1000——这几个数值就是官方固件里那套调参。

import mic
import neopixel
from machine import Pin

NUM_PIXELS = 30
SENSITIVITY = 5 # 1~10,越大越灵敏
MUTE_THRESHOLD = 20 # 低于这个音量视为静音
MAX_AMPLITUDE = 1000 # 参考振幅,越大越不灵敏

np = neopixel.NeoPixel(Pin(13), NUM_PIXELS)
mic.init(16000, 16, 1, 1024)


def volume_level(max_value):
level = int((max_value / MAX_AMPLITUDE) * 100 * SENSITIVITY / 5)
if level < MUTE_THRESHOLD:
level = 0
return min(max(level, 0), 100) # 0 ~ 100


try:
while True:
stats = mic.calculate_stats()
if stats is None:
continue
lit = int(NUM_PIXELS * volume_level(stats['max']) / 100)
for i in range(NUM_PIXELS):
np[i] = (0, 80, 0) if i < lit else (0, 0, 0)
np.write()
finally:
np.fill((0, 0, 0))
np.write()
mic.release()

只判断「有没有声音」​

import mic
import time

mic.init(16000, 16, 1, 1024)

NOISE_FLOOR = 800 # 峰值高于它就认为"有声音"

while True:
stats = mic.calculate_stats()
if stats and max(stats['max'], -stats['min']) > NOISE_FLOOR:
print("有声音")
time.sleep(0.05)

把一帧原始 PCM 存成文件​

import mic

mic.init(16000, 16, 1, 4096)
buf = bytearray(4096)

with open('/sd/rec.pcm', 'wb') as f:
for _ in range(25): # 4096 字节 ≈ 128 毫秒/帧,共约 3.2 秒
n = mic.read_data(buf)
f.write(memoryview(buf)[:n])

mic.release()

运行现象:SD 卡根目录出现 rec.pcm,是裸 PCM 数据。用 Audacity 按「导入原始数据 → 有符号 16 位 / 小端 / 单声道 / 16000 Hz」打开即可播放。

完整示例​

萤火虫T1 的应用放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。下面这段放进 /sd/apps/my-sound-app/boot.py:主循环把音量映射成灯带长度,中键短按打印当前这一帧的统计值,中键长按退出。

import mic
import neopixel
from machine import Pin
from button import Button

NUM_PIXELS = 30
MIN_LEVEL = 500 # 峰值低于它视为安静
MAX_LEVEL = 8000 # 峰值到它就算满格

np = neopixel.NeoPixel(Pin(13), NUM_PIXELS)
mic.init(16000, 16, 1, 1024)

buttons = Button()
running = True
dump_once = False # 回调里只置标志,重活留给主循环


def on_center_short():
global dump_once
dump_once = True


def on_center_long():
global running
running = False


buttons.register_callback('center', 'short', on_center_short)
buttons.register_callback('center', 'long', on_center_long)

while running:
stats = mic.calculate_stats() # 阻塞约 32 毫秒,也就是这一帧的时长
if stats is None:
continue

peak = max(stats['max'], -stats['min'])

if dump_once: # 中键短按:打印这一帧的统计值
dump_once = False
print("峰值 {} max={} min={} avg={}".format(
peak, stats['max'], stats['min'], stats['avg']))

level = (peak - MIN_LEVEL) * NUM_PIXELS // (MAX_LEVEL - MIN_LEVEL)
level = min(max(level, 0), NUM_PIXELS)
for i in range(NUM_PIXELS):
np[i] = (0, 90, 0) if i < level else (0, 0, 0)
np.write()

np.fill((0, 0, 0))
np.write()
mic.release() # 退出前必须释放,否则下次 init() 会让设备重启
buttons.deinit()

相关模块见 五向按键(button)、WS2812 炫彩灯(ws2812) 与 蜂鸣器(beep)。

排错​

现象原因 / 处理
抛 TypeError: Expected 4 arguments...init() 少传了参数 → 四个都要给,没有默认值
一调用 init() 设备就重启上次没 release(),或重复 init() 导致通道/引脚冲突触发断言 → 先 release() 再 init()
抛 RuntimeError: mic not initialized没 init(),或已经 release() 过 → 重新 init()
抛 ValueError: Buffer too small for readbytearray 比 buff_size 小 → 长度对齐到 buff_size
calculate_stats() 返回 None这一帧没读到数据 → 判断 None 后重试
灯效反应迟钝、帧率很低buff_size 太大,一帧要等很久 → 降到 1024
明明有声音,avg 却几乎不变avg 是正负相消后的平均值 → 改用 max 和 -min
安静时灯还在闪增益太灵敏 → 调大 MUTE_THRESHOLD / MAX_AMPLITUDE,或调小灵敏度
读数一直是 0没重新 init(),或别处重复初始化了 I2S → 确认只初始化一次,且 release() 后重新初始化

AI 用法(即将上线)​

以后你不用自己去调灵敏度、算阻塞时间:用自然语言描述你想要的音频行为,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。

比如直接对它说:

灯带跟着音量长短变化,安静时全灭;中键短按在屏幕上显示当前峰值,长按退出。

它就会把 mic、neopixel、Button 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。