Persian-IPA-to-Speech-F5 是一个基于 F5-TTS 的波斯语 TTS（Text-To-Speech）Python 库，输入 IPA 音标即可生成波斯语语音，并提供波斯语文本转 IPA 的可选前端。本文将带你完成一键安装、FFmpeg 配置与 CUDA 环境设置，10 分钟内跑通第一个波斯语合成示例。

Persian-IPA-to-Speech-F5 是什么？

这个项目封装了 KiaBush/Persian-IPA-to-Speech-F5 模型检查点，核心能力有 3 个：

• IPA 转语音：输入 IPA 音标字符串 + 一段参考音频，输出 WAV 语音文件；
• 波斯语文本转 IPA：可选前端基于 ByT5 模型，把波斯语普通文本先转成 IPA，再送入 TTS；
• CLI 命令：安装后自带persian-ipa-to-speech-f5命令行工具，不用写代码也能合成。

它会自动下载模型权重、保留原始 Unicode IPA、并隐藏上游 F5-TTS API 的兼容性细节，对新手非常友好。

核心源码位置：

一键安装：pip install 三步走

第 1 步：确认 Python 版本（需要 3.10 及以上，见 pyproject.toml 中的requires-python配置）：

python --version

第 2 步：安装 PyTorch（GPU 用户请先完成下一节的 CUDA 配置）。

第 3 步：安装 Persian-IPA-to-Speech-F5 本体：

pip install persian-ipa-to-speech-f5

这条命令会自动带上f5-tts和huggingface-hub两个核心依赖（版本约束定义在 pyproject.toml 的dependencies段）。

如果本地有仓库源码，也可以先克隆再安装：

git clone https://gitcode.com/gh_mirrors/pe/Persian-IPA-to-Speech-F5 pip install persian-ipa-to-speech-f5

FFmpeg 配置：三种系统的安装方法

项目运行强依赖 FFmpeg，安装前可用以下命令检测系统是否已有：

ffmpeg -version

若提示找不到命令，按系统选择对应安装方式：

• Linux（Ubuntu/Debian）：

sudo apt update && sudo apt install ffmpeg

• macOS（Homebrew）：

brew install ffmpeg

• Windows（Chocolatey）：

choco install ffmpeg

安装完成后重新打开终端，再次执行ffmpeg -version，能正常输出版本号即配置成功。

CUDA 配置指南：GPU 加速的最快路径

模型推理默认优先使用 GPU，但必须先安装与你的 CUDA 版本匹配的 PyTorch，再安装本包（README 明确强调了这一顺序）。

第 1 步：确认本机是否支持 CUDA：

nvidia-smi

命令能输出现卡驱动与 CUDA 版本说明环境可用；无独立显卡的机器请跳过本节，直接使用 CPU。

第 2 步：按官方 CUDA 版本安装对应 PyTorch：

# CUDA 12.x 示例（请以 nvidia-smi 显示的版本为准） pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

第 3 步：验证 GPU 是否被 PyTorch 识别：

python -c "import torch; print(torch.cuda.is_available())"

输出True即可用 GPU 推理。

💡 小技巧：PersianIPAToSpeechF5(device=...)的device参数不传时会自动选择设备；手动指定时 GPU 填cuda，CPU 填cpu，逻辑参考 model.py 中的初始化实现。

第一次波斯语语音合成：从命令到结果

安装完成后，准备一段参考音频（如reference.wav）及其精确的 IPA 转写，即可开始合成。

方式一：使用 CLI 命令（最简单）

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

已拿到 IPA 的用户可以把--text换成--ipa，直接跳过文本转 IPA 环节（参数定义见 cli.py）。

方式二：Python API（更灵活）

from persian_ipa_to_speech_f5 import PersianIPAToSpeechF5, PersianTextToIPA ipa = PersianTextToIPA(device="cpu").convert("گل رز واقعاً زیباست.") tts = PersianIPAToSpeechF5(device="cuda") tts.synthesize( ipa, reference_audio="reference.wav", reference_ipa="<exact IPA transcription of the reference audio>", output="outputs/result.wav", )

两个注意点：

• reference_ipa必须精确转写参考音频，并遵循该检查点的 IPA 规范；
• 人名、数字、缩略词和方言输入可能有多种读法，正式使用前建议人工复核生成的 IPA。

首次运行时，model.py 会通过huggingface_hub自动下载model.safetensors与vocab.txt，请保持网络畅通。

常见问题排查清单

许可说明（重要）

• Python 包源码采用Apache-2.0协议，可自由使用；
• 模型权重派生自 F5-TTS v1 Base，单独采用CC-BY-NC-4.0协议，限非商业用途，商用场景请务必注意（详见 NOTICE 与 README.md）。

按以上步骤完成 Persian-IPA-to-Speech-F5 的安装与配置后，你就拥有了一个可运行的波斯语 TTS 工具链：CLI 快速出结果，Python API 深度定制。快去合成你的第一段波斯语语音吧 🎙️