edge-tts 使用指南：免密钥语音合成实战

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

edge-tts 是一个 Python 模块，直接调用 Microsoft Edge 内置的在线文本转语音（TTS，text-to-speech）服务：不装 Edge 浏览器、不需要 Windows、不需要 API 密钥，就能把任意文本合成为带时间戳的 MP3。本文覆盖安装命令、四个调参开关、Python 同步与异步接入方式，以及高频报错的处理办法，读完即可判断它是否适合接入你的项目。

📌 项目定位：把 Edge 内置的语音服务拆出来用

它的存在逻辑很直接：微软的神经网络语音合成能力平时只通过订阅制商业 API 提供，而 Edge 浏览器自带的朗读功能走的是另一条免费通道。edge-tts 连的就是这条通道（speech.platform.bing.com 的 WebSocket 长连接），把它封装成开源的命令行工具和 Python 库。

能力覆盖两种使用方式：edge-tts/edge-playback命令，以及edge_tts模块。输出固定为 24kHz、48kbps、单声道 MP3；默认语音是 en-US-EmmaMultilingualNeural；--list-voices能拉出覆盖数十种语言与地区的长表，包括南非荷兰语（af-ZA）、阿姆哈拉语（am-ET）和阿拉伯语的多个地区变体（ar-AE、ar-BH、ar-DZ、ar-EG）。

不做的事要说清楚：自定义 SSML（Speech Synthesis Markup Language，用于精确控制停顿、重音的语音标记语言）已不支持，因为微软只接受 Edge 客户端自己生成的 SSML，项目已把该功能整体移除；也没有离线模式，断网即无法合成。

🚀 上手路径：安装 edge-tts 并生成第一条语音

安装

pip install edge-tts # Python 代码集成用 pipx install edge-tts # 只用命令行：pipx 是隔离环境的 Python 安装器

装完后运行edge-tts --version可输出版本号，当前仓库版本为 7.2.8。

最小可运行示例

edge-tts --text "Hello, world!" --write-media hello.mp3

执行后当前目录生成 hello.mp3，任意播放器可直接打开；不传--write-media时音频直接写到 stdout，方便管道给其他程序，-f/--file则从文件读取待合成文本。

查看可用资源

edge-tts --list-voices # 输出四列表格： # Name Gender ContentCategories VoicePersonalities # af-ZA-AdriNeural Female General Friendly, Positive # ar-EG-SalmaNeural Female General Friendly, Positive

从 Name 列挑一个语音名，后续通过--voice传入即可。

🎯 三个梯度场景：从单条文本到带字幕输出

第一条多语言音频：用 --voice 指定声音

问题：要把一句非默认语言文本合成音频，且要选对发音人。

edge-tts --voice ar-EG-SalmaNeural --text "مرحبا كيف حالك؟" --write-media hello_arabic.mp3

产出：hello_arabic.mp3，阿拉伯语女声 Salma 发音；换成其他语言只需替换--voice的值。

调优参数：语速、音量、音调各一个开关

问题：教学语速偏快，或者声音偏尖、想更沉稳。

edge-tts --rate=-50% --pitch=-50Hz --text "慢速低沉的讲解" --write-media slowed.mp3

负值必须写成--rate=-50%这种等号形式，空格写法--rate -50%会被当作选项名直接报错。产出：slowed.mp3，语速减半且音调降低 50Hz。

字幕流水线：一次产出音频加 SRT 时间戳

问题：视频需要句级字幕，手工打时间戳不现实。

edge-tts --text "今天我们来学习 Python 编程基础" --write-media lesson.mp3 --write-subtitles lesson.srt

产出：lesson.mp3 与 lesson.srt 两个文件；srt 由服务返回的句子边界事件自动生成时间戳，可直接导入剪辑软件或播放器。

🧩 代码层接入：save_sync 与 stream 两种姿势

轻量调用：5 行同步生成 MP3

这段同步代码与仓库 examples/ 下 sync_audio_gen_with_predefined_voice.py 示例一致：

import edge_tts TEXT = "Hello World!" VOICE = "en-GB-SoniaNeural" communicate = edge_tts.Communicate(TEXT, VOICE) communicate.save_sync("test.mp3") # 阻塞调用，直接落盘

工程化集成：流式输出边收边写

stream()异步产出 chunk，audio 是音频块，SentenceBoundary 是句子时间戳事件，适合边下载边写文件：

communicate = edge_tts.Communicate(TEXT, VOICE) submaker = edge_tts.SubMaker() with open("test.mp3", "wb") as file: async for chunk in communicate.stream(): if chunk["type"] == "audio": # 音频块直接落盘 file.write(chunk["data"]) elif chunk["type"] == "SentenceBoundary": submaker.feed(chunk) # 累积字幕时间戳 srt = submaker.get_srt()

不需要自己拼字幕时，直接await communicate.save("test.mp3")一步写文件即可。

按属性筛选语音：VoicesManager.find()

不想硬编码语音名时，可用 find() 按性别、语言、地区过滤（对应 async_audio_gen_with_dynamic_voice_selection.py 示例）：

from edge_tts import VoicesManager voices = await VoicesManager.create() candidates = voices.find(Gender="Male", Language="es") name = random.choice(candidates)["Name"] # 随机挑一个西班牙语男声 communicate = edge_tts.Communicate(TEXT, name) await communicate.save("spanish.mp3")

🛠 edge-tts 踩坑与调优：负号参数、mpv 与 4096 分块

• --rate -50%报 unrecognized arguments → 根因：argparse 把-50%当成另一个选项名 → 处理：统一写成--rate=-50%，volume、pitch 同理。
• Linux/macOS 上 edge-playback 不发声 → 根因：它依赖 mpv 命令行播放器 → 处理：先安装 mpv；只生成文件不需要播放的话，装不装都不影响 edge-tts。
• 合成 OCR 或 PDF 文本时报服务端错误 → 根因：服务不接受 0x00–0x08、0x0B–0x0C、0x0E–0x1F 区间的控制字符（OCR 文本里常见）→ 处理：库内 remove_incompatible_characters 会自动替换成空格，仍报错就先用re.sub(r"[\x00-\x08\x0b-\x0c\x0e-\x1f]", " ", text)预清洗。
• 长文本合成中途卡住 → 根因：文本按 4096 字节分块发送，receive_timeout 默认 60 秒 → 处理：按段落拆分逐段发送；大文档给 Communicate 传receive_timeout=120避免连接中途超时。
• 内网环境无法访问语音接口 → 根因：服务域名需要公网出口 → 处理：命令行加--proxy http://user:pass@host:port，模块传同名 proxy 参数。

调优参数速查：

🗂 内部结构速览：communicate.py 是唯一对外核心

CLI 参数解析在 util.py，网络与音频逻辑集中在 communicate.py。

edge-tts/ ├── src/edge_tts/ │ ├── __main__.py # 入口：调用 util.main() │ ├── communicate.py # WebSocket 连接、4096 字节分块、流解析 │ ├── voices.py # 语音列表拉取、VoicesManager 筛选 │ ├── submaker.py # 词/句边界事件转 SRT │ ├── drm.py # 请求签名（Sec-MS-GEC）生成 │ ├── constants.py # 服务地址、默认语音、请求头常量 │ └── data_classes.py # TTSConfig 参数格式校验 ├── src/edge_playback/ # 本地播放命令 edge-playback └── examples/ # 5 个同步/异步使用示例

• communicate.py：对外核心类 Communicate，负责建连、分块发送文本、按 audio 与边界事件输出 chunk，并内置 10 秒/60 秒两级超时。
• voices.py：拉取与 Edge 相同的语音列表，find() 支持按 Gender、Language、Locale 三个维度过滤。
• submaker.py：命令行的--write-subtitles由它实现，喂入边界事件后调 get_srt() 得到完整字幕。

⚠️ 局限与适用边界：在线依赖、SSML 与音质差异

• 完全依赖微软在线服务，无离线模式：断网即无法合成 → 在业务里加本地引擎（如 piper 或 espeak）兜底，或提前缓存已生成的 MP3。
• 服务端策略可能随时收紧：自定义 SSML 已被拒绝过一次，通道本身也没有服务等级承诺 → 不要规划自写 SSML 的功能，只用库暴露的 rate、volume、pitch、boundary 参数。
• 语音列表没有质量评级，不同语言质量参差 → 选型时用--list-voices加--write-media对 2～3 个候选各生成一小段试听，再为项目锁定一个语音。

从 examples/ 目录的 5 个脚本入手，重点看 stream() 的 chunk 结构与 SubMaker.feed 的消费方式，就能搭出自己的音频加字幕管线。

【免费下载链接】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