WorkBuddy + HyperFrames 安装教程：接入本地 Qwen3-TTS，实现自己的声音自动配音

Tue, 28 Jul 2026 11:55:00 +0800

想用 AI 自动生成动画视频，但不熟悉 Node.js、FFmpeg、命令行和环境配置？

一种更省事的方案是：使用 WorkBuddy 协助安装和排查问题，用 HyperFrames 把 HTML 动画渲染成 MP4，再通过桥接脚本接入本地 Qwen3-TTS，实现字幕、画面和个人声音配音的一体化制作。

一、三个工具分别做什么？

WorkBuddy

WorkBuddy 是腾讯推出的桌面 AI Agent。它不仅能回答问题，还可以协助执行命令、安装依赖、修改文件和分析报错。

在这套流程中，它主要负责：

检查电脑环境
安装 HyperFrames
执行终端命令
分析安装报错
编写 Qwen3-TTS 桥接脚本
调整视频项目文件

需要注意的是，WorkBuddy 本身不是 HyperFrames 的必要依赖。熟悉命令行的用户，也可以手动完成全部操作。

HyperFrames

HyperFrames 是 HeyGen 开源的 HTML 转视频框架。

它允许开发者使用 HTML、CSS、JavaScript 和动画时间轴制作画面，再按照固定帧逐帧渲染为 MP4 视频。

适合制作：

产品介绍动画
数据可视化视频
知识讲解视频
字幕配音视频
网页演示视频
社交媒体短视频

与传统录屏不同，HyperFrames 使用确定性的逐帧渲染方式。同一个项目重复渲染时，画面和动画时间通常能够保持一致。

Qwen3-TTS

Qwen3-TTS 是通义千问团队开源的语音生成模型，支持文本转语音、音色设计和声音克隆。

将它部署在本地后，可以用参考音频生成接近目标音色的配音，不必每次调用第三方在线语音接口。

请只克隆自己拥有授权的声音，不要冒用他人身份或未经允许复制他人音色。

二、安装前需要准备什么？

本文以 Windows 环境为例。

建议提前准备：

Node.js
FFmpeg
WorkBuddy
已部署的 Qwen3-TTS，可选
足够的磁盘空间

如果暂时没有 Qwen3-TTS，也可以先完成 HyperFrames 的安装和视频渲染，后续再接入本地配音。

三、安装 Node.js

前往 Node.js 官网下载长期支持版，也就是 LTS 版本。

安装完成后，打开 PowerShell 或 Windows Terminal，执行：

1
2

node -v
npm -v

如果能够正常显示版本号，说明 Node.js 和 npm 已安装成功。

例如：

1
2

v22.x.x
10.x.x

如果系统提示找不到 node 命令，可以尝试：

关闭并重新打开终端。
重启电脑。
检查 Node.js 是否已加入系统环境变量。

四、安装 FFmpeg

以管理员身份打开 PowerShell，然后执行：

`1`	`winget install --id Gyan.FFmpeg`

安装完成后，重新打开终端并检查：

`1`	`ffmpeg -version`

能够看到 FFmpeg 的版本和编译信息，即表示安装成功。

如果 winget 无法使用，也可以从 FFmpeg 官方网站下载 Windows 构建版本，再手动配置环境变量。

五、安装 WorkBuddy

前往 WorkBuddy 官方网站，下载适合 Windows 或 macOS 的客户端。

安装并登录后，可以先让 WorkBuddy检查当前环境：

`1`	`请检查这台电脑是否已经安装 Node.js、npm 和 FFmpeg，并分别输出版本号。缺少的依赖请告诉我具体安装方法。`

这样做的好处是，可以先发现环境问题，再开始安装 HyperFrames，避免安装到一半才发现依赖缺失。

六、使用 WorkBuddy 安装 HyperFrames

打开 WorkBuddy，新建一个空文件夹作为视频项目目录，然后输入：

`1`	`请在当前目录安装 HyperFrames，并创建一个可以预览和渲染的最小示例项目。完成后检查 Node.js、FFmpeg 和浏览器渲染依赖是否正常。`

也可以手动安装 HyperFrames Skill：

`1`	`npx skills add heygen-com/hyperframes --yes`

安装完成后，可以让 WorkBuddy 创建一个简单测试视频：

请使用 HyperFrames 创建一个 8 秒的 16:9 测试视频。

要求：
1. 深色背景。
2. 中间显示“Hello HyperFrames”。
3. 文字淡入并轻微向上移动。
4. 最后导出为 MP4。

七、运行环境体检

在项目目录中执行：

`1`	`npx hyperframes doctor`

部分安装方式可能也支持：

`1`	`hyperframes doctor`

建议优先使用 npx hyperframes，因为它会调用当前项目使用的版本，能够减少全局版本和项目版本不一致的问题。

环境体检通常会检查：

Node.js
FFmpeg
浏览器或 Chromium
HyperFrames 项目配置
视频渲染相关依赖

如果出现报错，不要只发送最后一行错误。建议把完整终端输出复制给 WorkBuddy：

1
2
3

下面是执行 npx hyperframes doctor 后的完整报错。

请先判断是哪项依赖失败，再给出修复步骤。不要删除现有项目文件，也不要升级无关依赖。

八、预览和渲染视频

创建好 HTML 动画项目后，可以先预览：

`1`	`npx hyperframes preview`

确认画面、动画和字幕没有问题后，再执行渲染：

`1`	`npx hyperframes render index.html`

也可以指定输出文件：

`1`	`npx hyperframes render index.html --output output.mp4`

不同版本的命令参数可能有所变化。如果命令报错，应先运行：

`1`	`npx hyperframes --help`

以当前安装版本显示的命令为准。

九、接入本地 Qwen3-TTS

HyperFrames 负责画面渲染，Qwen3-TTS 负责生成配音。两者之间通常需要增加一个桥接层。

整体流程如下：

视频文案
   ↓
桥接脚本
   ↓
本地 Qwen3-TTS 接口
   ↓
生成 WAV 或 MP3
   ↓
HyperFrames 读取音频
   ↓
根据音频时长生成字幕和动画
   ↓
导出 MP4

桥接脚本主要负责：

接收需要配音的文字。
调用本地 Qwen3-TTS。
指定参考音频和参考文本。
保存生成的音频。
把音频文件路径返回给 HyperFrames。

十、让 WorkBuddy 编写桥接脚本

假设本地 Qwen3-TTS 已经提供 HTTP API，可以向 WorkBuddy 输入：

我的本地 Qwen3-TTS 服务已经启动，请为当前 HyperFrames 项目编写一个 TTS 桥接脚本。

要求：
1. 接收中文文本。
2. 调用本地 Qwen3-TTS HTTP API。
3. 支持配置 API 地址、参考音频和参考文本。
4. 将生成结果保存到 public/audio 目录。
5. 返回音频文件路径和音频时长。
6. 请求失败时输出明确的错误信息。
7. 不要把本地路径和接口地址写死，统一放到 .env 文件中。
8. 同时生成 .env.example 和使用说明。

建议在 .env 中保存类似配置：

1
2
3

QWEN_TTS_API_URL=http://127.0.0.1:8000
QWEN_TTS_REF_AUDIO=D:/voice/reference.wav
QWEN_TTS_REF_TEXT=这里填写参考音频对应的准确文字

不要把真实的本地路径、密钥或个人声音样本提交到公开 GitHub 仓库。

可以在 .gitignore 中加入：

.env
public/audio/
private/
*.wav

十一、一个容易忽略的问题：接口格式不一定相同

“已经部署 Qwen3-TTS”并不代表所有项目都使用相同接口。

不同的本地部署项目可能使用：

Python 函数调用
FastAPI 接口
Gradio 接口
OpenAI 兼容接口
自定义 WebSocket 接口

因此，桥接脚本不能直接照搬。至少要先确认：

接口地址：
请求方法：
请求参数：
返回格式：
音频格式：
是否需要参考音频：
是否需要参考文本：

可以让 WorkBuddy读取本地 Qwen3-TTS 项目的 README 或接口代码，然后根据真实接口编写适配脚本。

推荐提示词：

`1`	`请读取这个 Qwen3-TTS 项目的 README 和服务端接口代码，确认真实的请求地址、参数和返回格式，再修改 HyperFrames 桥接脚本。不要猜测接口字段。`

十二、生成自己的声音配音

Qwen3-TTS 的声音克隆通常需要准备：

一段清晰的参考音频
参考音频对应的准确文字
需要生成的新文案

参考音频建议：

环境安静
没有背景音乐
没有明显混响
只有一个人说话
发音清楚
参考文本与录音内容一致

完成配置后，可以让 WorkBuddy执行测试：

请使用本地 Qwen3-TTS 生成一段中文测试配音，文案为：

“这是通过 HyperFrames 和本地语音模型生成的一段测试视频。”

生成后检查音频是否可以正常播放，再把它加入 HyperFrames 时间轴，并生成同步字幕。

确认试听结果正常后，再开始生成正式视频。

十三、常见问题

1. 找不到 `hyperframes` 命令

优先尝试：

`1`	`npx hyperframes --help`

如果可以运行，说明 HyperFrames 安装在当前项目，而不是全局环境。

2. FFmpeg 已安装，但终端仍然找不到

关闭所有终端窗口后重新打开。

仍然无效时，检查 FFmpeg 的 bin 目录是否已经加入系统 Path。

3. 浏览器下载失败

可能与网络、代理、防火墙或缓存有关。

可以把完整错误日志交给 WorkBuddy，重点检查：

下载地址是否可以访问
系统代理是否生效
防火墙是否拦截
磁盘空间是否充足
浏览器缓存目录是否损坏

4. 视频有画面但没有声音

检查：

音频文件是否真实存在
HTML 中的文件路径是否正确
音频格式是否受支持
音频是否加入时间轴
渲染时 FFmpeg 是否检测到音轨

5. 字幕和配音不同步

不要只按照文字长度估算时间。

更可靠的方式是先生成音频，再读取真实音频时长，根据句子或时间戳安排字幕和动画。

6. 自己的声音不像

重点检查：

参考音频是否清晰
参考文本是否准确
是否选择了支持声音克隆的 Base 模型
音频中是否包含噪声、音乐或多人说话
桥接脚本是否正确传递参考音频

十四、这套方案适合谁？

这套工作流适合：

不熟悉命令行的内容创作者
想批量制作知识类视频的人
需要自动生成字幕和配音的人
希望减少在线视频工具费用的人
已经部署本地语音模型的用户
想用 HTML、CSS 和 JavaScript 制作动画的人

它的核心价值不是“完全不用配置”，而是让 AI Agent 帮助完成重复安装、脚本适配和错误排查，把视频生产流程从多个工具之间的手动切换，变成相对统一的自动化工作流。

总结

WorkBuddy、HyperFrames 和 Qwen3-TTS 分别解决了三个问题：

WorkBuddy：负责安装、执行和排错。
HyperFrames：负责把 HTML 动画渲染成 MP4。
Qwen3-TTS：负责本地语音生成和个人音色配音。

真正关键的环节，是根据本地 Qwen3-TTS 的真实接口编写桥接脚本，而不是简单复制一段固定代码。

完成桥接后，就可以形成一条相对完整的自动化流程：

输入视频主题
→ AI 生成脚本和 HTML 动画
→ Qwen3-TTS 生成配音
→ 自动生成字幕
→ HyperFrames 渲染 MP4

项目与官方地址

WorkBuddy 官方介绍：https://docs.cloudbase.net/ai/ai-tools/workbuddy
HyperFrames GitHub：https://github.com/heygen-com/hyperframes
HyperFrames 文档：https://hyperframes.heygen.com/
Qwen3-TTS GitHub：https://github.com/QwenLM/Qwen3-TTS

自动配音 on 拾光集