be-more-agent 是一个运行在 Raspberry Pi 上、100% 本地化的 AI 智能体项目。它的"嘴巴"由Piper TTS神经语音引擎驱动，开箱即附带一个本地微调的BMO 音色。本文将带你快速换装这个自定义 BMO 音色，并给出一份采样率失配导致的"变声坑"完整排查清单——照着做，几步就能救回"低沉魔音"。


📌适合人群：刚装好 be-more-agent、想换音色，或遇到声音快慢/音调异常的新手

📂涉及文件：agent.py、config.json、setup.sh、start_agent.sh

一、先搞懂声音系统：BMO 是如何在树莓派上开口的

在换音色之前，先了解声音链路，排查问题时才能"对症下药"：

1. 文字生成：Ollama 大模型流式输出回复，按句号/问号切分成句子，进入 TTS 队列（见 agent.py 的流式循环）；
2. 语音合成：后台线程从队列取句子，调用本地 Piper 可执行文件./piper/piper --model <音色> --output-raw生成原始 PCM 音频（见 agent.py 的speak()方法）；
3. 音频播放：--output-raw输出的裸音频通过sd.RawOutputStream直接推给扬声器，播放采样率由常量PIPER_RATE决定（默认 22050 Hz，见 agent.py）；若设备不支持该速率，会自动用scipy.signal.resample重采样（见 agent.py）。

⚠️ 记住这条链路：模型自带采样率 + 播放采样率 + 模型的 length_scale，三者任何一个对不上，就是变声的根源。


二、一键安装步骤：快速部署 Piper TTS 与 BMO 音色

1. 准备系统与 Ollama

先更新系统并安装 Ollama（大模型"大脑"），拉取gemma3:1b与moondream模型。

2. 克隆仓库并运行安装脚本

git clone https://gitcode.com/gh_mirrors/be/be-more-agent cd be-more-agent chmod +x setup.sh ./setup.sh

setup.sh 会自动完成 6 件事，与声音相关的有 4 件：

• 下载 Piper TTS 引擎到piper/目录（自动识别 aarch64 架构，见 setup.sh）；
• 下载默认音色en_GB-semaine-medium.onnx及其.json配置文件；
• 下载自定义 BMO 音色，保存为voices/bmo-custom.onnx和voices/bmo-custom.onnx.json（见 setup.sh）；
• 创建 Python 虚拟环境并安装 requirements.txt 中的依赖（sounddevice、numpy、scipy 等）。

3. 启动智能体

./start_agent.sh

start_agent.sh 会自动激活虚拟环境并运行 agent.py。首次启动会播放sounds/greeting_sounds/里的问候音效——如果这时听到声音，说明 Piper 播放链路已打通。

三、音色换装指南：两步切换到 BMO 音色

好消息是，setup.sh 已经帮你把 BMO 音色下载好了，换装只需两步：

第一步：确认模型文件就位

voices/目录下应有两个文件：bmo-custom.onnx（模型）和bmo-custom.onnx.json（配置，必须同名同目录）。Piper 靠这个 json 知道模型的采样率和推理参数。

第二步：修改 config.json

打开 config.json，把voice_model指向 BMO 模型：

"voice_model": "voices/bmo-custom.onnx"

保存后重启智能体即可。同理，你也可以把piper/目录下任意其他.onnx音色填进去，实现"声音换装"。

🎨进阶玩法：项目本身是一张"白纸"。sounds/目录下的问候音、思考音、确认音（sounds/ack_sounds/）都可以放入自己的.wav文件，程序每次会随机挑一个播放（见 agent.py），配合faces/里的表情动画，你就能塑造出一个完整的原创角色。


四、采样率变声坑：完整排查清单

如果你换装后 BMO 的声音听起来异常低沉、缓慢，甚至有点"恶魔附体"，先别慌——这几乎一定不是 Piper 安装问题，而是采样率（Sample Rate）失配。按下面顺序逐项排查即可。

坑 1：模型采样率与播放采样率不匹配（最常见）

默认情况下，agent.py 期望 "medium" 质量模型，以PIPER_RATE = 22050播放音频。如果你的模型实际训练采样率是 48000 或 16000，按 22050 播放就会把音频拉伸/压缩，音调被严重改变。

修复步骤（最快配置方法）：

1. 打开模型配置文件（如voices/bmo-custom.onnx.json），找到"sample_rate"字段，记下数值（22050 / 16000 / 48000）；
2. 打开 agent.py，找到PIPER_RATE = 22050这一行；
3. 把数字改成与 json 中sample_rate一致的值；
4. 保存并重启智能体。

坑 2：length_scale 偏大导致语速被拉长

如果采样率完全一致，问题可能出在模型的"内部节奏"上：

1. 打开voices/bmo-custom.onnx.json，进入"inference"配置块；
2. 找到"length_scale"参数——Piper 用它控制语速；
3. 如果该值明显高于1.0，语音会被整体拉长，BMO 听起来像"僵尸"。把它调低、靠近1.0即可恢复正常语速。

坑 3：麦克风采样率自动检测不生效

输出端之外的输入端也有采样率逻辑：agent.py 的choose_input_samplerate()会按 48000 → 44100 → 32000 → 16000 的顺序探测麦克风支持的采样率并自动重采样，防止 ALSA 报错。如果唤醒词检测不稳定，可在 config.json 中用input_sample_rate手动指定（示例配置中设为 44100）。


常见误判：退出时的 ALSA 报错是正常的

按 Ctrl+C 退出时看到Expression 'alsa_snd_pcm_mmap_begin' failed，属于正常现象——只是音频流在采样中途被切断，不影响功能，无需处理。

⚡ 变声问题速查清单


五、总结

be-more-agent 的声音系统只有三个关键旋钮：config.json里的voice_model（选哪个音色）、模型 json 里的sample_rate（它真实采样率）、agent.py 的PIPER_RATE（以什么速率播放）。三者对齐，BMO 就会以正常、清澈的声音跟你说话。按本文的排查清单从上到下过一遍，90% 的"变声"问题都能几分钟内解决。

🚀 完成换装后，记得把sounds/和faces/也换成你自己的素材，打造独一无二的树莓派桌面伙伴！