企业官网建设流程全解析

3 条命令生成语音：edge-tts 文本转语音从安装到出结果

【免费下载链接】edge-ttsUse Microsoft Edge's online text-to-speech service from Python WITHOUT needing Microsoft Edge or Windows or an API key项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts

给视频加旁白、给电子书生成朗读版本，通常要接商业语音合成 API：申请密钥、按字数计费、还要担心限流。edge-tts 是一个直接调用 Microsoft Edge 在线文本转语音服务的 Python 工具，不需要 Edge 浏览器、不需要 Windows、不需要 API key，一条命令就能产出带字幕的语音文件。

快速上手：从 0 到跑通

最常用的安装方式是pip install edge-tts，如果只打算用命令行工具，用pipx install edge-tts也可以。最短路径如下：

pip install edge-tts edge-tts --text "你好，这是 Edge-TTS 语音" --write-media hello.mp3

运行后当前目录会出现 hello.mp3，终端没有其他输出，用播放器打开即可听到默认语音把文字念出来，这就是最小可验证结果。

核心能力拆解

语音列表查询命令

服务内置了几十种语言方言的神经网络语音，列表命令会打印每种语音的名称、性别与风格：

edge-tts --list-voices | grep "zh-"

多语言产品选型时先跑一遍这条命令，把看中的名称直接抄进 --voice 参数。

Python 同步调用写法

核心入口是Communicate类，异步接口适合放进事件循环，save_sync适合普通脚本：

import asyncio import edge_tts text = "你好，这是一次测试。" voice = "zh-CN-XiaoxiaoNeural" async def main(): communicate = edge_tts.Communicate(text, voice) await communicate.save("output.mp3") asyncio.run(main())

需要批量或并发处理大量文本时，用这个异步写法，并发度由自己控制。

按属性筛选语音

VoicesManager.find支持按语言、地区、性别等属性过滤可用语音：

from edge_tts import VoicesManager async def main(): manager = await VoicesManager.create() # 挑出西班牙语男声 matches = manager.find(Gender="Male", Language="es") print(matches[0]["Name"])

适合"每章随机分配一个配音"或按地区自动选声音的场景。

参数与自定义

对最终听感影响最大的三个参数是语音、语速和音调。注意负数取值必须写成--rate=-50%的形式，否则 shell 会把负值误判成新的选项：

组合调参的完整命令：

edge-tts --voice zh-CN-YunxiNeural --rate=-10% --pitch=-5Hz \ --text "这是一个稍慢速的示例" --write-media demo.mp3

一个能直接抄的完整示例

下面的脚本按章节批量生成旁白 mp3，文件间并发执行，缩短总等待时间：

import asyncio import edge_tts # 每章的旁白文本，替换成自己的内容 TEXTS = [ "第一章：项目介绍", "第二章：环境准备", "第三章：运行第一个示例", ] VOICE = "zh-CN-XiaoxiaoNeural" async def save_one(index: int, text: str) -> None: # rate 直接传给构造器，统一放慢语速 communicate = edge_tts.Communicate(text, VOICE, rate="-10%") await communicate.save(f"chapter_{index:02d}.mp3") async def main() -> None: # 多个文件并发处理，批量生成更快 await asyncio.gather(*(save_one(i, t) for i, t in enumerate(TEXTS))) if __name__ == "__main__": asyncio.run(main())

改造时只需替换TEXTS列表和VOICE变量。需要同时产出字幕的话，参考示例文件examples/async_audio_streaming_with_predefined_voice_and_subtitles.py里用SubMaker处理边界事件的写法。

排错与常见坑

负参数不生效→ 命令行把-50%当成了新选项 → 改用--rate=-50%、--pitch=-10Hz的等号写法。

输出文件为空或 NoAudioReceived→ 服务端偶发异常，本工具不自动重试 → 包一层重试循环，或换一个语音再试。

edge-playback 无法播放→ Linux 与 macOS 上依赖 mpv 播放器 → 先安装 mpv，Windows 上则不需要。

请求超时或 403 错误→ 网络环境问题 → 检查外网连通性，或加--proxy参数指定代理。

edge-tts 适合做个人项目、内部工具和不需要为 API 付费的批量语音生产；不适合对可用性有 SLA 要求的商业产品，因为服务端点是 Edge 的内部接口，稳定性没有保障。下一步建议跑edge-tts --list-voices，挑一个顺耳的语音开始动手。

【免费下载链接】edge-ttsUse Microsoft Edge's online text-to-speech service from Python WITHOUT needing Microsoft Edge or Windows or an API key项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts