mlx-audio Echo TTS基于扩散模型的快速语音克隆 TTS 实现全解【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio本文以 Echo TTS 模块文档 为主体系统讲解 mlx-audio 中 Echo TTS 的两种使用方式Python API 与 CLI、完整配置参数、扩散生成架构与推理管线。读完本文你将掌握如何加载mlx-community/echo-tts-base完成带参考音频的零样本语音克隆并理解其文本/说话人双编码器、双重 CFG 采样器、Fish S1 DAC 编解码与 PCA 潜空间压缩在源码中的具体实现。Echo TTS 是什么Echo TTS 是一个基于扩散模型Diffusion的文本转语音模型特点是快速、高保真的语音克隆只需一段参考音频即可让合成语音复刻该说话人的音色。在 TTS 模型列表 中Echo TTS 被标注为 Diffusion-based, fast voice cloning支持语言为英文EN。在 mlx-audio 中它的实现位于 mlx_audio/tts/models/echo_tts/ 目录由以下源码文件构成文件职责echo_tts.py对外Model类加载、generate()推理入口model.py核心EchoDiT扩散主干文本/说话人编码器、联合注意力sampling.pyEuler ODE 采样器一次性生成 块状生成audio.pyFish S1 DAC 编解码、PCA 潜空间压缩、静音裁剪text.py文本规范化与字节级分词config.pyModelConfig/EchoDiTConfig/SamplerConfig三层配置模块通过 mlx_audio/tts/utils.py 中的echo_tts: echo_tts映射注册进统一加载器因此可以像其他 TTS 模型一样用load()一行加载。快速上手Python API 与 CLI原始文档给出的两种用法如下均可直接复制运行。Python APIfrom mlx_audio.tts import load model load(mlx-community/echo-tts-base) result next(model.generate(Hello from Echo TTS., ref_audiospeaker.wav)) audio result.audio要点说明对照 echo_tts.py 中Model.generate的签名ref_audio支持文件路径字符串或mx.array波形数组传路径时会按模型采样率 44100 Hz 重新加载内部调用load_audio。若参考音频是立体声源码会自动取两声道均值降为单声道audio.ndim 2 and audio.shape[0] 1分支。generate()是一个生成器next(...)取出首个GenerationResult其中result.audio是mx.array波形同时result还携带samples、sample_rate、audio_duration、real_time_factorRTF、peak_memory_usage等指标方便你做性能评估。其余**kwargs会透传给采样器凡与SamplerConfig字段同名的参数如num_steps、cfg_scale_text都会被采样器识别无关参数如speed会被静默忽略。generate(streamTrue)目前会抛出NotImplementedError——Echo TTS 尚不支持流式输出这是文档之外的一个明确限制。rng_seed控制随机种子默认 0保证同参数可复现。CLIpython -m mlx_audio.tts.generate --model mlx-community/echo-tts-base \ --text Hello from Echo TTS. --ref-audio speaker.wav需要提醒的是原始 README 中该行写成了mmlx-community/echo-tts-base多了一个m属于笔误实际模型 ID 应为mlx-community/echo-tts-base与 Python API 示例一致。CLI 入口 mlx_audio/tts/generate.py 的--ref-audio参数同样支持路径或数组形式并在文件不存在时给出明确报错Reference audio file not found: ...。配置体系三层 Dataclass 与全部默认值Echo TTS 的配置集中在 config.py由ModelConfig聚合EchoDiTConfig模型结构和SamplerConfig采样行为两个子配置。完整默认值如下均可在模型仓库的config.json中按字段覆盖ModelConfig.from_dict支持dit、sampler两个嵌套字典。ModelConfig顶层参数默认值含义model_typeecho_tts模型类型标识sample_rate44100输出音频采样率CD 级高于常见 16k/24k TTSmax_text_length768文本 token 最大长度超过部分截断max_speaker_latent_length6400参考音频潜序列上限帧对应 6400 × 2048 ≈ 13.1 秒×640 的音频上限见下文audio_downsample_factor2048每帧潜向量对应的音频采样数即 44100/2048 ≈ 21.5 fps 潜帧率normalize_textTrue是否做文本规范化见下文delete_blockwise_modulesFalse是否删除块状生成专用模块以省内存见下文pca_filenamepca_state.safetensors模型目录下 PCA 状态文件名fish_codec_repojordand/fish-s1-dac-minFish S1 DAC 编解码器仓库model_pathNone可选本地权重路径EchoDiTConfig扩散主干结构参数默认值说明latent_size80潜向量维度PCA 压缩后的维度model_size/num_layers/num_heads2048/24/16DiT 主干宽度、层数、注意力头数intermediate_size5888MLP 中间维度norm_eps1e-5归一化 epsilontext_vocab_size256文本词表大小UTF-8 字节 BOStext_model_size/text_num_layers/text_num_heads/text_intermediate_size1280/14/10/3328文本编码器规模speaker_patch_size4说话人潜帧 patch 大小4 帧合并为 1 个 tokenspeaker_model_size/speaker_num_layers/speaker_num_heads/speaker_intermediate_size1280/14/10/3328说话人编码器规模timestep_embed_size512扩散时间步正弦嵌入维度adaln_rank256AdaLN 低秩条件投影秩SamplerConfig采样行为参数默认值说明num_steps40Euler ODE 步数质量/速度权衡主旋钮cfg_scale_text3.0文本条件 CFG 强度cfg_scale_speaker8.0说话人条件 CFG 强度克隆相似度主旋钮cfg_min_t/cfg_max_t0.5/1.0只在 t ∈ [0.5, 1.0] 的高噪声区间启用 CFG低噪声段只做单前向节省约一半条件推理truncation_factorNone→ 实际取0.96初始噪声截断系数防止初始 x_t 过大rescale_k/rescale_sigmaNone启用后对速度场做时间相关的 score rescalespeaker_kv_scale/speaker_kv_max_layers/speaker_kv_min_tNone/None/None说话人 KV 缓存动态缩放三件套speaker_kv_scale放大克隆强度speaker_kv_max_layers限制作用的层数speaker_kv_min_t指定在某时间步之后将缩放还原见采样器实现sequence_length640一次性生成时的潜序列长度640 × 2048 / 44100 ≈29.5 秒音频模型架构文本、说话人、潜变量三路联合注意力核心主干是 model.py 中的EchoDiT它是一个把文本条件、说话人条件、自注意力统一在同一个 Transformer 里的扩散模型。从源码结构看其组成如下1. 文本编码器TextEncoder一个 14 层、宽度 1280 的双向非因果Transformer输入是text_vocab_size256上的嵌入——即 UTF-8 字节级 token。文本分词逻辑在 text.py 中normalize_text_prompt会先把省略号、弯引号、冒号/分号统一替换并给文本加上[S1]说话人标签前缀若文本未以[、(开头且不含S1/S2标记tokenizer_encode直接对 UTF-8 字节序列编码并在开头插入 BOS tokenid0。文本状态会被逐层投影成 KV 缓存get_kv_cache_text之后每个扩散步都复用这份缓存而非重算文本编码——这是把条件计算从 O(步数 × 文本长度) 降为 O(文本长度) 的关键优化。2. 说话人编码器SpeakerEncoder与 latent 前缀编码器SpeakerEncoder与文本编码器同构14 层、1280但注意两点输入不是音频而是 Fish S1 DAC 编码再经 PCA 压缩后的说话人潜向量每speaker_patch_size4帧合并为一个 tokenin_proj将latent_size × patch_size 320维投到 1280 维且除以 6.0 做尺度校正它使用因果注意力与文本编码器的双向注意力形成对比。当delete_blockwise_modulesFalse时模型还会额外构建一个同构的latent_encoderlatent_norm用于把已生成的潜序列也编码成 KV 缓存get_kv_cache_latent。这正是块状/续写生成的基础新生成块可以看到之前所有块的潜变量。3. 联合注意力JointAttentionDiT 的 24 个TransformerBlock中注意力不再是单一自注意力而是把四类 K/V 拼接在一起做单次 SDPAxk [ 自身潜变量 K | 已生成潜前缀 K | 文本 K | 说话人 K ]自身注意力部分应用 RoPE 位置编码_apply_rotary_half只对序列前半施加旋转与 latent 位置约定配合输出乘以一个 sigmoid 门控output * mx.sigmoid(gate)属于 gated attention 设计Q/K 均带 per-head RMSNorm类似 QK-Norm增强长序列训练稳定性。时间步 t 经正弦嵌入后通过cond_module两层 MLP 3 倍投影得到条件向量再经两个LowRankAdaLN模块分别调制注意力和 MLP 子层低秩rank256下投影 SiLU 上投影生成 shift/scale/gate实现 DiT 经典的 AdaLN-Zero 条件注入且 gate 经 tanh 约束在 [-1, 1]。推理管线从文本与参考音频到波形Model.generate()的完整数据流echo_tts.py可以拆解为五步文本准备_prepare_text走规范化 → 字节分词 → 打包出text_input_ids与text_maskpad_to_maxFalse即不填充到 768实际多短多长。说话人潜向量提取若提供了ref_audio调用get_speaker_latent_and_maskaudio.py参考音频先截断到max_speaker_latent_length × 2048采样即 6400 × 2048 ≈ 13.1 秒44.1kHz 下按 640 × 2048 的块切分逐块用 Fish S1 DACencode_zq得到 1024 维潜帧再经PCA 白化降维z_q (z_q - pca_mean) pca_components.T × latent_scale把 1024 维压到 80 维——latent_size80由此而来生成逐帧speaker_mask并将总长裁剪到 4 的倍数以匹配 patch size。 若不提供参考音频则退化为全零潜向量 全零 mask即无克隆条件。扩散采样generate_latents先算好文本/说话人 KV 缓存再调用sample_euler_cfg_independent_guidancessampling.py按sequence_length默认 640 帧 ≈ 29.5 秒一次性采样若传入block_sizes如[160, 160, ...]则走块状采样器。DAC 解码ae_decode先把 80 维潜向量逆 PCA 还原为 1024 维交给 Fish S1 DACdecode_zq还原为 44.1kHz 波形。Fish S1 DAC 本身在 mlx_audio/codec/models/fish_s1_dac/ 中实现注意它是在post_load_hook里通过FishS1DAC.from_pretrained(config.fish_codec_repo)从jordand/fish-s1-dac-min仓库拉取的且加载失败时fish_ae会被置空并延迟到generate时报错——因此必须经由mlx_audio.tts.load()完整加载管线才能正常工作。尾部裁剪crop_audio_to_flattening_point用一个滑窗20 帧检测潜序列中方差小于 0.05 且均值接近 0的第一个平坦点audio.py把该点之后的波形全部裁掉。由于固定长度采样会产生尾部静音/塌缩这一步保证了输出时长贴合实际内容。采样器深解双重 CFG 与时间步门控Echo TTS 的采样器是理解其克隆强、生成快的关键。sample_euler_cfg_independent_guidances的每个时间步逻辑sampling.pyt_schedule np.linspace(1.0 * 0.999, 0.0, num_steps 1) # 从 t0.999 走到 0 x_t mx.random.normal((B, sequence_length, latent_size)) * trunc # trunc 默认 0.96 for i in range(num_steps): has_cfg cfg_min_t t cfg_max_t # 默认只有 t ∈ [0.5, 1.0] 才开 CFG if has_cfg: # 一次前向同时算 3 份条件 / 去文本 / 去说话人batch 拼接 v_pred (v_cond cfg_scale_text * (v_cond - v_uncond_text) cfg_scale_speaker* (v_cond - v_uncond_speaker)) else: v_pred model(仅条件分支) x_t x_t v_pred * (t_next - t) # Euler 步进v-prediction 形式几个值得注意的设计独立双 CFG文本与说话人各有一个 CFG 强度且无条件分支是通过把对应 mask 置零实现的text_mask_uncond/speaker_mask_uncond不依赖额外权重CFG 时间窗默认cfg_min_t0.5意味着 40 步里有大约一半步只做 1 次前向而非 3 次把 CFG 的算力开销压到约 2/3 批处理规模初始噪声截断truncation_factor0.96DEFAULT_TRUNCATION_FACTOR缩放初始高斯噪声避免极端初始值导致波形爆音Score rescale同时提供rescale_k与rescale_sigma时按 SNR ((1-t)/t)² 对速度场做_temporal_score_rescale用于抑制 CFG 过冲带来的能量漂移说话人 KV 动态缩放设置speaker_kv_scale后采样开始前把说话人 KV 缓存整体乘上该系数可限制到前speaker_kv_max_layers层当时间步跨过speaker_kv_min_t时再乘回1/scale还原。从源码结构看这是一种前段强克隆、后段保自然度的软调度用来在克隆相似度与音色伪影之间调参。块状生成latent 前缀 KV 与流式潜力sample_blockwise_euler_cfg_independent_guidancessampling.py实现了按块递进生成通过generate(text..., block_sizes[160, 160, 160], ...)指定每块潜帧数块之间拼接每块开始前把已生成潜序列经latent_encoder编码为kv_latent缓存新块注意力时可看到全部历史保证跨块韵律连贯支持continuation_latent参数续写以已有潜序列为起点继续生成是长文本/连续对话场景的潜在入口块状路径依赖latent_encoder、latent_norm及wk_latent/wv_latent投影。若你在配置里设了delete_blockwise_modulesTrue省内存调用块状生成会抛出ValueError(Blockwise generation requires latent-prefix modules...)sanitize权重时也会把latent_encoder.、latent_norm.、.wk_latent.、.wv_latent.开头的键直接丢弃echo_tts.py。文本处理的细节text.py 的规范化策略反映了模型的训练分布约定[S1]前缀默认给文本加上说话人 1 标记除非文本已显式以[、(开头或包含S1/S2即模型原生支持多说话人标记文本你可以直接写[S1] Hello. [S2] Hi.之类的内容标点替换…→...、’→、”→、→,、—→, 、换行→空格减少未见过字符对字节嵌入的扰动该流程受normalize_text配置控制设False可传入完全原始文本对应测试 mlx_audio/tts/tests/test_echo_tts.py 中对规范化与分词的覆盖。性能与限制须知采样率 44100Hz明显高于多数 16k/24k 的开源 TTS但相应地 Fish S1 DAC 解码与 24 层 DiT 的显存/算力开销也更高GenerationResult.peak_memory_usage会报告 GB 级峰值内存方便你按机型评估。单次最长约 30 秒sequence_length640帧 × 2048 / 44100 ≈ 29.5 秒。更长的文本应使用block_sizes分块生成而不是盲目调大sequence_length。参考音频最长约 13 秒超出max_speaker_latent_length6400帧的部分会被直接截断。不支持流式streamTrue明确抛NotImplementedError块状生成目前仍是整批产出。许可证README 明确说明 Echo-TTS 与 Fish S1 权重均以CC-BY-NC-SA-4.0发布非商用用途之外需另行获得模型作者授权。商用集成前务必确认这一点。小结mlx-audio 中的 Echo TTS 把扩散生成 强克隆落到了一套相当完整的工程实现上条件 KV 缓存复用避免了每步重算文本/说话人编码CFG 时间窗与独立双 CFG 强度提供了质量/速度/相似度的三向调节PCA 压缩 Fish S1 DAC 兼顾了潜空间紧凑与波形保真块状生成与 latent 前缀 KV 则为长音频铺了路。上手只需两行代码load(mlx-community/echo-tts-base)generate(text, ref_audio...)而调优空间则集中在SamplerConfig的num_steps、cfg_scale_speaker与speaker_kv_*三组参数上。相关路径索引模块文档mlx_audio/tts/models/echo_tts/README.md模型实现mlx_audio/tts/models/echo_tts/echo_tts.py、model.py、sampling.py音频/文本前端audio.py、text.py、config.pyFish S1 DAC 编解码器mlx_audio/codec/models/fish_s1_dac/统一加载与 CLImlx_audio/tts/utils.py、mlx_audio/tts/generate.py单元测试mlx_audio/tts/tests/test_echo_tts.py模型列表含语言与克隆能力标注docs/models/tts/index.md【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考