voice 是运行在 iii 平台上的本地语音技能,提供语音转文字与文字转语音能力。默认情况下音频与文本不离开本机:使用小型流式识别器产出实时文本,内置 Parakeet 或已配置的 host whisper-cli 产出准确的最终文本;也可通过配置将任一部分替换为 OpenAI 兼容端点或经 llm-router 注册的语音服务商。
用途与使用时机:用户附上或指定 WAV 录音并需要其文本时,调用 voice::transcribe;前端持续推送麦克风音频并需要实时文本时,使用 voice::dictation::*;需要把回复朗读出来时,调用 voice::speak。
主要能力与函数:voice::transcribe 将 WAV 文件(路径或 base64)转为带时间戳分段的文本。voice::dictation::start 开启听写会话,转写事件发往 output_function_id;voice::dictation::push 每次送入一个 base64 PCM 音频块(seq 递增);voice::dictation::stop 关闭会话并返回转写结果(可选择丢弃);voice::dictation::list 列出已开启会话;voice::speak 朗读文本,支持 text_format: markdown(默认,去掉 Markdown 标记、隐藏链接地址与代码块)或 plain(保留字面文本),返回 speech_id;voice::speech::prepare 做无状态的 Markdown 快照准备,返回纯文本与 max_chunk_chars,可先扣留未完成的语法,再在请求浏览器中排队播放纯文本 voice::speak 片段;voice::speak::stop 为兼容旧接口,返回 stopped: 0,浏览器音频需在本地停止;voice::models::list 列出本地模型、安装状态及各自的许可证、作者与来源(Parakeet TDT 0.6B v2 为 CC BY 4.0,复制文件时需保留署名);voice::models::download 校验和验证后安装本地模型;voice::models::remove 删除已下载模型;voice::doctor 查看后端、模型状态与已开启会话。
响应式触发器:voice::transcript 提供听写会话的 partial、final、closed 与 error 事件(可按 session_id 过滤);voice::session-started、voice::session-stopped 为会话生命周期事件;voice::model-progress 提供下载进度,每兆字节一个事件,结束时发送 done。
使用限制:听写输入为 16 kHz 单声道 16 位 PCM;voice::transcribe 接受任意采样率的 WAV,不解析其它容器格式。内置模型为英语,葡萄牙语等其它语言需设 stt.backend: whisper_cpp 并搭配多语言 GGML 模型,或使用远程后端。本地自然朗读需安装 piper-tts,在 Piper 语言过滤器中填入语言,从内置多语言目录中选择匹配语音并显式下载,再将 tts.backend 设为 piper;piper-pt-br-faber-medium 仍可用于巴西葡萄牙语。过滤操作不会下载模型或更改当前语音。tts.piper.command 是可执行文件路径而非 shell 命令,Piper 不可用时不会回退到机械音的 eSpeak。tts.piper.device 默认 auto(优先请求 NVIDIA CUDA,允许回退到 ONNX Runtime CPU,若 GPU 优先进程失败则在 CPU 上重试一次);cpu 强制使用 CPU。auto 每次尝试分配 30 秒,纯 CPU 为 60 秒;GPU 需在 Piper 自身环境中具备兼容的 onnxruntime-gpu/CUDA/cuDNN,不会自动安装驱动,doctor 仅报告策略而非验证 GPU 实际使用。
朗读行为:每个 voice::speak 后端都向调用方返回 audio_base64 与 mime;host 使用 say/espeak 以文件输出模式生成 WAV,不做服务器端播放。请求方浏览器自行播放和停止音频,不影响其它客户端。Console 中“阅读所选内容”只朗读该对话中被选中的文本;语音聊天按浏览器/会话选择启用,在回合结束前以句子/短语分块朗读实时助手文本(含可见进度,不包含思考过程或工具参数),会去重快照,结束时只刷新未读尾部,不发送消息也不保持麦克风开启,停止操作会关闭自动朗读。chat 选区使用 plain 格式,因为内容已渲染;字数上限在格式转换后生效,不修改消息,也不抓取远程链接。超过 session_idle_secs 空闲的听写会话会被 worker 关闭。