edge-tts 实战：免费在线语音合成，把文本变成 MP3 和 SRT 字幕
【免费下载链接】edge-ttsUse Microsoft Edge's online text-to-speech service from Python WITHOUT needing Microsoft Edge项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts
给课件录音、做有声书时，商业 TTS 接口往往要先注册账号、申请密钥、按量计费。edge-tts 直接调用 Microsoft Edge 内置的在线语音合成服务，一行命令把文本转成 MP3 音频和 SRT 字幕：不要 API key、不要账号，只要装好 Python 就能用，也不依赖 Windows 或 Edge 浏览器本身。
edge-tts 安装步骤与验证
先安装：
pip install edge-tts如果只用edge-tts、edge-playback两个命令而不用 Python 模块，官方 README 建议改用 pipx 隔离安装：
pipx install edge-tts然后跑第一条命令：
edge-tts --text "Hello, world!" --write-media hello.mp3 --write-subtitles hello.srt成功的标志有三点：
- 当前目录多出
hello.mp3（24kHz 单声道、48kbps 恒定码率 MP3）和hello.srt（带时间戳的字幕）两个文件； - 运行过程中 stderr 会显示一条进度条，例如
42%|██████... | 1.5MB 00:03<00:04，按已收到音频的比例推进； edge-tts --version能打印版本，例如edge-tts 7.3.1。
一个默认行为值得留意：不写--write-media时音频直接输出到标准输出，方便接管道；在交互终端里这样做，命令会先警告并等你按回车确认，Ctrl+C 可取消。
edge-tts 能力总览
| 能力 | 适用场景 | 触发方式 |
|---|---|---|
| 文本合成 MP3 | 单条配音、批量产出音频 | edge-tts --text "..." --write-media out.mp3 |
| 同步生成 SRT 字幕 | 课件视频、有声书加字幕 | 上一命令加--write-subtitles out.srt |
| 列出全部声音 | 挑选 voice 名称 | edge-tts --list-voices |
| 合成完立即播放 | 试听声音 | edge-playback --text "..." |
| 从文件或 stdin 读文本 | 长讲义转有声、流水线接入 | edge-tts --file book.txt或--file - |
| 调语速 / 音量 / 音调 | 课程慢速朗读、降音 | --rate、--volume、--pitch |
| Python 合成 API | 写进自己的程序 | edge_tts.Communicate |
| 声音按属性筛选 | 条件或随机选音 | VoicesManager |
edge-tts 参数速查
| 参数 | 作用 | 取值示例 | 默认值 |
|---|---|---|---|
-t/--text | 要合成的文本 | "你好" | 必填，与--file二选一 |
-f/--file | 从文件读文本，-表示 stdin | book.txt | 无 |
-v/--voice | 声音名，用--list-voices查 | ar-EG-SalmaNeural | en-US-EmmaMultilingualNeural |
--rate | 语速 | +20%、-50% | +0% |
--volume | 音量 | -10% | +0% |
--pitch | 音调 | -20Hz | +0Hz |
--write-media | 音频写入文件 | hello.mp3 | 无，音频走 stdout |
--write-subtitles | SRT 写入文件，-表示输出到 stderr | hello.srt | 无 |
--list-voices | 列出所有声音后退出 | 无值 | — |
--proxy | TTS 与语音列表请求的代理 | http://127.0.0.1:7890 | 无 |
--no-progress | 隐藏进度条 | 无值 | stderr 为终端时自动显示 |
--list-voices输出 Name、Gender、ContentCategories、VoicePersonalities 四列表格，声音名称以实际输出为准。
典型场景实战
长讲义读成有声书
目标：讲义文本文件直接变 MP3 + SRT，不做任何预处理。
操作：
edge-tts --file lecture.txt --write-media lecture.mp3 --write-subtitles lecture.srt产出：一对同目录文件。长文本内部按 4096 字节切段发送，切分点优先落换行、其次空格，且不会截断多字节 UTF-8 字符，中文长文不会切出乱码；字幕时间戳按实际收到的音频字节重新校正，长音频也不会越滚越漂。切分逻辑在 src/edge_tts/communicate.py。
挑声音再试听
目标：不凭记忆猜声音名，先查后定。
操作：
edge-tts --list-voices edge-playback --voice <声音名> --text "试一句"产出：试听满意的声音名，正式生成时传同一个--voice。Windows 下 edge-playback 开箱即用；其他平台需要先装mpv命令行播放器。edge-tts 的参数（除--write-media、--write-subtitles、--list-voices）在 edge-playback 下同样可用。
管道传文本
目标：上游命令的输出不落中间文件，直接进语音合成。
操作：
cat notes.txt | edge-tts --file - --write-media notes.mp3产出：notes.mp3。--file -表示从 stdin 读文本。
接入 edge-tts 到自己的代码
最短可运行示例：
import edge_tts communicate = edge_tts.Communicate("Hello World!", "en-GB-SoniaNeural") communicate.save_sync("test.mp3")同步与异步的对应关系：
save_sync阻塞到文件写完，适合普通脚本；asyncio 程序里用await communicate.save(...)，可顺带写一份边界元数据文件；- 要逐块处理（实时字幕、边合成边写）时，遍历
communicate.stream()，同步场景用等价的stream_sync()； - 构造参数除 voice、rate、volume、pitch 外，还有
boundary（词边界或句边界，默认句边界）、proxy，以及connect_timeout、receive_timeout（默认 10 秒与 60 秒）。
仓库自带六个完整脚本，覆盖同步/异步、生成与流式两种模式，参考 examples/。
edge-tts 避坑记录
- 现象：
--rate -50%直接报错。原因：以减号开头的值被命令行解析成新选项。解法：用等号形式--rate=-50%，--volume、--pitch同理。 - 现象：合成中文文本却用英文口音朗读。原因：默认声音是
en-US-EmmaMultilingualNeural。解法：显式传--voice，名称从--list-voices输出里选。 - 现象：脚本里重定向后看不到进度条。原因：进度条只在 stderr 是终端时显示，
--write-subtitles -和--no-progress也会关闭它。解法：属设计行为，需要进度条就在终端里直接运行。 - 现象：Linux / macOS 上跑 edge-playback 提示 mpv 未安装。原因：非 Windows 平台的播放交给 mpv。解法：安装 mpv；Windows 无此要求。
- 现象：想自己拼 SSML 微调参数，发现入口没了。原因：服务端只接受 Edge 自己生成的 SSML，自定义 SSML 支持已移除。解法：语速、音量、音调直接用
--rate、--volume、--pitch三个参数覆盖。
源码与文档深入索引
- 项目文档：README.md
- 使用示例脚本：examples/
- 合成核心（长文本切分、SSML 组装、WebSocket 流）：src/edge_tts/communicate.py
- 声音列表与属性筛选：src/edge_tts/voices.py
- SRT 字幕生成：src/edge_tts/submaker.py
- 命令行入口与参数解析：src/edge_tts/util.py
- 播放模块：src/edge_playback/
- 默认声音与音频格式常量：src/edge_tts/constants.py
下一步
- 跑一次
edge-tts --list-voices，按 ContentCategories 和 Gender 两列筛出候选； - 用
edge-playback --voice <声音名> --text "..."试听定稿； - 满意后用
--write-media加--write-subtitles产出第一对音频与字幕文件。
【免费下载链接】edge-ttsUse Microsoft Edge's online text-to-speech service from Python WITHOUT needing Microsoft Edge项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
