将小米TTS封装为OpenAI风格API：实现离线高质量语音合成

1. 项目概述从“小爱同学”到通用语音合成最近在折腾智能家居和语音交互项目时我遇到了一个挺有意思的需求想把小米设备上那个熟悉的“小爱同学”语音集成到我自己的应用里。你可能也注意到了像“小爱同学”这样的语音助手其合成的声音在清晰度、自然度和情感表达上往往比市面上很多通用TTS文本转语音服务要舒服得多尤其是中文场景。但问题是这些厂商的TTS服务通常是封闭的只供自家生态使用没有公开的API。于是我动手搞了一个项目核心目标就是“破壁”——把小米设备本地运行的TTS引擎能力封装成一个标准的、类似OpenAI TTS API的HTTP服务。这样一来任何支持调用HTTP API的应用、脚本或者智能家居平台比如Home Assistant、Node-RED都能轻松调用这个高质量的语音合成服务生成“小爱同学”同款音色的音频文件。这个项目本质上是一个协议转换与能力封装的中间件。它不生产语音它只是小米TTS引擎的“搬运工”和“翻译官”。对于开发者而言你不再需要去逆向分析复杂的设备间通信协议或者处理繁琐的音频流你只需要像调用OpenAI的接口一样发送一段文本就能收到一个MP3文件。这对于需要个性化、高质量中文语音输出的DIY项目、内容创作辅助工具或者希望统一语音服务接口的开发者来说是一个非常实用的解决方案。2. 核心思路与技术选型解析2.1 为什么选择小米设备作为TTS源市面上TTS方案很多有在线的如Azure、Google、阿里云也有离线的如VITS、Edge-TTS。选择小米设备主要是基于以下几个实际考量音质与本地化优势小米的TTS引擎针对中文进行了深度优化特别是在轻声、儿化音和语调的自然度上表现优于许多开源方案。它的声音已经经过了海量用户的实际验证接受度高。零成本与易得性几乎每个玩智能家居的朋友手边都可能有一台闲置的小米音箱如小爱音箱Play、Pro等或者一部小米/Redmi手机。这些设备本身就是现成的、性能足够的“硬件服务器”无需额外购买云服务或强大的计算设备。完全的离线与隐私所有语音合成过程都在你自己的设备本地完成文本数据不会上传到任何第三方服务器对于处理敏感信息或注重隐私的场景是刚需。绕过服务端限制厂商的在线TTS API通常有调用频率、字数或商用限制。利用本地设备只要硬件撑得住理论上你可以无限次、无限制地使用。当然这个选择也带来了核心挑战如何与设备上封闭的TTS服务进行通信这需要我们深入设备系统找到触发TTS的“开关”。2.2 整体架构设计从触发到交付项目的核心思路可以概括为“监听-触发-捕获-提供”四步流水线。我画了一个简化的心智图来帮助理解[你的应用] --(HTTP请求含文本)-- [本项目API服务] | | (解析请求准备指令) V [向小米设备发送合成指令] | | (设备本地合成语音) V [监听设备音频输出] | | (录制并编码为MP3) V [你的应用] --(返回MP3文件/流)-- [API服务返回音频数据]服务层本项目运行在服务器可以是树莓派、家用NAS或云主机上的Python/Node.js应用提供RESTful API。控制层服务通过某种方式如ADB调试、局域网协议、模拟点击向小米设备发送“合成指定文本”的指令。执行层小米设备设备接收到指令后调用内置TTS引擎在系统音频通道播放合成语音。捕获层服务同时在设备或网络层面捕获这段播放的音频流。处理与响应层服务将捕获的原始音频流进行编码如转为MP3然后通过HTTP响应返回给调用方。这个架构的关键在于稳定、可靠地完成“控制”和“捕获”这两个动作。不同的设备型号、系统版本可用的方法差异很大。2.3 关键技术选型与权衡为了实现上述架构我评估并尝试了几种技术路径路径一Android调试桥ADB方案这是最直接、兼容性相对较好的方案。通过USB或网络ADB连接到设备需要开启开发者选项和USB调试。控制TTS使用adb shell am broadcast命令发送一个特定的Intent来触发系统TTS。捕获音频使用adb shell screenrecord --output-formath264 -或adb shell screencap并不适用因为它们抓的是视频或截图。更可行的是使用adb shell tinymix和adb shell tinycap等命令直接录制音频环回loopback或指定音频设备。但这条路需要root权限且不同设备音频架构不同非常复杂。优点理论上通用性强。缺点对普通用户来说开启ADB并保持连接有一定门槛音频捕获需要深度系统权限不稳定。路径二利用设备开放协议如米家APP相关协议研究小米音箱等设备与米家APP的通信发现它们使用基于TCP的自有协议。通过抓包分析可以找到触发TTS的指令包。控制TTS仿造米家APP向设备的特定端口发送构造好的协议数据包。捕获音频设备播放的音频有时会通过UDP组播流输出。可以尝试监听特定端口的UDP流来获取音频。优点无需ADB纯网络操作更优雅。缺点协议可能未公开且随版本变化逆向工程难度大稳定性存疑。路径三模拟用户操作无障碍服务/Auto.js在设备上安装一个辅助APP如用Auto.js或Tasker编写这个APP监听来自网络的HTTP请求通过内网WebServer收到请求后模拟调用系统语音助手或TTS接口的行为。控制TTSAPP调用TextToSpeech.speak()或模拟用户对小爱同学说话。捕获音频仍然面临系统音频捕获的难题。一个取巧的办法是让这个APP在触发TTS后直接读取系统生成的临时音频文件如果存在或者利用Android的AudioRecord录制内部音频需要权限。优点完全在应用层操作避免底层差异。缺点需要在目标设备上安装额外APP音频捕获的权限和可靠性问题依然存在。最终实践选择经过反复测试对于大多数拥有小米手机的场景一个相对平衡的方案是ADB控制 外部录音。即通过ADB发送Intent触发TTS然后通过在电脑端运行API服务的机器连接一个USB声卡到手机的耳机孔或者利用支持音频传输的USB连接在电脑端录制从手机输出的音频。虽然需要一根音频线但避免了复杂的系统内录稳定性最高。对于小米音箱则可能更适合探索协议控制 UDP音频流捕获的路径。注意任何对非自有设备进行自动化操作或音频捕获的行为都应确保符合设备使用条款并仅用于个人学习与合法用途。在多人共享或公共设备上实施需格外谨慎。3. 核心实现细节与实操要点3.1 API接口设计向OpenAI TTS看齐为了让使用者无缝切换我决定尽可能兼容OpenAI TTS API的接口格式。OpenAI的接口非常简单POST https://api.openai.com/v1/audio/speech Headers: Authorization: Bearer YOUR_API_KEY Body: { model: tts-1, input: 你好世界, voice: alloy, response_format: mp3, speed: 1.0 }我的服务接口也照此设计POST http://你的服务地址:端口/v1/audio/speech Body: { model: xiaomi-tts, # 固定或可指定设备类型 input: 要合成的文本内容支持中文标点。, voice: default, # 小米设备通常只有一种音色这里可作为预留参数 response_format: mp3, # 目前固定MP3 speed: 1.0 # 语速可能依赖设备TTS引擎是否支持 }关键实现点服务框架使用FastAPIPython或ExpressNode.js可以快速搭建这样的REST接口。FastAPI的自动交互式文档Swagger UI对调试非常友好。参数处理input文本需要做清洗过长文本要考虑分段小米TTS可能有单次字数限制。speed参数可能无法直接映射到设备TTS引擎一种折中方案是在服务端对生成的音频进行变速处理如使用pydub库但这会影响音质。异步处理TTS合成和音频捕获是耗时操作必须使用异步处理如asynciothreading或任务队列避免HTTP请求阻塞。接口应该立即返回一个“任务ID”然后通过WebSocket或另一个查询接口来获取结果。3.2 设备控制模块发送合成指令这是项目的核心之一。以ADB方案针对小米手机为例详细步骤和代码逻辑如下首先确保设备已通过USB连接并开启了USB调试在电脑上执行adb devices应能看到设备。触发TTS的ADB命令 Android系统有一个隐藏的Intent可以用于调试TTS。最常用的是adb shell am broadcast -a com.android.internal.util.ACTION_SPEECH --es text “你要合成的语句”但这条命令在很多定制系统上无效。更通用的方法是直接调用系统TTS服务的speak方法但这需要更复杂的adb shell am命令来启动一个带有ACTION_TTS_QUEUE_SPEECH的Activity或Service。经过大量测试一个相对稳定的方法是使用adb shell input模拟按键打开语音助手再模拟输入文本但这太笨重且不可靠。一个更可行的“黑科技”利用adb shell mediaplayer或adb shell cmd调用媒体服务。我发现某些系统版本中可以通过一个特定的URI来触发TTSadb shell am start -a android.intent.action.VIEW -d “tts://com.xiaomi.tts?text你好世界”这行命令会尝试让系统查看一个tts://协议的URI并携带文本参数。其有效性完全取决于设备厂商是否实现了这个协议。这正是项目需要适配不同机型的地方。你需要为不同型号的小米手机或音箱找到那个能触发TTS的“魔法命令”。在Python服务中我们可以这样封装import subprocess import logging class XiaomiTTSController: def __init__(self, device_serialNone): self.device_serial device_serial self.adb_cmd [adb] if device_serial: self.adb_cmd.extend([-s, device_serial]) def trigger_tts(self, text): # 对文本进行URL编码和安全处理 encoded_text subprocess.check_output([python3, -c, fimport urllib.parse; print(urllib.parse.quote({text}))]).decode().strip() # 方案1尝试广播Intent可能无效 # cmd self.adb_cmd [shell, am, broadcast, -a, com.android.internal.util.ACTION_SPEECH, --es, text, text] # 方案2尝试使用tts协议URI需要实测 tts_uri ftts://com.xiaomi.tts?text{encoded_text} cmd self.adb_cmd [shell, am, start, -a, android.intent.action.VIEW, -d, tts_uri] # 方案3备用方案模拟调用小爱同学需设备有小爱语音助手 # 先唤醒小爱模拟按下语音助手键再通过ADB输入文本这非常复杂且不稳定。 logging.info(f执行TTS命令: { .join(cmd)}) try: result subprocess.run(cmd, capture_outputTrue, textTrue, timeout10) if result.returncode 0: logging.info(TTS触发指令发送成功) return True else: logging.error(fTTS触发失败: {result.stderr}) return False except subprocess.TimeoutExpired: logging.error(ADB命令执行超时) return False实操心得命令超时处理必须为subprocess.run设置timeout防止ADB无响应卡死整个服务。错误重试网络ADB可能不稳定重要的命令需要加入重试机制。设备选择如果连接了多台设备-s参数指定设备序列号至关重要。协议探索最耗时的工作就是为你的特定设备找到有效的触发命令。可以尝试在设备上安装Activity Launcher这类APP查看系统内所有Activity和Intent Filter寻找与TTS相关的线索。3.3 音频捕获模块从设备到MP3文件触发TTS后设备开始播放语音。我们需要在播放的同时将这段音频录下来。如前所述系统内录困难我们采用“外部线路录音”方案。硬件准备一根USB声卡即插即用很便宜。一根3.5mm公对公音频线。将音频线一端插入小米手机的耳机孔如果手机有的话否则需要Type-C转3.5mm转接头另一端插入USB声卡的线路输入Line In口。USB声卡插入运行API服务的电脑。软件实现Python示例 我们使用sounddevice和soundfile库进行录音和保存。import sounddevice as sd import soundfile as sf import numpy as np import threading import time import logging class AudioCapture: def __init__(self, output_dir./audio_cache): self.output_dir output_dir self.is_recording False self.frames [] self.sample_rate 44100 # 标准采样率 self.device_index None # 需要指定USB声卡的设备索引 def list_devices(self): 列出所有音频设备用于找到USB声卡对应的索引 devices sd.query_devices() for i, dev in enumerate(devices): logging.info(f设备 {i}: {dev[name]} (输入通道: {dev[max_input_channels]})) if USB in dev[name] and dev[max_input_channels] 0: # 粗略匹配USB输入设备 self.device_index i logging.info(f疑似USB声卡输入设备索引: {i}) return devices def callback(self, indata, frames, time, status): 录音回调函数持续将数据存入列表 if status: logging.warning(f录音状态: {status}) if self.is_recording: self.frames.append(indata.copy()) def start_recording(self, duration10): 开始录音持续指定秒数 self.is_recording True self.frames [] logging.info(f开始录音预计时长{duration}秒使用设备{self.device_index}) # 打开输入流 with sd.InputStream(samplerateself.sample_rate, deviceself.device_index, channels1, callbackself.callback): # 单声道通常足够 sd.sleep(duration * 1000) # 阻塞等待录音完成 self.is_recording False logging.info(录音结束) def save_as_mp3(self, filenameoutput): 将录制的音频数据保存为MP3文件 if not self.frames: logging.warning(没有音频数据可保存) return None audio_data np.concatenate(self.frames, axis0) filepath f{self.output_dir}/{filename}_{int(time.time())}.mp3 # 注意soundfile默认不支持MP3需要libsndfile支持或转换。 # 更常见的做法是先保存为WAV再用pydub转MP3 wav_path filepath.replace(.mp3, .wav) sf.write(wav_path, audio_data, self.sample_rate) # 使用pydub转换为MP3需安装ffmpeg from pydub import AudioSegment audio AudioSegment.from_wav(wav_path) audio.export(filepath, formatmp3, bitrate128k) # 删除临时wav文件 import os os.remove(wav_path) logging.info(f音频已保存为: {filepath}) return filepath # 使用示例 capture AudioCapture() capture.list_devices() # 首次运行确认设备索引 # 假设触发TTS和开始录音是同步的 import threading record_thread threading.Thread(targetcapture.start_recording, args(8,)) # 录音8秒 record_thread.start() time.sleep(0.5) # 稍等录音启动 # 此时立即触发设备TTS controller.trigger_tts(测试语音合成) record_thread.join() # 等待录音线程结束 audio_file capture.save_as_mp3(test_tts)关键细节同步问题必须在设备开始播放语音之前启动录音并在播放结束后停止。可以通过在触发TTS命令后添加一个微小延迟如0.5秒再开始录音来应对设备响应延迟。更可靠的方法是先开始录音再触发TTS并设置一个固定的录音时长根据文本长度估算。设备索引sounddevice需要正确的输入设备索引。务必通过list_devices()函数确认你的USB声卡被识别为输入设备并记录其索引号在初始化时传入。音频格式与质量采样率44100Hz、单声道、128kbps的MP3对于语音已经足够清晰且文件体积小。资源清理录音会产生大量内存中的音频数据self.frames每次合成完成后必须及时清理防止内存泄漏。4. 服务集成与部署实战4.1 构建完整的Web API服务将控制模块和音频捕获模块整合到一个Web服务中。这里以FastAPI为例构建一个异步服务。from fastapi import FastAPI, BackgroundTasks, HTTPException from fastapi.responses import FileResponse from pydantic import BaseModel import uuid import asyncio import threading import os from your_controller_module import XiaomiTTSController from your_capture_module import AudioCapture app FastAPI(titleXiaomi TTS to API) # 全局组件生产环境应考虑更佳的资源管理 controller XiaomiTTSController(device_serial你的设备序列号) capture AudioCapture(output_dir/tmp/tts_audio) # 内存中存储任务状态生产环境应用数据库或Redis tasks {} class TTSRequest(BaseModel): model: str xiaomi-tts input: str voice: str default response_format: str mp3 speed: float 1.0 def run_tts_task(task_id: str, text: str): 后台同步任务函数执行TTS和录音 try: # 估算录音时长按中文字符数假设每秒读3-4字 duration max(5, len(text) / 3) # 最少5秒 # 启动录音线程 record_thread threading.Thread(targetcapture.start_recording, args(duration,)) record_thread.start() asyncio.sleep(0.8) # 等待录音稳定启动注意这里在非主线程中 # 触发设备TTS success controller.trigger_tts(text) if not success: tasks[task_id][status] failed tasks[task_id][error] Failed to trigger TTS on device return # 等待录音线程结束 record_thread.join() # 保存音频文件 filename ftts_{task_id} audio_path capture.save_as_mp3(filename) if audio_path and os.path.exists(audio_path): tasks[task_id][status] completed tasks[task_id][file_path] audio_path else: tasks[task_id][status] failed tasks[task_id][error] Audio file not generated except Exception as e: tasks[task_id][status] failed tasks[task_id][error] str(e) app.post(/v1/audio/speech) async def create_speech(request: TTSRequest, background_tasks: BackgroundTasks): 接收TTS请求创建后台任务 if len(request.input.strip()) 0: raise HTTPException(status_code400, detailInput text cannot be empty) if len(request.input) 500: # 设置长度限制 raise HTTPException(status_code400, detailInput text too long) task_id str(uuid.uuid4()) tasks[task_id] {status: processing, text: request.input} # 将耗时的同步任务放入后台线程池执行 background_tasks.add_task(run_tts_task, task_id, request.input) return {task_id: task_id, status: processing, message: TTS task started} app.get(/v1/audio/speech/{task_id}) async def get_speech_result(task_id: str): 查询任务结果并返回音频文件 if task_id not in tasks: raise HTTPException(status_code404, detailTask not found) task_info tasks[task_id] if task_info[status] completed: file_path task_info.get(file_path) if file_path and os.path.exists(file_path): # 返回音频文件 return FileResponse(file_path, media_typeaudio/mpeg, filenamespeech.mp3) else: raise HTTPException(status_code500, detailAudio file missing) elif task_info[status] failed: raise HTTPException(status_code500, detailfTask failed: {task_info.get(error, Unknown error)}) else: return {task_id: task_id, status: processing} # 可选清理过期音频文件的任务 app.on_event(startup) async def startup_event(): # 可以在这里初始化设备连接清理旧文件等 pass服务优化点异步处理使用BackgroundTasks将耗时的TTS合成任务丢到后台避免阻塞HTTP请求。对于更重的负载应该引入Celery或RQ这样的任务队列。任务状态管理示例中使用内存字典服务重启会丢失。生产环境必须使用Redis或数据库。文件管理生成的MP3文件需要定期清理可以在get_speech_result中发送文件后安排异步删除或者设置一个定时清理任务。错误处理与重试设备可能离线、ADB断开需要在run_tts_task中加入重试逻辑和更细致的错误分类。认证与限流对外开放的API需要添加API Key认证如使用FastAPI的Depends和请求限流如slowapi防止滥用。4.2 部署与配置指南环境准备服务器一台Linux服务器Ubuntu/Debian、树莓派甚至一台常开的旧电脑。依赖安装# Python环境 sudo apt update sudo apt install python3-pip python3-venv ffmpeg # ffmpeg为pydub所需 # ADB工具 sudo apt install android-tools-adbPython库pip install fastapi uvicorn pydub sounddevice soundfile # sounddevice系统依赖Linux sudo apt install libportaudio2硬件连接确保小米设备通过USB连接服务器并开启USB调试。将音频线按前述方式连接好。ADB设备授权 首次连接设备时需要在设备上点击“允许USB调试”。为了在无头无屏幕服务器上实现这一点可以先用有屏幕的电脑连接一次授权然后将~/.android/adbkey等文件复制到服务器上。或者使用adb kill-server和adb start-server配合adb devices查看状态。服务启动 将完整的代码保存为main.py使用uvicorn运行uvicorn main:app --host 0.0.0.0 --port 8000 --reload生产环境建议使用Gunicorn管理Uvicorn进程并用Nginx做反向代理和负载均衡。配置说明 建议使用配置文件如config.yaml或环境变量管理以下参数device_serial: ABCDEFG # adb devices 看到的序列号 audio_device_index: 2 # USB声卡索引 default_sample_rate: 44100 output_dir: /var/tts_audio max_text_length: 500在代码中读取这些配置。5. 常见问题排查与性能调优在实际搭建和运行过程中你肯定会遇到各种问题。下面是我踩过的一些坑和解决方案。5.1 设备连接与控制问题问题1adb devices列表为空或设备显示unauthorized。排查检查USB线是否完好尝试更换线缆或USB口。在设备上确认“USB调试”已开启。进入“开发者选项”连续点击MIUI版本号激活确保“USB调试”和“USB调试安全设置”已打开。如果是网络ADB检查IP和端口是否正确防火墙是否放行5555端口。设备提示“允许USB调试吗”勾选“始终允许”后确认。解决重启设备ADB服务adb kill-server adb start-server重新插拔USB线。对于网络ADB使用adb connect ip:port。问题2TTS触发命令执行成功但设备没反应。排查说明你使用的Intent或URI不对应你设备上的TTS服务。解决抓取日志在电脑上运行adb logcat | grep -i tts或adb logcat | grep -i speech然后在设备上手动进行一次语音合成如用翻译APP的朗读功能观察日志输出寻找关键Activity或Service名。尝试其他命令adb shell am start -n com.android.settings/.Settings\$TextToSpeechSettingsActivity打开TTS设置间接触发。搜索网上针对你特定MIUI版本的TTS触发方法。备用方案如果目标是小米音箱放弃ADB转向研究局域网协议。5.2 音频捕获问题问题3录音全是噪音或没声音。排查确认音频线连接正确手机耳机孔 - 音频线 - USB声卡线路输入Line In口不是麦克风Mic口。在系统音频设置中检查USB声卡的输入音量是否被静音或调至过低。在Linux上可以用alsamixer命令调整。在Python代码中确认sounddevice使用的设备索引device_index是否正确指向了USB声卡的输入通道。运行sd.query_devices()仔细核对。手机音量是否打开尝试调高媒体音量。解决使用arecord -l和aplay -l列出音频设备。用arecord -D hw:1,0 -f cd test.wav假设hw:1,0是你的USB声卡测试能否直接录制到系统播放的声音需要先播放一段音乐。确保系统声音输出是到手机扬声器或通过音频线输出。问题4录制的音频开头或结尾有截断或不同步。排查这是同步问题。录音启动、TTS触发、录音停止三个事件的时间点没对齐。解决提前开始录音在触发TTS命令前至少0.5-1秒开始录音。动态计算时长更精确的方法是触发TTS后通过ADB实时监控日志或音频系统状态检测到TTS播放开始和结束的事件再控制录音起停。但这实现复杂。一个折中方案是根据文本长度估算一个富余的时长如len(text)/2 3秒确保覆盖整个播放过程。音频后处理录制完成后使用pydub检测静音段自动裁剪掉开头和结尾的空白。例如from pydub import AudioSegment, silence audio AudioSegment.from_mp3(raw.mp3) # 检测非静音部分 nonsilent_parts silence.detect_nonsilent(audio, min_silence_len500, silence_thresh-40) if nonsilent_parts: start_ms nonsilent_parts[0][0] end_ms nonsilent_parts[-1][1] trimmed_audio audio[start_ms:end_ms] trimmed_audio.export(final.mp3, formatmp3)5.3 服务性能与稳定性问题5高并发请求下服务崩溃或响应极慢。瓶颈分析设备是单点一台小米设备同一时间只能合成一段语音。并发请求必须排队。ADB串行频繁的ADB命令可能产生冲突。资源竞争音频录制和文件IO可能成为瓶颈。优化方案任务队列必须引入任务队列如Redis RQ。所有TTS请求进入队列由单个或多个工作进程Worker顺序处理。API接口立即返回任务ID。连接池如果使用网络ADB维护一个ADB连接池避免频繁建立连接的开销。多设备负载均衡如果你有多台闲置小米设备可以构建一个设备池。服务根据设备空闲状态将任务分发到不同的设备上实现并行合成。这需要更复杂的设备状态管理和任务调度。缓存对于相同的文本请求可以直接返回之前生成的音频文件避免重复合成。使用Redis存储text_md5 - file_path的映射。问题6生成的MP3文件体积过大。优化调整音频参数。语音合成不需要CD音质。# 在保存时调整参数 audio.export(filepath, formatmp3, bitrate64k, parameters[-ar, 22050])将比特率从128k降至64k甚至32k采样率从44.1kHz降至22.05kHz或16kHz可以显著减小文件体积对语音清晰度影响有限。