hutool.extra.tts

TTS 文字转语音工具类，基于 edge_tts。

提供两个工具类：

Module Contents

Classes

TtsVoice

常用语音列表（基于 Microsoft Edge TTS）。

TtsUtil

文字转语音工具（同步版），基于 Microsoft Edge TTS 服务。

AsyncTtsUtil

文字转语音工具（异步版），基于 Microsoft Edge TTS 服务。

Functions

_check_edge_tts

检查 edge_tts 是否可用。

_resolve_voice

将语音参数解析为 short_name 字符串。

_filter_voices

按条件过滤语音列表。

Data

logger

_HAS_EDGE_TTS

API

hutool.extra.tts.logger = 'getLogger(...)'
hutool.extra.tts._HAS_EDGE_TTS = False
class hutool.extra.tts.TtsVoice(short_name: str, gender: str, locale: str)

Bases: enum.Enum

常用语音列表（基于 Microsoft Edge TTS）。

每个成员的值为 (short_name, gender, locale) 三元组。

Initialization

XIAO_XIAO = ('zh-CN-XiaoxiaoNeural', 'Female', 'zh-CN')
XIAO_YI = ('zh-CN-XiaoyiNeural', 'Female', 'zh-CN')
YUN_JIAN = ('zh-CN-YunjianNeural', 'Male', 'zh-CN')
YUN_XI = ('zh-CN-YunxiNeural', 'Male', 'zh-CN')
YUN_XIA = ('zh-CN-YunxiaNeural', 'Male', 'zh-CN')
YUN_YANG = ('zh-CN-YunyangNeural', 'Male', 'zh-CN')
XIAO_BEI = ('zh-CN-liaoning-XiaobeiNeural', 'Female', 'zh-CN-liaoning')
XIAO_NI = ('zh-CN-shaanxi-XiaoniNeural', 'Female', 'zh-CN-shaanxi')
HIU_GAAI = ('zh-HK-HiuGaaiNeural', 'Female', 'zh-HK')
HIU_MAAN = ('zh-HK-HiuMaanNeural', 'Female', 'zh-HK')
WAN_LUNG = ('zh-HK-WanLungNeural', 'Male', 'zh-HK')
HSIAO_CHEN = ('zh-TW-HsiaoChenNeural', 'Female', 'zh-TW')
YUN_JHE = ('zh-TW-YunJheNeural', 'Male', 'zh-TW')
HSIAO_YU = ('zh-TW-HsiaoYuNeural', 'Female', 'zh-TW')
EN_EMMA = ('en-US-EmmaMultilingualNeural', 'Female', 'en-US')
EN_ANDREW = ('en-US-AndrewNeural', 'Male', 'en-US')
EN_BRIAN = ('en-US-BrianNeural', 'Male', 'en-US')
EN_JENNY = ('en-US-JennyNeural', 'Female', 'en-US')
EN_GUY = ('en-US-GuyNeural', 'Male', 'en-US')
EN_ARIA = ('en-US-AriaNeural', 'Female', 'en-US')
JA_NANAMI = ('ja-JP-NanamiNeural', 'Female', 'ja-JP')
JA_KEITA = ('ja-JP-KeitaNeural', 'Male', 'ja-JP')
KO_SUNHI = ('ko-KR-SunHiNeural', 'Female', 'ko-KR')
KO_INJUN = ('ko-KR-InJoonNeural', 'Male', 'ko-KR')
class hutool.extra.tts.TtsUtil

文字转语音工具（同步版），基于 Microsoft Edge TTS 服务。

所有方法均为静态方法，阻塞式调用。

需要安装：pip install edge_tts

异步版本请使用 AsyncTtsUtil，方法名完全一致。

static list_voices() → List[Dict[str, Any]]

列出所有可用语音。

返回:

语音列表，每个元素为包含 ShortName、Gender、Locale 等字段的字典

static find_voices(*, locale: Optional[str] = None, gender: Optional[str] = None, language: Optional[str] = None) → List[Dict[str, Any]]

按条件查找语音。

参数:

  • locale – 地区代码（如 zh-CN、en-US）

  • gender – 性别（Male / Female）

  • language – 语言代码（如 zh、en）

返回:

匹配的语音列表

static gen_voice(text: str, output: Union[str, pathlib.Path] = 'output.mp3', voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None, subtitle_file: Optional[Union[str, pathlib.Path]] = None) → pathlib.Path

将文字转为语音并保存到文件。

参数:

  • text – 要转换的文字

  • output – 输出文件路径（默认 output.mp3）

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速（如 +20%、-10%）

  • volume – 音量（如 +50%、-20%）

  • pitch – 音调（如 +10Hz、-5Hz）

  • proxy – 代理地址（如 http://127.0.0.1:7890）

  • subtitle_file – 字幕文件路径（可选，生成 SRT 格式）

返回:

输出文件路径

static gen_voice_bytes(text: str, voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None) → bytes

将文字转为语音并返回 MP3 二进制。

参数:

  • text – 要转换的文字

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

返回:

MP3 音频二进制数据

static gen_subtitle(text: str, voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None) → str

生成文字对应的 SRT 字幕。

参数:

  • text – 要转换的文字

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

返回:

SRT 格式字幕字符串

static gen_all_voices(text: str, output_dir: Union[str, pathlib.Path] = 'data/tts', rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None) → List[pathlib.Path]

使用所有内置语音生成音频文件。

参数:

  • text – 要转换的文字

  • output_dir – 输出目录

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

返回:

生成的文件路径列表

static stream_voice(text: str, voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None)

流式获取音频数据（同步生成器）。

每次 yield 一个 MP3 音频片段（bytes）。

参数:

  • text – 要转换的文字

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

Yield:

MP3 音频片段

class hutool.extra.tts.AsyncTtsUtil

文字转语音工具（异步版），基于 Microsoft Edge TTS 服务。

所有方法均为 async 静态方法，需在协程中调用。

方法名与 TtsUtil 完全一致，仅调用方式不同：

import asyncio
from hutool import AsyncTtsUtil

asyncio.run(AsyncTtsUtil.gen_voice("你好", output="hello.mp3"))

需要安装：pip install edge_tts

async static list_voices() → List[Dict[str, Any]]

列出所有可用语音。

返回:

语音列表

async static find_voices(*, locale: Optional[str] = None, gender: Optional[str] = None, language: Optional[str] = None) → List[Dict[str, Any]]

按条件查找语音。

参数:

  • locale – 地区代码

  • gender – 性别

  • language – 语言代码

返回:

匹配的语音列表

async static gen_voice(text: str, output: Union[str, pathlib.Path] = 'output.mp3', voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None, subtitle_file: Optional[Union[str, pathlib.Path]] = None) → pathlib.Path

将文字转为语音并保存到文件。

参数:

  • text – 要转换的文字

  • output – 输出文件路径

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

  • subtitle_file – 字幕文件路径（可选）

返回:

输出文件路径

async static gen_voice_bytes(text: str, voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None) → bytes

将文字转为语音并返回 MP3 二进制。

参数:

  • text – 要转换的文字

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

返回:

MP3 音频二进制数据

async static gen_subtitle(text: str, voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None) → str

生成文字对应的 SRT 字幕。

参数:

  • text – 要转换的文字

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

返回:

SRT 格式字幕字符串

async static gen_all_voices(text: str, output_dir: Union[str, pathlib.Path] = 'data/tts', rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None) → List[pathlib.Path]

使用所有内置语音生成音频文件。

参数:

  • text – 要转换的文字

  • output_dir – 输出目录

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

返回:

生成的文件路径列表

async static stream_voice(text: str, voice: Union[str, hutool.extra.tts.TtsVoice] = TtsVoice.YUN_YANG, rate: str = '+0%', volume: str = '+0%', pitch: str = '+0Hz', proxy: Optional[str] = None)

流式获取音频数据（异步生成器）。

每次 yield 一个 MP3 音频片段（bytes）。

参数:

  • text – 要转换的文字

  • voice – 语音名称字符串或 TtsVoice 枚举

  • rate – 语速

  • volume – 音量

  • pitch – 音调

  • proxy – 代理地址

Yield:

MP3 音频片段

hutool.extra.tts._check_edge_tts() → None

检查 edge_tts 是否可用。

hutool.extra.tts._resolve_voice(voice: Union[str, hutool.extra.tts.TtsVoice]) → str

将语音参数解析为 short_name 字符串。

hutool.extra.tts._filter_voices(voices: List[Dict[str, Any]], *, locale: Optional[str] = None, gender: Optional[str] = None, language: Optional[str] = None) → List[Dict[str, Any]]

按条件过滤语音列表。