Yoji语音体验指南:唤醒词"小优"+TTS流式播报,全离线语音对话
Yoji语音体验指南:唤醒词"小优"+TTS流式播报,全离线语音对话
Yoji 是一款有情绪的 AI 桌面伴侣,语音体验是它最接近真人的部分:说出唤醒词"小优"即可开启全离线语音对话,AI 的回复通过 TTS 流式播报边生成边朗读,全程不联网、零延迟、零成本。本指南带你快速上手 Yoji 的语音唤醒与 TTS 播报,并看懂背后的实现机制。
⚠️ 平台说明:语音唤醒与 TTS 播报都基于 macOS 系统能力(SFSpeechRecognizer / say / afplay),目前仅支持 macOS;Windows 下界面会自动隐藏语音对话入口。
一、快速上手:三步开启 Yoji 全离线语音对话
| 步骤 | 操作 | 看到什么 |
|---|---|---|
| 1️⃣ 配置模型 | 「模型」页填入 API Key 并保存 | AI 核心就绪 |
| 2️⃣ 开启语音播报 | 对话输入框右下角点击 🎵 声音图标 | 提示"语音播报已开启",AI 回复开始朗读 |
| 3️⃣ 开启语音唤醒 | 点击 🎤 麦克风图标 | 提示"语音对话已开启,说出 '小优' 即可唤醒",进入持续监听 |
开启唤醒后首次会请求 macOS 麦克风权限,允许即可。之后喊一声"小优",就能免动手连续对话了。
二、唤醒词"小优":免动手的连续语音对话流程
Yoji 的语音对话是一条清晰的状态机流水线(见 voice-dialogue.ts):
| 状态 | 含义 | 如何进入 |
|---|---|---|
idle |
未启动,麦克风关闭 | 初始状态 |
listening |
持续监听,等待唤醒词 | 点击麦克风图标 |
woken |
已唤醒,正在采集你说的话 | 识别到"小优" |
核心体验细节:
- 🗣️ 流式转文字实时显示——你一边说,输入框一边出现文字,说错了也能看到
- ✂️ 唤醒词自动剥离——"小优,帮我总结下这份文件"中"小优"后面的内容才是你的消息
- ⏱️ 2 秒静默判定——停顿 2 秒没新文字就视为说完了,自动发送(静默计时逻辑)
- 🔄 发送后自动回到监听——不用点任何按钮,连续对话
- 🔴 录音指示——正在收音时界面右侧亮起麦克风小标记,状态一目了然
为什么说是"全离线"? 语音识别用的是 macOS 原生 SFSpeechRecognizer(与 Siri 同款引擎,通过 speech.ts 在主进程注册),识别过程在设备本地完成——不联网、零延迟、零成本,识别结果也不会离开你的电脑,天然契合 Yoji 隐私优先的设计原则。
三、TTS 流式播报:边生成边朗读的实现机制
点开声音图标后,AI 的每一条回复都会被朗读。tts.ts 中的播报引擎分五步工作:
- 流式喂入:Agent 每输出一段文字就
feed进句子缓冲,不用等整条回复生成完 - 智能分句:定时器每 100ms 扫描一次,遇到
。!?或换行就切出一句(省略号也会转成句号充当分句符,见 SENTENCE_RE) - Markdown 清洗:句子级清理——加粗/斜体标记去掉、图片语法直接丢弃、链接只读文字、空白转成逗号停顿,保证念出来的是干净口语(cleanSentence)
- 音频生成 + 播放:调用 macOS 原生
say(默认 180 词/分钟)生成临时音频,再用afplay顺序播放 - 预生成队列:播上一句的同时后台提前生成下一句,句子交替衔接,句间间隙几乎消失(preGenerate)
不想听时再点一次声音图标即可——会立即杀掉正在播放的音频进程,队列里没播完的句子也全部清空,绝不多嘴。
更换音色与语速:macOS 朗读内容设置
Yoji 的 TTS 直接复用 macOS 系统朗读引擎,所以音色在系统里调:
系统设置 → 辅助功能 → 朗读内容 → 选择"系统声音"
选完立即生效,女声男声随意换,语速也能一并调整。
四、Live2D 口型同步:让 AI 真的在"说"话
Yoji 不只是"出声",虚拟形象还会跟着说话张合嘴部。联动链路非常直接:
主进程 tts.ts 起停播放 → 广播 tts:speakingChanged
→ preload 暴露 onSpeakingChanged → 形象组件 talking 状态
→ Live2D talking 动画器驱动嘴部参数
形象组件监听播报状态(Image.tsx),createTalkingAnimator 每 80~160ms 随机一个目标口型开度并平滑插值,模拟真人说话的自然节奏;播报一结束,嘴部平滑闭合。配合情绪系统里星星眼、歪头、眨眼这些动作,整段语音体验的"活人感"拉满。
Yoji 还会在主动聊天前先感知自己的情绪和天气再开口,表情、界面背景随心境变化——语音唤醒它时,它是什么心情,你一眼就能看出来。
五、常见问题 FAQ
Q1:Windows 上看不到麦克风图标? 语音唤醒依赖 macOS 原生 SFSpeechRecognizer,目前仅支持 macOS,非 macOS 平台入口自动隐藏,属正常现象。
Q2:唤醒后没反应 / 监听突然停了?
若是权限类错误(permission-denied 等),Yoji 会自动重置监听状态并提示。检查「系统设置 → 隐私与安全性 → 麦克风」中是否允许 Yoji 使用麦克风。
Q3:播报念错了符号或格式? 分句前会自动做句子级 Markdown 清洗(斜体、加粗、图片、链接标记都会处理),若仍觉得某类格式读着别扭,可以在 cleanSentence 里补充对应规则。
Q4:能改语速吗? 可以。默认语速常量在 TTS_RATE(180 词/分钟);更简单的做法是去 macOS「辅助功能 → 朗读内容」里全局调整声音语速。
Q5:会上传我的语音吗? 不会。识别在设备本地完成,TTS 音频在本地生成,整条语音链路不经过任何第三方服务。
六、相关源码与文档导航
| 模块 | 路径 | 说明 |
|---|---|---|
| 语音对话 Hook | voice-dialogue.ts | 唤醒词匹配、2 秒静默判定、状态机 |
| TTS 播报引擎 | tts.ts | 分句、清洗、预生成队列、流式播放 |
| 原生语音注册 | speech.ts | macOS SFSpeechRecognizer 接入 |
| 对话页 UI | AIChat.tsx | 麦克风/声音图标、录音指示 |
| Live2D 口型动画 | animation.ts | 说话口型、眨眼、呼吸管线 |
| Live2D 设计文档 | live2d.md | 口型/情绪/戳一戳的完整设计说明 |
从"小优,帮我看看今天的天气"到她开口回答、嘴部同步张合——Yoji 的全离线语音链路只有四步:原生离线识别 → 流式生成 → 流式朗读 → 口型联动。拿起麦克风试试,体验一下和桌面上的 AI 像真人一样说话吧 💬


