ComfyUI_MaskGCT 插件完全使用指南

1. 插件简介

ComfyUI_MaskGCT 是一个专门用于语音合成和语音识别的插件包，插件地址：https://github.com/807502278/ComfyUI_MaskGCT

这个插件主要能帮你做三件事：

• 语音合成：就像给电脑装了一个虚拟播音员，你输入文字，它就能说出来
• 语音识别：就像给电脑装了一双耳朵，它能听懂你说的话并转成文字
• 语音编辑：就像一个简单的音频剪辑工具，能调整音频的各种属性

想象一下，你有一段很好听的声音样本，这个插件就能学会这个声音，然后用这个声音来朗读任何你想要的文字。就像是给电脑教会了模仿某个人的声音一样。

2. 如何安装

方法一：直接下载安装

1. 下载压缩包后解压到 ComfyUI/custom_nodes/ 文件夹里
2. 打开命令行，进入 ComfyUI/custom_nodes/ComfyUI_MaskGCT 文件夹
3. 运行命令：你的python路径/python.exe -m pip install -r requirements.txt

方法二：使用git命令

1. 在 ComfyUI/custom_nodes/ 文件夹里打开命令行
2. 运行：git clone https://github.com/807502278/ComfyUI_MaskGCT.git
3. 安装依赖包（同上）

必需的额外软件

• ffmpeg：音频处理工具，从 https://www.gyan.dev/ffmpeg/builds 下载
• espeak-ng：语音合成工具，Windows用户下载 espeak-ng-X64.msi

3. 节点详细解析

3.1 load_maskgct_model（加载主要语音模型）

这个节点就像是打开一个装满声音模板的工具箱，它会加载或自动下载语音合成需要的主要模型。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| 无参数 | 无参数 | 无 | 无 | 这个节点就像开关，一插上就自动工作 | 自动加载MaskGCT模型文件 | 直接连接到下一个节点即可 |

3.2 load_w2vbert_model（加载音频理解模型）

这个节点就像是给电脑装了一个能听懂各种声音的耳朵，它专门负责理解和分析音频。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| 无参数 | 无参数 | 无 | 无 | 这个节点像个自动助手，插上就开始工作 | 自动加载W2V-BERT音频编码模型 | 直接连接到MaskGCT Pipeline节点 |

3.3 MaskGCT Pipeline（语音合成预处理管道）

这个节点就像一个调音台，把所有的声音材料和设置都准备好，为最终的语音合成做准备。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| maskgct_model | maskgct_model | 模型对象 | 来自load_maskgct_model | 语音合成的大脑 | MaskGCT模型实例 | 连接load_maskgct_model的输出 |
| w2vbert_model | w2vbert_model | 模型对象 | 来自load_w2vbert_model | 音频理解的耳朵 | W2V-BERT模型实例 | 连接load_w2vbert_model的输出 |
| sample_audio | sample_audio | 音频文件 | 你想模仿的声音 | 声音样本，就像给AI听一个声音示例 | 参考音频数据 | 上传一段清晰的语音文件 |
| sample_prompt_text | sample_prompt_text | 文本字符串 | 音频对应的文字 | 告诉AI这段声音说的是什么 | 参考音频对应的文本内容 | 输入"你好，我是小明"对应音频内容 |
| sample_language | sample_language | 语言代码 | 根据音频语言选择 | 告诉AI这是什么语言的声音 | 参考音频的语言类型 | 中文选择"zh"，英文选择"en" |
| device | device | 设备类型 | cuda/cpu | 选择用显卡还是处理器来计算 | 运行设备选择 | 有显卡选cuda，没显卡选cpu |

3.4 Load Audio from Path（从路径加载音频）

这个节点就像一个音频文件管理器，能从你的电脑里找到并读取音频文件。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| path | path | 文件路径 | 你的音频文件路径 | 告诉节点去哪里找音频文件 | 音频文件的完整路径 | 输入"C:/music/voice.wav" |

输出信息：

• Audio：音频数据（就像把声音变成了电脑能理解的数字）
• Time(s)：音频时长（告诉你这段声音有多长）
• Sample：采样率（声音的清晰度，数字越大越清晰）
• Channel：声道数（单声道是1，立体声是2）

3.5 MaskGCT Run V2（语音合成执行器）

这个节点就是真正的语音合成师，它把准备好的所有材料组合起来，生成你想要的声音。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| maskgct_pipeline | maskgct_pipeline | 管道对象 | 来自MaskGCT Pipeline | 准备好的合成工具 | 预处理管道实例 | 连接MaskGCT Pipeline的输出 |
| target_text | target_text | 文本字符串 | 你想要合成的文字 | 想让AI说什么就输入什么 | 目标合成文本 | 输入"今天天气真好" |
| language | language | 语言代码 | Auto或具体语言 | 选择用什么语言来说话 | 目标语言类型 | 选择"Auto"让AI自动判断 |
| settings | settings | 设置对象 | 可选的详细设置 | 调节声音的各种细节 | MaskGCT参数配置 | 可以不连接使用默认设置 |

输出信息：

• Audio：合成的语音（你要的声音文件）
• Audio_List：分段音频列表（长文本被分成小段的声音）
• Batch_Text：分段文本列表（长文本被分成小段的文字）

3.6 MaskGCT Setting（语音合成详细设置）

这个节点就像一个专业调音师的控制台，能精细调节语音合成的各种参数。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| target_len | target_len | 数字 | 0 | 每段声音的长度，0表示自动计算 | 目标音频段长度 | 输入0让系统自动决定 |
| text_slice_length | text_slice_length | 数字 | 120 | 把长文本切成小段的长度 | 文本切片长度 | 中文建议60，英文建议120 |
| pause_time | pause_time | 数字 | 0.5 | 每句话之间的停顿时间 | 句间停顿时长 | 0.5秒比较自然 |
| maskgct_系列 | maskgct_ | 各种数值 | 默认值 | 调节语音合成模型的内部参数 | MaskGCT模型配置参数 | 新手建议使用默认值 |
| w2vbert_系列 | w2vbert_ | 各种数值 | 默认值 | 调节音频理解模型的内部参数 | W2VBert模型配置参数 | 新手建议使用默认值 |
| w2vbert_time_steps | w2vbert_time_steps | 数字列表 | [25,10,1,1,1,1,1,1,1,1,1,1] | 控制音频处理的时间步长 | 时间步长配置 | 使用默认值即可 |

3.7 Speech Recognition-whisper_large_v3（语音识别器）

这个节点就像一个专业的速记员，能听懂你说的话并写成文字。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| audio | audio | 音频数据 | 需要识别的音频 | 输入你想转成文字的声音 | 待识别的音频输入 | 连接音频加载节点的输出 |

输出信息：

• text：识别出的文字内容

3.8 Audio Resampling（音频重采样）

这个节点就像一个音频格式转换器，能调整音频的采样率，改变音频的质量或播放速度。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| audio | audio | 音频数据 | 待处理的音频 | 输入需要调整的音频 | 原始音频输入 | 连接音频文件 |
| sample | sample | 数字 | 22050 | 新的采样率，影响音质 | 目标采样率 | 22050是常用的语音采样率 |
| resample | resample | 布尔值 | True | 是否进行重采样 | 重采样开关 | True表示重采样，False表示变速 |

3.9 Audio Capture percentage（音频按比例裁剪）

这个节点就像一个音频剪刀，能按照百分比裁剪音频的开头和结尾。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| audio | audio | 音频数据 | 待裁剪的音频 | 输入需要裁剪的音频 | 原始音频输入 | 连接音频文件 |
| start | start | 百分比 | 0.0 | 从开头剪掉多少，0.1表示剪掉前10% | 开始裁剪比例 | 0.05表示剪掉前5% |
| end | end | 百分比 | 1.0 | 保留到哪里，0.9表示保留到90% | 结束裁剪比例 | 0.95表示保留到95% |

3.10 Get Audio Data（获取音频数据信息）

这个节点就像一个音频文件的体检报告，告诉你这个音频文件的各种详细信息。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| audio | audio | 音频数据 | 待检查的音频 | 输入想了解信息的音频 | 音频数据输入 | 连接任何音频输出 |

输出信息：

• sample：采样率（音频的清晰度）
• Time(s)：音频时长（多少秒）
• channel：声道数（单声道还是立体声）
• batch_size：批处理大小（同时处理多少个音频）
• Data_Length：数据长度（音频数据的大小）

3.11 Get Text Data（获取文本数据信息）

这个节点就像一个文本分析师，能分析文本的语言、长度、单词数等信息。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| text | text | 文本字符串 | 待分析的文本 | 输入想了解信息的文字 | 文本数据输入 | 输入"你好世界" |

输出信息：

• language：检测到的语言类型
• character_length：字符长度
• words：分词后的单词数组
• words_number：单词数量
• symbols：符号数组
• symbols_number：符号数量

3.12 Remove Blank Space（去除静音）

这个节点就像一个音频清洁工，能去掉音频中的静音部分，让声音更紧凑。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| audio | audio | 音频数据 | 待处理的音频 | 输入需要去除静音的音频 | 原始音频输入 | 连接音频文件 |
| threshold | threshold | 数字 | 0.01 | 静音的判断标准，越小越严格 | 静音检测阈值 | 0.01表示很小的声音也算静音 |
| time_length | time_length | 数字 | 0 | 限制处理的时长，0表示全部处理 | 处理时长限制 | 0表示处理整个音频 |

3.13 Multilingual Slice（多语言文本切片）

这个节点就像一个智能的文本编辑器，能根据标点符号把长文本切成合适的小段。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| text | text | 文本字符串 | 待切片的文本 | 输入需要分段的长文本 | 原始文本输入 | 输入一篇长文章 |
| language | language | 语言代码 | Auto | 选择文本的语言 | 语言类型选择 | Auto让系统自动判断 |
| text_slice_length | text_slice_length | 数字 | 120 | 每段文本的最大长度 | 文本切片长度 | 中文建议60，英文建议120 |

输出信息：

• sentence：按标点分割的短句列表
• sentence_number：短句数量
• length_sentence：按长度重新组合的句子列表
• length_sentence_n：重新组合后的句子数量

3.14 Audio Speed Adjustment（音频速度调节）

这个节点就像一个音频播放器的变速功能，能让音频播放得更快或更慢。

| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 | 专业解释 | 怎么用/举个例子 |
| :— | :— | :— | :— | :— | :— | :— |
| audio | audio | 音频数据 | 待调速的音频 | 输入需要调节速度的音频 | 原始音频输入 | 连接音频文件 |
| scale | scale | 数字 | 1.0 | 速度倍数，1.0是原速 | 时长缩放倍数 | 0.5表示播放速度变慢一半，2.0表示播放速度变快一倍 |

4. 使用技巧和建议

基础使用流程

1. 准备声音样本：选择一段清晰、没有背景噪音的语音文件，最好是3-10秒的纯净人声
2. 模型加载：先连接两个模型加载节点，等待模型下载完成
3. 设置管道：在MaskGCT Pipeline中输入样本音频和对应文字
4. 文本合成：在MaskGCT Run V2中输入想要合成的文字
5. 调节参数：根据需要连接MaskGCT Setting来精细调节

声音样本选择建议

• 选择发音清晰、没有口音的录音
• 避免有背景音乐或噪音的音频
• 样本时长建议在3-10秒之间
• 确保样本文本和音频内容完全匹配

参数调节技巧

• 新手建议全部使用默认参数
• 如果合成语音听起来不自然，可以调小 pause_time 到0.3
• 长文本建议调小 text_slice_length 到60-80
• 如果想要更快的处理速度，可以调小 target_len

5. 常见问题解答

Q1：为什么安装后提示"espeak not installed"？

答：需要安装espeak-ng软件。Windows用户下载espeak-ng-X64.msi并安装，然后在命令行输入 espeak-ng --voices 测试是否安装成功。

Q2：模型下载很慢怎么办？

答：模型文件比较大，首次使用需要下载。建议使用稳定的网络环境，或者手动下载模型文件放到 comfyui/models/maskgct 目录下。

Q3：合成的声音听起来不像样本声音？

答：检查以下几点：

• 样本音频是否清晰无噪音
• 样本文本是否与音频内容完全匹配
• 尝试使用更高质量的样本音频
• 确保样本和目标文本使用相同的语言

Q4：处理长文本时出错怎么办？

答：长文本会自动切片处理，如果出错可以：

• 手动把长文本分成短段
• 调小 text_slice_length 参数
• 检查文本中是否有特殊字符

Q5：显存不够用怎么办？

答：在device参数中选择"cpu"使用处理器计算，虽然速度会慢一些，但不会占用显存。

6. 高级应用场景

多语言语音合成

这个插件支持6种语言的语音合成，你可以：

• 制作多语言的语音播报
• 创建语言学习材料
• 制作国际化的音频内容

音频后期处理

结合插件的音频处理功能，你可以：

• 去除音频中的静音部分
• 调节音频的播放速度
• 按比例裁剪音频内容
• 转换音频的采样率

语音识别应用

利用whisper模型，你可以：

• 将录音转换为文字
• 制作会议记录
• 创建字幕文件
• 分析音频内容

这个插件功能强大，但使用起来并不复杂。记住最重要的是准备好质量高的声音样本，其他参数基本可以使用默认值。随着使用经验的积累，你可以逐渐尝试调节各种参数来获得更好的效果。