麦克风(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 | 采样率 | Hz | 16000 | 常规声音检测足够;8000 更省资源,44100 更细腻 |
bit_width | 每个采样的位宽 | 位 | 16 | 填 16,模块按 16 位有符号解析数据 |
slot_mode | 声道模式 | — | 1 | 1 = 单声道,2 = 立体声 |
buff_size | 一次读取的缓冲区大小 | 字节 | 1024 | 后面 bytearray 的长度必须 ≥ 这个值 |
缓冲区大小同时决定「延迟」和「内存」,因为一次读取会攒满整个缓冲区才返回:
buff_size | 占用内存 | 16 kHz / 16 位单声道下,一次读取约需 |
|---|---|---|
1024 | 1 KB | 约 32 毫秒 |
2048 | 2 KB | 约 64 毫秒 |
4096 | 4 KB | 约 128 毫秒 |
做「声音驱动灯效」这类实时反应,1024 最合适;要录一段完整音频再用 4096。估算公式:耗时 ≈ buff_size ÷ (采样率 × 2)。
API 参考
初始化 mic.init()
mic.init(sample_rate, bit_width, slot_mode, buff_size)
| 参数 | 类型 | 取值 |
|---|---|---|
sample_rate | int | 采样率(Hz),常用 16000 |
bit_width | int | 位宽,填 16 |
slot_mode | int | 1 = 单声道,2 = 立体声 |
buff_size | int | 缓冲区字节数 |
无返回值。三个必须知道的行为:
- 引脚是写死的:
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)
| 参数 | 类型 | 要求 |
|---|---|---|
buffer | bytearray | 长度必须 ≥ 初始化时的 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
无参数。它自动分配缓冲区、读一帧、算完再释放,你不用管缓冲区的事。
| 键 | 类型 | 含义 |
|---|---|---|
max | int | 这一帧里的最大采样值 |
min | int | 这一帧里的最小采样值 |
avg | int | 这一帧的平均采样值 |
- 它同样会阻塞(读满一帧才返回),耗时见上文缓冲区表。
- 读不到数据时返回
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) |
| 放在按键回调里调用 | 整个系统被卡住一帧的时长,按键和灯效都会变卡 |
常见坑点
init()的四个参数一个都不能省,否则抛TypeError。- 重复
init()之前必须先release()。 底层是ESP_ERROR_CHECK断言,冲突时设备直接重启而不是抛异常,表现为「程序一跑就重启」,非常难查。 buff_size是字节数,不是采样点数。buff_size=1024只够 512 个 16 位采样。read_data()传入的bytearray长度必须 ≥buff_size,否则抛ValueError。- 读取是阻塞的。 它不会返回「当前这一瞬间的音量」,而是先攒满一整帧;
buff_size越大,反应越慢。 - 判断音量用
max(以及-min),不要用avg。 声音是围绕 0 上下振荡的,平均值几乎不动。 calculate_stats()可能返回None。 这不是异常,判断后重试即可。- 不要在按键回调里调用麦克风接口。 回调运行在调度上下文,阻塞一帧会把整个系统拖慢。
更多配方
声音驱动的灯带(与官方 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 read | bytearray 比 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/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。