Persian-IPA-to-Speech-F5 是一个基于 F5-TTS 的波斯语语音合成工具，一条 pip 命令即可安装，通过命令行就能把波斯语 IPA 或波斯语文本转成自然语音。本文用 10 个终端实战示例，带你完成从单句合成到批量生成的全部操作，零代码基础也能上手。

30秒上手：安装 Persian 语音合成工具

准备只需三步：

1. 安装命令行工具：

pip install persian-ipa-to-speech-f5

2. 确认系统已安装 FFmpeg（推理过程依赖它）：

ffmpeg -version

3. 准备一段参考音频（如reference.wav），并写好它的 IPA 转写。模型会在首次使用时自动下载，无需手动操作。

💡 想要 GPU 加速？先安装与 CUDA 版本匹配的 PyTorch，再安装本工具即可。

参数速查表：看懂命令行 9 个开关

所有参数定义见 cli.py：

10 个终端实战示例

示例1：首次运行——IPA 直接合成语音

persian-ipa-to-speech-f5 --ipa "sælɒːm, xoːbiː?" \ --reference-audio reference.wav \ --reference-ipa "<参考音频的IPA>" \ --output outputs/result.wav

首次运行会自动下载模型文件（见 model.py），完成后终端打印Saved: outputs/result.wav。

示例2：波斯语原文合成——用 --text 跳过 IPA

不会手写 IPA？直接传波斯语文本，工具会自动调用 ByT5 前端转成 IPA（g2p.py），并把转换结果打印到终端，方便核对发音：

persian-ipa-to-speech-f5 --text "گل رز واقعاً زیباست." \ --reference-audio reference.wav \ --reference-ipa "<参考音频的IPA>" \ --output outputs/result.wav

示例3：GPU 加速——大任务用 --device cuda

persian-ipa-to-speech-f5 --ipa "bærɒm" --device cuda \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>"

省略--output时，结果会输出到默认的outputs/output.wav。

示例4：语速控制——--speed 适配学习场景

• 语言学习：--speed 0.8放慢 20%
• 快速试听：--speed 1.5加速预览长文本

persian-ipa-to-speech-f5 --ipa "sælɒm" --speed 0.8 \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>" \ --output outputs/slow.wav

示例5：固定随机种子——合成结果可复现

对比不同参数对音色的影响时，用--seed锁定随机性，保证 A/B 测试公平：

persian-ipa-to-speech-f5 --ipa "xoːbiː?" --seed 42 \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>"

示例6：调整采样步数——速度优先用 --nfe-step

步数越少出稿越快（质量略有取舍），默认 32 步是均衡点：

persian-ipa-to-speech-f5 --ipa "sælɒm" --nfe-step 16 \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>"

示例7：for 循环批量生成——一句话一条音频

i=1 for ipa in "sælɒːm" "xoːbiː?" "bærɒm"; do persian-ipa-to-speech-f5 --ipa "$ipa" --seed 42 \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>" \ --output "outputs/tts_$i.wav" i=$((i+1)) done

3 条 IPA，产出 3 个 WAV，全部落在outputs/目录。

示例8：读文件批量合成——逐行处理 IPA 清单

把每行一条 IPA 的清单存为ipa_list.txt，用while read逐行合成：

n=1 while IFS= read -r line; do persian-ipa-to-speech-f5 --ipa "$line" \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>" \ --output "outputs/line_${n}.wav" n=$((n+1)) done < ipa_list.txt

示例9：设备分离——g2p 走 CPU，TTS 上 GPU

--text模式下会同时加载「文本转 IPA」和「IPA 转语音」两个模型，可分别指定设备，对小显存机器尤其友好：

persian-ipa-to-speech-f5 --text "گل رز واقعاً زیباست." \ --g2p-device cpu --device cuda \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>"

示例10：结构化输出——自动创建多级目录

--output指向的父目录不存在时会被自动创建（model.py），按项目组织批量音频很方便：

persian-ipa-to-speech-f5 --text "گل رز واقعاً زیباست." \ --reference-audio reference.wav --reference-ipa "<参考音频的IPA>" \ --output episodes/01/hello.wav

常见问题排查

⚠️ 参考 IPA 必须与参考音频内容严格对应，并遵循模型检查点的 IPA 惯例，否则音色克隆效果会打折扣。

项目结构与延伸阅读

• 命令行入口：cli.py
• 模型下载与合成：model.py
• 波斯语→IPA 前端：g2p.py
• 公开 API：init.py
• 包配置与入口命令：pyproject.toml
• 使用说明：README.md

📌 许可提醒：源码采用 Apache-2.0；模型权重基于 CC-BY-NC-4.0，仅限非商业用途，商用前请阅读 README.md 的 Licenses 部分。