edge-tts 实战：一条命令免费生成多语言文本转语音 MP3

edge-tts 实战：一条命令免费生成多语言文本转语音 MP3

【免费下载链接】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 key，要么按字符计费，成本不好控制。edge-tts 绕开了这些问题：它直接复用 Microsoft Edge 内置的在线文本转语音服务，从 Python 或命令行就能生成 MP3 音频和 SRT 字幕，不需要 Windows，也不需要任何密钥。

用 pipx 装好 edge-tts，一条命令生成 MP3 和字幕

如果只用命令行，推荐用 pipx 安装，工具会放在隔离环境里，不占你的日常 Python 环境：

pipx install edge-tts

装完即得edge-tts和edge-playback两条命令。最小的生成组合是--text指定内容、--write-media指定落盘位置，字幕可以顺手一起写：

edge-tts --text "你好，世界！" \ --voice zh-CN-XiaoxiaoNeural \ --write-media hello.mp3 \ --write-subtitles hello.srt

跑完会在当前目录得到 hello.mp3 和一份带时间戳的字幕文件。文本较长时也可以改用--file直接从文件读入（传-表示从标准输入读取）。

不想落盘就直接听，edge-playback内部会先调用 edge-tts 合成到临时文件、播放后清理，Linux 和 macOS 上需要先装好 mpv 播放器：

edge-playback --text "欢迎使用 edge-tts" --voice en-US-AriaNeural

除了--write-media、--write-subtitles、--list-voices三个选项，其余参数都可以原样传给edge-playback。

列出全部语音，按语言或性别挑一个

不必背语音名。命令加--list-voices会打印完整清单，列里包含性别、内容类别和性格风格：

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

输出里能找到 zh-CN-XiaoxiaoNeural（女声）、zh-CN-YunyangNeural（男声）等中文语音，挑中哪个就把名字填进--voice。不传--voice时默认使用 en-US-EmmaMultilingualNeural。

写脚本时可以筛得更精确。src/edge_tts/voices.py 里的VoicesManager支持按 Language、Gender、Locale 等维度组合查询：

voices = await VoicesManager.create() picked = voices.find(Gender="Male", Language="zh")

返回的是一个列表，交给random.choice或者按业务规则挑选都可以，完整的动态选声写法见 examples/async_audio_gen_with_dynamic_voice_selection.py。

语速、音量、音调怎么微调

暴露了三个参数：rate 调语速、volume 调音量、pitch 调音调，默认都不改变（rate/volume 为+0%，pitch 为+0Hz）：

edge-tts --text "把语速放慢，声音压低" \ --voice zh-CN-YunxiNeural \ --rate=-30% --volume=+20% --pitch=-10Hz \ --write-media demo.mp3

这里有个小坑：负值必须写成--rate=-30%这种等号形式，用空格分开会被当成独立选项直接报错。

这三个值最终会填进 SSML 的 prosody 节点发给服务，对应逻辑在 src/edge_tts/communicate.py 的mkssml()函数里。

用 Python 脚本批量合成多个音频

文本一多，命令行就不够用了，这时换成 Python 接口。入口是Communicate类，同步场景用save_sync()循环即可：

import edge_tts VOICE = "zh-CN-YunyangNeural" for i, line in enumerate(read_lines("chapter.txt"), 1): edge_tts.Communicate(line, VOICE, rate="+10%").save_sync(f"ch_{i}.mp3")

这段是 examples/sync_audio_gen_with_predefined_voice.py 的略加扩写版本，注意 voice 是第二个位置参数，rate 等走关键字参数，每段依次得到 ch_1.mp3、ch_2.mp3。

规模上去后有两件事值得注意：

• 并发控制：服务端对连接数有限制，批量任务建议用asyncio.Semaphore（比如 5）包住异步的save()再并发。
• 长文本：不用手动切分。Communicate构造时已经用split_text_by_byte_length()按 4096 字节自动分段，优先在换行或空格处断开，不会截断多字节字符或&这类实体。

避坑清单：代理、进度条、报错与音质

• 合成报 NoAudioReceived：几乎都是 voice 名拼错或文本为空，先用--list-voices核对语音名。
• 进度条干扰输出：stderr 是终端时合成过程会画进度条；把输出重定向或写字幕到 stderr 时会自动隐藏，也可以手动加--no-progress。
• 网络受限制约：命令追加--proxy即可，合成和拉取语音列表都会走代理。
• 别试自定义 SSML：服务只接受 Edge 自身生成的 SSML，自定义 SSML 支持已被移除，可调项目前已全部暴露在 rate/volume/pitch 参数里。
• 音质是固定的：输出为 24kHz、48kbps 的 mono MP3，没有质量参数可调，需要更高码率得用 FFmpeg 后处理。

小结

edge-tts 把免费文本转语音最常用的三件事——单次生成、参数微调、批量脚本——都覆盖了，拿来当项目的音频生成层基本够用。往后的延伸方向有三个：用 FFmpeg 把多个 MP3 拼接成长文件并转格式；把Communicate封装成 FastAPI 服务，对外暴露一个文本转语音接口；或者按文本语气匹配不同风格的声音，让朗读更接近"情感化"效果。

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