ChatTTS WebUI & API

ChatTTS WebUI & API — 本地网页界面与 API 使用指南

本指南基于 ChatTTS-ui 的英文/中文混合实现，提供一个在本地运行的网页界面来将文字合成为语音，并附带可本地调用的 API 接口。该项目源自原始的 ChatTTS，并在 0.96 版本后对部署要求进行了更新：需要先安装 ffmpeg；同时，早期的音色文件（CSV/PT）不可直接使用，需要通过新流程获取并生成音色值。以下内容将带你从快速体验到完整部署，覆盖 Windows、Linux、macOS 的打包版、源码部署、音色获取、API 使用及与第三方工具的集成等要点与步骤。

界面与核心理念

• 目标与定位

• 提供一个简单易用的本地网页界面，让用户能够将文字（包含中英文、数字、符号等混合文本）转换为自然语音。

• 同时提供 HTTP API，方便开发者在应用或脚本中调用文本转语音服务。

• 兼容中英文混合文本的处理，尽量保留标点、停顿与情感的自然表达。

• 技术要点

• 本地化部署，强调数据隐私与离线化体验。

• 依赖 ffmpeg 进行音频流处理与后处理（如编码）。

• 支持使用不同的音色（音色值、种子等参数组合）来控制音色与风格。

• 提供多平台部署方案：从打包版本到源码部署，覆盖主流操作系统和容器化部署方式。

界面预览

• 界面预览图展示了文字、数字、符号混合文本的合成效果，以及与音色、发声参数的交互界面。该截图直观呈现了网页界面的交互区域、文本输入框、音色选择与控制符号混合等场景。界面示例图片链接如下：
• 界面预览图: https://github.com/jianchang512/ChatTTS-ui/assets/3378335/669876cf-5061-4d7d-86c5-3333d0882ee8
• 附注：如果你需要在文章中展示更多画面，可参考上述图片进行插入，以帮助读者理解界面布局与操作流程。

快速开始与部署路径

以下内容按照不同平台与部署方式整理，帮助你快速从零开始体验 ChatTTS。

1) Windows 预打包版（最简捷体验）

• 下载与启动
• 从项目的 Releases 页下载打包好的压缩包，解压后双击 app.exe 即可使用。
• 注意：某些安全软件可能误报，请在需要时退出或使用源码部署作为替代。
• 如果你拥有英伟达显卡且显存大于 4GB，且安装了 CUDA 11.8+，将自动启用 GPU 加速以提升合成速度。
• 音色与模型
• 初次使用时，可能需要手动下载并放置模型、音色数据到指定目录，参与后续合成流程。
• 音色获取与说明
• 由于 0.96 版本后音色获取方式发生变化，请参阅“音色获取”章节执行转换流程，以获得可用的音色文件。

2) 手动下载模型（适用于多场景）

• 下载来源
• GitHub Releases 提供 all-models.7z，解压后可看到 asset 文件夹，里面含有若干 pt 文件。
• 也可通过百度网盘下载（链接在原文中提供）。
• 安装步骤
• 将 asset 文件夹内所有 pt 文件复制到 asset 目录，然后重启程序。
• 说明
• 该步骤用于手动把需要的模型文件放置到程序能读取的目录，确保首次启动时模型能够被加载。

3) Linux 下容器化部署

• 安装与启动

• 从代码仓克隆项目：git clone https://github.com/jianchang512/ChatTTS-ui.git chat-tts-ui

• 进入目录：cd chat-tts-ui

• 启动容器（GPU 版本）：

  • docker compose -f docker-compose.gpu.yaml up -d

• 启动容器（CPU 版本）：

  • docker compose -f docker-compose.cpu.yaml up -d

• 查看初始化日志：

  • docker compose logs -f --no-log-prefix

• 访问入口

• Web 服务默认启动在端口 9966，地址形式为 http://<部署设备IP>:9966，例如 http://127.0.0.1:9966 或 http://192.168.1.100:9966。

• 更新流程

• 获取最新代码：git checkout main; git pull origin main

• 更新镜像与服务：关闭当前服务后重新构建和启动

  • docker compose down --gpu
  • docker compose -f docker-compose.gpu.yaml up -d --build
  • docker compose -f docker-compose.cpu.yaml up -d --build

• 查看日志：docker compose logs -f --no-log-prefix

4) Linux 下源码部署

• 前置条件与环境
• 需要 Python 3.9–3.11 环境，并安装 ffmpeg。
• 根据系统包管理器安装 FFmpeg：如 yum install ffmpeg 或 apt-get install ffmpeg。
• 目录与虚拟环境
• 创建数据目录：/data/chattts
• 将仓库克隆到该目录：cd /data/chattts; git clone https://github.com/jianchang512/chatTTS-ui .
• 创建并激活虚拟环境：
  • python3 -m venv venv
  • source ./venv/bin/activate
• 依赖与安装
• 安装依赖：pip3 install -r requirements.txt
• 根据 CUDA 支持情况安装 Torch 与 Torchaudio：
  • 不使用 CUDA：pip3 install torch==2.2.0 torchaudio==2.2.0
  • 使用 CUDA（CUDA 11.8 支持，RTX 系列等）：pip3 install torch==2.2.0 torchaudio==2.2.0 --index-url https://download.pytorch.org/whl/cu118
• 若使用 AMD/GPU 加速，需安装 ROCm 与 PyTorchROCm 版本，并按说明配置驱动与工具链。示例包括安装 ROCm、通过 PyTorchROCm 版本安装、以及使用 rocm-smi 查询 GPU 状态。
• 启动与访问
• 启动应用：python3 app.py
• 默认浏览器会自动打开，地址为 http://127.0.0.1:9966
• 注意：默认从 modelscope 下载模型，请确保网络可访问且禁用代理。

5) macOS 下源码部署

• 环境准备
• 确保 Python 3.9–3.11、Git、ffmpeg 等工具可用。
• 安装依赖：brew install libsndfile git [email protected]
• 安装 ffmpeg 并配置 PATH：brew install ffmpeg；设置 PATH 后再执行后续步骤。
• 部署步骤
• 在 /data/chattts 下克隆仓库
• 创建虚拟环境、安装依赖、安装 Torch（2.2.0）和 Torchaudio（2.2.0）
• 启动 python app.py，浏览器将打开并访问 http://127.0.0.1:9966
• 注意
• 同样需要确保模型下载源的可访问性，禁用代理以便模型下载。

6) Windows 下源码部署

• 先决条件
• 需要 Python 3.9–3.11（安装时勾选“Add Python to environment variables”）。
• 需要 FFmpeg、Git，确保 PATH 可用。
• 步骤概要
• 在 D:/chattts 目录下创建并进入，使用 cmd 执行 git clone https://github.com/jianchang512/chatTTS-ui .
• 创建虚拟环境：python -m venv venv
• 激活虚拟环境：.\venv\Scripts\activate
• 安装依赖：pip install -r requirements.txt
• CUDA 加速与否：不使用 CUDA 时安装 torch==2.2.0 torchaudio==2.2.0；若需要 CUDA 加速，指定 CUDA 版本的 torch/torchaudio 与 CUDA Toolkit。
• 启动应用：python app.py
• 浏览器打开地址：http://127.0.0.1:9966
• 额外说明
• 同样需要注意模型下载来源及代理设置，确保网络可访问。

源码部署注意事项

• 0.96 版本之后，部署时必须安装 ffmpeg，否则会影响音频编码与处理。
• 如果显存低于 4G，系统会强制使用 CPU 推理。
• 如果 GPU 显存较大且是 NVIDIA，但源码部署后仍使用 CPU，尝试重新安装带 CUDA 的 Torch：
• pip uninstall -y torch torchaudio
• pip install torch==2.2.0 torchaudio==2.2.0 --index-url https://download.pytorch.org/whl/cu118
• 同时请确保 CUDA 11.8+ 已正确安装。
• 模型加载方面，系统会首先尝试从 modelscope 下载模型；若不可达，则回退到 huggingface.co 下载模型。

音色获取（音色转换与 emb 文件转换）

• 背景
• 0.96 及以上版本的内核升级后，直接使用 modelscope 下载的 pt 文件不可直接使用，需要进行转换以获得可用的音色编码。
• 转换工具与使用
• 转换脚本 cover-pt.py（Win 整合包中含有 cover-pt.exe，与 app.exe 放在同一目录可直接执行）。
• 执行命令：python cover-pt.py
• 转换过程会把 speaker/seedxxxxrestored_emb.pt 等原始文件转换为可用编码格式，转换后的文件以 _emb-covert.pt 结尾，原 pt 文件将被删除只保留转换后的文件。
• 例如，如果 speaker/seed2155restoredemb.pt 存在，将生成 speaker/seed2155restoredemb-cover.pt。
• 兼容性与说明
• 生成的音色文件命名规则会影响音色选择与自定义种子值的应用，需确保路径和名称与配置相一致。

常见问题与解决路径

• 常见问题与报错请参考 FAQ 文档（faq.md），其中涵盖了环境依赖、网络、模型下载、音色转换等常见场景的排错步骤。
• 若遇到网络下载失败或模型加载失败，请确认网络是否可访问 modelscope 与 huggingface 的资源站点，必要时手动下载并放置到 asset 目录。
• 修改 HTTP 地址
• 默认地址为 http://127.0.0.1:9966
• 如需在局域网中访问，将 .env 文件中的 WEBADDRESS 修改为所需的 IP 与端口组合，例如 WEBADDRESS=192.168.0.10:9966。

使用 API 请求（v0.5+）

• API 概览
• 请求方法：POST
• 请求地址：http://127.0.0.1:9966/tts
• 请求参数（示例）：
  • text: 要合成的文本（必填）
  • prompt: 提示词，用于控制语义或笑声等（可选）
  • voice: 音色标识（默认 2222，可选 2222、7869、6653、4099、5099 等）
  • temperature: 调温参数，默认 0.3
  • top_p: 取样概率阈值，默认 0.7
  • top_k: 取样的最大候选数，默认 20
  • skip_refine: 跳过 refine 阶段，默认 0
  • custom_voice: 自定义音色种子值，非 0 时将覆盖 voice 的指定
• 返回结果
• 成功示例（JSON）：{code:0, msg: "ok", audio_files:[{filename: "…wav", url: "http://…/static/wavs/…wav"}]}
• 失败示例（JSON）：{code:1, msg: "错误原因"}
• Python 调用示例
• import requests
• res = requests.post('http://127.0.0.1:9966/tts', data={ "text": "若不懂无需填写", "prompt": "", "voice": "3333", "temperature": 0.3, "topp": 0.7, "topk": 20, "skiprefine": 0, "customvoice": 0 })
• print(res.json())

与 PyVideoTrans 的集成

• PyVideoTrans 升级
• 将 PyVideoTrans 升级到 1.82 及以上版本以兼容新的 ChatTTS 调用。
• 配置与测试
• 在 PyVideoTrans 的设置菜单中选择 ChatTTS，填写请求地址，默认为 http://127.0.0.1:9966
• 测试无问题后，在主界面选择“ChatTTS”进行使用。
• 使用截图示例
• 在集成成功的示例中，可以看到 PyVideoTrans 与 ChatTTS 的联动效果。相关示例图片来自官方演示：
  • 集成示例图像: https://github.com/jianchang512/ChatTTS-ui/assets/3378335/7118325f-2b9a-46ce-a584-1d5c6dc8e2da

重要提示与最佳实践

• 依赖与环境
• 0.96 版本之后务必确保 ffmpeg 已正确安装；在某些系统中，系统自带的 FFmpeg 版本不足以支撑高质量音频编码。
• 对于显存较小的设备（如 4G 以下），推荐使用 CPU 模式运行，以避免显存溢出导致的崩溃或卡顿。
• GPU 加速
• NVIDIA 显卡 + CUDA 11.8+ 能带来明显的推理加速，但要确保 CUDA 驱动与 Toolkit 正确安装。
• 如果遇到显卡检测异常，请尝试重新安装 CUDA 版本的 Torch，并确保网络环境能访问 NVIDIA 的 PyTorch wheel。
• AMD/ROCm 支持
• AMD GPU 的加速可通过 ROCm 与 PyTorchROCm 实现。请按照 ROCm 官方文档与 PyTorchROCm 版本安装，且在运行前使用 rocm-smi 或 PyTorch 脚本验证设备可用性。
• 模型下载与代理
• 启动时模型通常会尝试从 modelscope 下载，若无法访问建议暂停代理或在无代理环境下运行。
• 确保默认下载源可用，必要时切换到备用源（如 huggingface）。
• 音色获取与兼容性
• 由于版本更新，旧目录中的 pt 文件可能不可用，需要通过 cover-pt.py 脚本进行转换以获得可用的 emb 文件。
• 如果你使用的是 Windows 整合包，已携带 cover-pt.exe，便于一键转换音色。
• 安全与隐私
• 作为本地运行的文本转语音解决方案，尽量在受信任的本地环境中部署，避免在公网上暴露接口，除非你进行额外的鉴权与安全加固。

总结与展望

ChatTTS WebUI & API 提供了一个灵活、可扩展的本地文本转语音解决方案，支持中英文混合文本、多音色体验，以及可观的本地化部署能力。无论你是想在个人电脑上体验高质量语音合成，还是希望将其整合进自有应用，亦或在研究/开发场景中进行离线部署、数据隐私的控制，ChatTTS 都提供了多元的入口与路径。

在未来版本中，诸如更丰富的音色库、进一步优化的合成质量、以及对更多平台的支持将成为持续改进的方向。社区与开发者的参与也将推动该项目不断完善。若你愿意贡献代码、文档或使用案例，欢迎通过官方渠道加入讨论与协作。

附注：本文所提及的图像与链接均来自原始项目页面与 README 的公开资源，请在遵循许可与使用条款的前提下使用和展示。

参考与资源

• ChatTTS UI 主页与 README（包含安装、部署、音色获取等指南）
• 界面预览图片
• https://github.com/jianchang512/ChatTTS-ui/assets/3378335/669876cf-5061-4d7d-86c5-3333d0882ee8
• PyVideoTrans 集成示例图片
• https://github.com/jianchang512/ChatTTS-ui/assets/3378335/7118325f-2b9a-46ce-a584-1d5c6dc8e2da

如果你愿意，我们也可以将本文进一步本地化为教程型内容，按照你的实际使用场景（如个人电脑、服务器、教育场景等）来定制部署步骤和示例代码。

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/chattts-webui-api?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)