andyhuo520/digital-human-koubo:1.9k stars 的 AI 数字人口播工厂,一张照片 + 一句话出片

上周有个朋友问我:

“我想做口播号,但不想露脸、不想配音、不想学剪辑。 有没有可能丢一段文案进去,它自己出片?”

我第一反应是” 这不就是那些 AI 数字人工具吗”,但真的一去翻 GitHub,发现能用的东西要么是闭源 SaaS(按分钟计费,样式就那几套),要么是几百行的 demo 脚本(生成完就没了,还得自己找剪辑软件)。

然后我刷到了 andyhuo520/digital-human-koubo。

1,897 stars,435 forks,MIT,主语言 TypeScript,2026 年 10 月 26 日建的仓库,到 10 月 31 日还有提交。不到两周。

它不是” 一个数字人生成工具”。它是一个跑在 AI agent 里的完整视频生产车间 —— 你跟 Claude Code 说一句话,它从诊断内容、选风格、写稿、报价、生成、回听质检、统一音色、套包装、做封面,一路跑到成片 mp4。

作者 Berryxia 在 README 里写了一句我觉得很实在的话:

Made by Berryxia · built with Claude Code

意思是:这个仓库本身就是 Claude Code 写出来的。我花了一晚上把 README、SKILL.md、persona.json 和几个关键脚本翻了一遍,下面按” 这玩意到底怎么运作的、哪些设计是真有想法的、坑在哪” 来写。


一、它想解决什么:口播视频的真实成本

先说清楚痛点,别急着看代码。做一条数字人口播视频,拆开看是六件事:

  1. 找 / 造一个形象 —— 要么自拍,要么找人画,要么用现成形象库
  2. 写稿 —— 口播稿和文章不一样,得算语速
  3. 生成带口型的视频 —— 这段最贵
  4. 质检 —— 念错字、字幕烧进画面、齿音不一致
  5. 剪辑 —— 字幕、花字、卡片、节奏、BGM、音效
  6. 封面 + 首帧 —— 平台拿第一帧当缩略图

单看每一步都不难。难的是串起来,而且每一步都会往回污染上一步:

  • 稿子太长 → 生成超时 → 分段 → 段间音色漂移 → 声音对不上口型
  • 生成出来发现烧了字幕 → 重拍 → credits 白花
  • 念错一个字 → 重拍整条?或者重配音 → 口型又对不上
  • 剪辑时才发现某个镜头是特写 → 文字在人身后放不下 → 整条镜头重拍

这个项目最有意思的地方,就是它把上面每一条” 回流” 都变成了可执行的脚本。


二、它是什么:一份 Agent Skill,不是一个 SaaS

先把定位说准,这很重要。

andyhuo520/digital-human-koubo 不是一个 Web 应用,不是一个 npm 包,它是一个 Agent Skill—— 遵循 2026 年 Anthropic 提出的开放 Agent Skills 格式:一个文件夹,里面有 SKILL.md + 脚本 + 资源。

仓库结构(从 GitHub tree API 拉的真实结构):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
skills/
digital-human-koubo/ 主 skill
SKILL.md agent 遵守的工作流
persona.json 形象、声音、提示词模板
references/ 风格菜单 · 包装 · 玩法 · 研究报告
scripts/ build_tasks · rangedl · assemble · align · check_edit
cutout_video · voicefx/unify · doctor · new_edit
make_cover · cover_first · lin_scenes · lin_subs
lin_sfx · lin_mix · misread_check · patch_words
templates/
huazi-916/ 9:16 数据驱动口播模板
packaging/ 48 组件套件 + 图鉴工程
lin-169/ 16:9 小林式解说模板(scenes.json 驱动,13 种场景)
reference/ launch-169 · tutorial-169 · multihost-169
finance-explainer/ 纯图表财经长片引擎
docs/

整个仓库 git tree 里 979 个条目(917 个文件 + 62 个目录),其中 31 个 Python 脚本、611 个 ts/tsx(绝大部分是 Remotion 模板组件)、3 个 shell 脚本。

1,897 stars 是怎么来的

数字上没有水分:

  • 1,897 stars / 435 forks
  • MIT,作者 Berryxia(andyhuo520)
  • 仓库创建:2026-10-26
  • 最后推送:2026-10-31
  • 唯一 release:v1.0.0(2026-10-26),带着 5 个 demo mp4

10 月 26 日建仓,10 月 26 日发 v1.0.0,5 天内冲到 1.9k stars。这在 AI agent 工具里属于爆发式传播 —— 大概率是被” 一条照片出直播带货广告” 的 demo 视频刷屏了。

它需要什么才能跑起来

README 里写得很明白,一个 agent 要驱动完整流水线,需要三件事:

能力 说明 谁有
加载 Agent Skills skills 文件夹或 zip 上传 Claude Code / Codex / OpenClaw / WorkBuddy…
连接远程 MCP server Renoise,streamable HTTP,浏览器登录,不用 API key 全部主流 agent
在本机跑命令 ffmpeg、Python、Node,用于下载、质检、剪辑 Claude Code / Codex 有;网页版 Claude 只有沙箱

第三条是分水岭:只有 MCP + 对话、没有本机 shell 的 agent,仍然可以规划、报价、生成视频片段,但剪辑得另外找 Claude Code / Codex 干,或者手工执行 SKILL.md 里的命令。

这个降级设计我觉得挺聪明 —— 它没有假设” 所有人都有 Claude Code”。


三、核心机制:整条流水线长什么样

README 里给的流程图,我把它翻译成人话:

1
2
3
4
5
6
7
8
9
10
你的内容 ──► 0. 环境检查(Renoise MCP / ffmpeg / whisper,缺什么装什么)
1. 诊断内容 → 从 5 种风格里推荐 2 种 → 一次性问完 → brief.json
2. script.json(每段 ≤15 秒,中文约 5.4 字/秒)
3. 报价 credits → 等你说"好" → 生成第 1 段 → 你确认 → 批量
4. Range 分段下载(CDN 安全)→ whisper 回听 → 抽帧检查
5. 音色统一(频谱匹配 + 去齿音 + 同一间小房间混响)
6. 逐字时间轴 tl.json
7. Remotion 剪辑:风格模板 + 默认包装(+ 你的追加要求)
8. 渲染 → 检查过渡中间帧 → 响度(-14 / -16 LUFS)
9. 封面:挑主播帧 → 16:9 / 9:16 / 3:4 → 接成首帧(0.5 秒)

九步。每一步的产物都是磁盘上一个文件,这是整个设计能成立的前提 —— 因为 agent 的上下文有限,但文件不会。

3.1 persona.json:把” 人” 固化成配置

数字人视频最容易失控的地方是” 每条视频长得不一样”。解法很朴素:把身份写成文件。persona.json 里的一个主播长这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"name": "白背心数字人",
"renoise": {
"reference_material": "material:329814",
"multiview_task": "task:357546",
"note": "参考图是用户自己 Grok 视频里的一帧(正脸、闭嘴、头发不挡脸)"
},
"look": "年轻东亚女性,黑色长发带脸侧碎发,白色罗纹背心,竖屏自拍构图,室内自然光",
"voice": {
"engine": "grok-native",
"desc": "young friendly female voice, clear and patient but lively, natural pace",
"speed_cps": 5.4,
"alt_clone": "MiMo mimo-v2.5-tts-voiceclone"
},
"model": {
"name": "grok-video-1.5",
"ratio": "9:16",
"full_shot_resolution": "720p",
"pip_shot_resolution": "480p",
"max_seconds": 15,
"price_per_second": { "720p": 17, "480p": 10 }
}
}

几个我觉得很关键的设计:

speed_cps: 5.4 —— 中文语速 5.4 字 / 秒,写稿时按这个数切。这是个非常具体的经验值,比” 写得有节奏一点” 有用一万倍。

acts 字典 —— 每个镜头类型对应一段行为描述:

1
2
3
4
5
6
"acts": {
"full": "warm eye contact, expressive face, natural hand gestures",
"pip": "calm explaining tone, small nods, occasionally glancing down as if reading a screen",
"vlog": "relaxed lifestyle vlogger sharing a favorite tool, natural small head tilts",
"depth": "medium shot with generous headroom and plain background visible on both sides of the head and shoulders (for text-behind-subject graphics)"
}

注意 depth 那条 —— 它明确说了” 头顶两侧要留出背景”。因为有个效果叫” 文字在人身后”(TextBehind),如果镜头是特写,人占画面 89%,字根本放不下。这个约束被写进了 prompt 模板,靠生成前就限定构图来解决,而不是生成完再返工。

prompt_template —— 所有出镜段落共用一个模板,{ref} {purpose} {act} {voice} {line} 五个槽:

1
2
3
4
5
6
The young woman in {ref} talks straight into her phone's front camera,
same selfie framing, lighting and outfit as the reference, like a friendly
Chinese tech vlogger {purpose}: {act}. Handheld selfie feel with only a
very slight natural sway. She speaks Mandarin Chinese, clearly lip-synced,
in a {voice}: "{line}"
Sound: only her voice and quiet room tone, no music, no subtitles, no on-screen text.

最后那句 no music, no subtitles, no on-screen text 不是装饰。README 的” 已知坑” 里第一条就是:

Grok 偶尔自己烧字幕进横屏片段,即使提示词写了也挡不住 → 帧检查 + 重拍那段。

作者知道模型不听,但还是写了,再用质检兜住。这就是工程和 prompt 的边界在哪。

other_hosts —— 同一个文件里还有另外三个主播:用户本人(藏青 polo,横屏)、橘猫店长、柴犬新闻主播。所以” 造一个自己的数字人” 就是往这个 JSON 里加一段。

languages_tested —— 记录了实测的 whisper 回听准确率:

1
2
3
4
5
"languages_tested": {
"en": "100%", "ja": "100%", "ko": "94%",
"fr": "100%", "es": "100%", "ar": "99%",
"note": "2026-10 第三期实测 whisper 回听准确率;台词提前翻好再写进提示词"
}

阿拉伯语 99%、韩语 94%—— 这些数字是从哪来的?作者说是” 第三期实测”,也就是他自己第三条片子真的一口气试了六种语言。

3.2 报价门:这个项目最值钱的一行代码

SKILL.md 的” 红线” 第一条:

生成花用户的 Renoise credits:create_tasks 之前先报「段数・秒数・预估 credits・余额」,等用户在对话里明确同意。先拍第 1 段给用户确认音色,再批量。重拍也要先报价。

翻译成实现:

1
2
python3 scripts/build_tasks.py script.json tasks.json --purpose "..."
# → 打印段数、秒数、预估 credits

然后拿 estimate_cost 核一次,报给用户等确认。确认后才生成第 1 段,用户看过音色和画质,才批量生成其余的。

这在 AI 视频生成工具里是稀缺品质。因为视频生成本质上是按秒计费的不可逆操作 —— 生成了就是生成了,credits 花出去回不来。一个不报价、不分批的工具,第一次用就能烧掉你几百积分。

作者在 README 里也留了实盘成本:

片子 生成内容 Credits
直播带货广告,9:16,27 秒 1 张场景图 + 5 段 Grok(720p) 482
教程第 2 集,16:9,4:36 32 段(全 720p / PiP 480p)+ demo ~3,250
教程第 3 集,16:9,5:54 30 段新生成 + 7 张场景图,复用 17 段 ~3,409

当时的价:Grok Video 1.5 —— 720p 17 credits / 秒,480p 10 credits / 秒;GPT Image 2.5 2k —— 23 credits。

换算一下:一条 27 秒的竖屏带货广告,482 积分;一条 5 分钟的教程,三千多积分。这个价格放到 SaaS 数字人平台上是什么水平,你自己算。

3.3 画质档位的坑:480p 到底能不能用

build_tasks.py 的逻辑里有个很实用的判断,SKILL.md 写得很直白:

主播要裁成半身 / 放大显示、或者 pip 段的主播卡并不小时,所有出镜段一律 720p(--all-720p):480p 原片只有 400×736,裁半身再铺满大卡会放大 2 倍以上,明显发糊(vibe-knowledge 介绍片因此重拍 4 段,多花 680 积分)。

这是我全篇最喜欢的一段工程注释。因为它同时给了三样东西:

  1. 数字:480p 原片是 400×736
  2. 推理:裁半身再铺满 → 放大 2 倍 → 糊
  3. 代价:实际重拍 4 段,多花 680 积分

有第三样,别的开发者才会信你前面两条。

3.4 下载:Renoise 美国 CDN 会截断并发

scripts/rangedl.py 全文 31 行,核心逻辑:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
N = 6

def part(url, path, a, b):
for _ in range(30):
have = os.path.getsize(path) if os.path.exists(path) else 0
if have >= b - a + 1: return True
r = subprocess.run(['curl', '-sS', '--http1.1', '--max-time', '60',
'-r', f'{a + have}-{b}', url], capture_output=True)
with open(path, 'ab') as f: f.write(r.stdout)
return os.path.getsize(path) >= b - a + 1

def fetch(tid, url):
n = size(url); step = (n + N - 1) // N
rngs = [(i * step, min(n - 1, (i + 1) * step - 1)) for i in range(N)]
with cf.ThreadPoolExecutor(N) as ex:
ok = list(ex.map(lambda ir: part(url, f'.p{tid}_{ir[0]}', *ir[1]), enumerate(rngs)))
with open(f'renoise-{tid}', 'wb') as out:
for i in range(N):
p = f'.p{tid}_{i}'
out.write(open(p, 'rb').read()[: rngs[i][1] - rngs[i][0] + 1]); os.remove(p)
bad = subprocess.run(['ffmpeg', '-v', 'error', '-i', f'renoise-{tid}',
'-f', 'null', '-'], capture_output=True, text=True).stderr.strip()
return tid, n, all(ok), 'OK' if not bad else 'BAD ' + bad[:60]

四个要点:

  • 每个文件切 6 段 Range 并发
  • 每段单独断点续传(用 have 偏移续 -r)
  • 单段最多重试 30 次
  • 全部拼完用 ffmpeg 解码校验,报错就标 BAD

最后那步是关键。下完不等于下好了 —— 一个字节不差但文件损坏的 mp4,ffmpeg 能立刻告诉你。

这段代码本身很朴素,但它解决的是那种” 每次跑都有 1/3 概率某几个段下不全” 的烦人问题。作者在 README 里写”Renoise 的美国 CDN 会截断并行下载”,这是被坑过才会写出来的话。

3.5 质检:whisper 回听 + 抽帧

SKILL.md 里质检环节的描述:

python3 scripts/assemble.py script.json ids.json --out 成片_完整版.mp4:whisper 逐段转写比对文稿、只保留到说完后 0.25 秒、拼接、loudnorm -16。

然后是两条硬规则:

  • whisper --prompt 原文 会让个别段漏掉前半句,用中性提示「以下是普通话的句子。」
  • 每段抽 4 帧看一眼:Grok 横屏口播偶尔自己烧字幕(提示词写了也挡不住),有就重拍那段。

第一条特别有意思。whisper 有个 prompt 参数可以给它上下文,但用它来对齐文稿反而会污染结果 —— 模型会倾向于把听到的音往提示词上凑。所以脚本里用的是” 不带原文的转写”。

3.6 念错字:这是整个项目技术含量最高的部分

大多数 AI 视频工具的做法:念错了,重拍。成本是整段。

这个项目做了两件事。

第一件:找出来。 misread_check.py 的逻辑在 SKILL.md 里写得很清楚:

不能拿带原文提示的转写判断读音:它会把念错的字纠正回去(「通胀」念成 tōng zhèng,带原文照样判全对)。同音字会误报,可疑处听一下确认。

所以 misread_check.py 的做法是:按停顿切句、不带原文逐句转写,列出可疑字。

第二件:修,而且不花钱。 patch_words.py:

1
2
python3 scripts/patch_words.py script.json patch.json \
--ref <2–3 段干净原声> --synth-only

机制是:

只把错的那一句换成 MiMo 克隆音,长度拉到和原句一样,切在停顿上。换整句比只换两个字自然。

用别的模型(MiMo TTS 声音克隆)重新合成出错的那一句,音频长度拉成和原句完全一致,然后切在停顿上替换回去。 口型是原片的,没动。

代价:0 积分。

而如果整片重配音,口型就全乱了。作者还专门警告:

别整片换音色:口型跟的是原声,整片换掉会到处对不上;也别先提 OmniHuman 重做口型(全片约 5,000 积分)。

这里有个非常成熟的成本直觉:局部修复 > 全局重做,即使局部修复技术上更麻烦。

还有一个细节:

开头第一个字最容易被吞或念歪(例:「一个知识点」→「几个知识地点」),写稿时第一段开头别放关键名词,或者先垫一个短词。

这是用写稿规避模型缺陷,而不是硬刚。写 prompt 的人才会这么想。

3.7 音色统一:把 30 段独立生成的音频揉成一条

这是我认为整个项目最硬的工程部分。voicefx/unify.py 97 行,做三件事。

第一件:1/3 倍频程频谱匹配。

1
2
3
4
5
6
7
8
9
10
11
12
CENTERS = [100, 125, 160, 200, 250, 315, 400, 500, 630, 800, 1000, 1250,
1600, 2000, 2500, 3150, 4000, 5000, 6300, 8000, 10000, 12500]

def band_db(x):
n = 1 << 14; win = np.hanning(n); acc = None; k = 0
for i in range(0, len(x) - n, n // 2):
seg = x[i:i + n]
if np.sqrt(np.mean(seg ** 2)) < 0.01: continue
s = np.abs(np.fft.rfft(seg * win)) ** 2; acc = s if acc is None else acc + s; k += 1
f = np.fft.rfftfreq(n, 1 / SR); s = acc / max(1, k)
out = np.array([10 * np.log10(np.sum(s[(f >= c / 2 ** (1 / 6)) & (f < c * 2 ** (1 / 6))]) + 1e-12) for c in CENTERS])
return out - out.mean()

每个片段算 22 个频段的能量(每段覆盖 1/3 倍频程),减去全段均值得到形状,然后向” 参照组中位数” 对齐,修正量限制在 ±4 dB:

1
2
3
4
5
B = {c: band_db(load(c)) for c in clips}
pool = [band_db(load(p)) for p in sorted(ref.glob("*.mp4"))] if ref else list(B.values())
med = np.median(np.stack(pool), 0)
for c in clips:
g = np.clip(med - B[c], -4, 4)

--ref 参数让你可以把新片段向上一期的旧片段靠拢 —— 跨集统一音色。这在做系列内容时非常关键。

修正量最后转成 ffmpeg 的 firequalizer:

1
2
3
def fq(g):
g = np.convolve(np.pad(g, 1, mode="edge"), [0.25, 0.5, 0.25], mode="valid")
return "firequalizer=gain_entry='" + ";".join(f"entry({c},{v:.2f})" for c, v in zip(CENTERS, g)) + "'"

第二件:去刺耳 + 统一频响。

1
2
3
4
CHAIN = ("highpass=f=80,lowpass=f=15000,deesser=i=0.6:m=0.6:f=0.55,"
"equalizer=f=6600:t=q:w=1.3:g=-3,equalizer=f=3600:t=q:w=1.1:g=-1.2,"
"equalizer=f=200:t=q:w=0.9:g=1.4,"
"acompressor=threshold=-22dB:ratio=2.3:attack=8:release=120:makeup=1.4")

6.6 kHz 收 3 dB(齿音区)、3.6 kHz 收 1.2 dB(鼻音区)、200 Hz 补 1.4 dB(胸腔感),加轻度压缩。

第三件:同一个小房间混响。 这个是我觉得最漂亮的一步。

1
2
3
4
5
6
7
8
9
10
11
def tail_ms(x):
"""语音峰值后衰减 20 dB 所需时间的中位数(ms),越大越「湿」"""
hop = SR // 50
env = np.array([np.sqrt(np.mean(x[i:i + hop] ** 2)) + 1e-9 for i in range(0, len(x) - hop, hop)])
db = 20 * np.log10(env); out = []
for i in range(1, len(db) - 15):
if db[i] > db.max() - 18 and db[i + 1] < db[i] - 3:
j = i
while j < len(db) - 1 and db[j] > db[i] - 20: j += 1
if j - i < 40: out.append((j - i) * 20)
return int(np.median(out)) if out else 0

这个函数量的是每段音频本身带的混响尾巴有多长。然后:

1
2
tl = tail_ms(load(c))
wet = float(np.clip(0.24 - (tl - 60) / 320 * 0.16, 0.08, 0.24))

意思是:本来已经很湿的段,少加混响;本来很干的段,多加混响。 最后所有段共用同一个脉冲响应:

1
2
3
4
5
6
7
8
9
def room_ir():
"""小房间脉冲响应:早期反射 + 0.32 s 衰减尾巴,高频吸收(像卧室 / 书房里自拍)"""
rng = np.random.default_rng(7)
n = int(0.55 * SR); t = np.arange(n) / SR
ir = np.zeros((n, 2), np.float32); ir[0] = 1.0
for d, g in [(0.0061, .42), (0.0093, .33), (0.0137, .28),
(0.0189, .22), (0.0247, .17), (0.0311, .12)]:
...
tail = rng.standard_normal((n, 2)).astype(np.float32) * np.exp(-6.91 * t / 0.32)[:, None] * 0.09

早期反射(6.1ms、9.3ms、13.7ms、18.9ms、24.7ms、31.1ms)+ 0.32 秒指数衰减尾巴 + 高频吸收。这不是” 套个混响插件”,这是在用代码合成一个” 卧室里自拍” 的声学空间,然后把 30 段来自不同生成批次的音频塞进同一个房间。

效果数字:齿音段间差从 13.2 dB 降到 5.9 dB(README 和脚本 docstring 里都写了这个数,是 2026 年 10 月第二、三期实测)。

还有个细节 ——--scene 参数。场景片段(B-roll、动物)不加房间混响,只做去齿音 + 响度:

1
SCENE = "highpass=f=70,deesser=i=0.5:m=0.5:f=0.55,equalizer=f=6600:t=q:w=1.3:g=-2"

因为把 B-roll 混进人声的房间里会露馅。

3.8 剪辑:Remotion + 48 个包装组件

剪辑用 Remotion 4(React 写视频,MIT 之外它自己有个 license:个人和 3 人以下公司免费,更多要买公司 license)。

templates/huazi-916/src/kit/ 目录里的组件结构:

1
2
3
4
5
6
7
8
9
src/
Huazi.tsx
Root.tsx
index.ts
icons/NotoEmoji.tsx
kit/
Annotate.tsx Beast.tsx Depth.tsx Explain.tsx
Map.tsx Overlay.tsx Polish.tsx Text.tsx
Wangan.tsx core.tsx registry.tsx

registry.tsx 说明这些是注册式组件 —— 按名字查表渲染。

包装组件是 48 个,分四组:

组 组件
开场 / 钩子 TeaserColdOpen · ColdOpenFreeze · SearchTyping · NumberSpike · SlamText · WordStack · TornStrip · TextBehind
证据 / 数据 EvidenceCard · DocFocus · SourceDoc · ZoomFocus · Counter · Odometer · GlassPanel · SpecCard · LineDraw · BarCompare · ReviewCards · ArchiveCards · MapRoute · CompareWipe · PaperCollage
标注 / 人物 HandDraw · CalloutPill · LeaderLabel · TypedNameTag · LowerThird · NamePlate · SourceTag · FreezeFrame
节奏 / 互动 PunchInHost · KeywordStack · RetentionCaption · TiltLine · Aside · Danmaku · ReactionPop · MemeWindow · PollPop · GlitchInterstitial · HostFloaters · ProgressChapters · ProgressTracker · ChapterCard · RecapBoard · Countdown · GhostWord

这些组件的来源 README 说得清楚:

我们逐帧测量了 25 个视频(镜头检测、开场节拍、屏幕文字、声音)—— 完整报告在 references/research/。
测量对象:MrBeast、Mark Rober、Ryan Trahan、MKBHD、MediaStorm / 影视飓风、何同学、Johnny Harris、Vox、Kurzgesagt、回形针、半佛仙人、差评、毕导

规则提炼成了 packaging-playbook.md,我挑几条:

  • 剪辑次数可以少,但刺激不能停:前 30 秒,每 3–5 秒要有个新东西。
  • 前 3 秒:主张或动作 —— 不要问候,不要 logo。
  • 所有东西底下铺一层 BGM;音效只在事件上(中文口播频道每分钟 1–3 个);揭示前留 0.6–1.0 秒静音。
  • 对单机位数字人,最便宜的节奏是句边界上的 punch-in 切(1.0× / 1.18× / 1.32×)。

“对单机位数字人,最便宜的节奏是 punch-in 切”—— 这句话说明作者是想清楚了在数字人这个特定约束下怎么做节奏,而不是照搬真人多机位拍摄那套。

组件调用方式是往 pack 数组里塞,时间点写成 "段:词":

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"pack": [
{ "use": "NumberSpike", "at": "1:不到十块钱", "until": "1:end",
"text": "¥9.9/节", "label": "一节课" },
{ "use": "Danmaku", "items": [
{ "t": "真的假的?", "at": "1:" },
{ "t": "AI 还能帮我干活?", "at": "1:教你", "hot": true }
]},
{ "use": "TextBehind", "src": "main.mp4", "cutout": "main_cut_s4.webm",
"cutoutFrom": 17.2, "at": "4:", "until": "4:end",
"mode": "count",
"lines": [{ "t": "¥99", "font": "en", "color": "#FFE14D", "size": 0.17 }],
"count": { "from": 999, "to": 99, "prefix": "¥" }
}
]

注意 at 的格式是 "3:积分" 这种段号:关键词 —— 不是时间戳。因为视频是逐段生成的,每段长度会漂移,写死时间戳根本对不上。用” 在第 3 段说到’积分’的时候触发”,才是能对齐真实口播的方式。

3.9 文字在人身后:macOS Vision 抠像

TextBehind 是这 48 个组件里最有技术含量的一个 —— 把大号文字放在人物和背景之间。

实现路径:

1
2
python3 scripts/cutout_video.py public/main.mp4 public/main_cut_s4.webm \
--from 17.2 --to 22.4

用 Apple Vision 的人像分割把人物抠成透明 webm,然后三层合成:背景 → 大字 → 抠出来的人。

作者在 README 里明确标注了这个功能的限制:

它在中景且头顶留白时有效。在自拍特写里人物占画面约 89%,会盖住文字 —— 脚本会在超过 60% 时警告。把这种段标记为 "shot": "depth",它们就会按中景生成。

又是同一个模式:约束写进生成前的 prompt,而不是生成完再补救。

另外注意 --from 17.2 --to 22.4—— 只抠需要的那几秒,不做全片抠像。因为抠像很慢,而且中间帧质量差。

3.10 封面即首帧

最后一个环节,但我觉得这个设计很聪明:

平台默认拿视频第一帧当封面,所以每条片子都做封面,并把它接在成片最前面。

流程:

  1. 写 cover.json(栏目名、钩子标题 ≤8 字、红色强调句 ≤6 字、副标题、≤3 个标签、链接、主播帧、≤2 张证据卡)
  2. make_cover.py cover.json --candidates 抽 12 帧拼候选图
  3. 挑一帧笑着、眼睛睁开、没在说话或嘴型好看的
  4. make_cover.py cover.json 出三种比例:cover_16x9.jpg / cover_9x16.jpg / cover_3x4.jpg
  5. cover_first.py 成片.mp4 cover/cover_16x9.jpg 交付.mp4 —— 封面停 0.5 秒后硬切进正片,声音整体后推 0.5 秒

第 5 步尤其重要:因为封面帧和正片第一帧是两段独立视频,硬切过去会有跳帧感。所以声音要整体后推 0.5 秒和封面停顿时长对齐。这个细节不处理的话,成片开头会很怪。


四、快速上手:真的能跑起来吗

按 README 的顺序:

4.1 拉代码

1
2
git clone https://github.com/andyhuo520/digital-human-koubo.git
cd digital-human-koubo

4.2 装 skill 到你的 agent

Claude Code

1
mkdir -p ~/.claude/skills && cp -R skills/digital-human-koubo skills/finance-explainer ~/.claude/skills/

Codex

1
mkdir -p ~/.codex/skills && cp -R skills/digital-human-koubo skills/finance-explainer ~/.codex/skills/

WorkBuddy / OpenClaw / 其他 agent —— 打包导入:

1
cd skills && zip -r ../digital-human-skills.zip digital-human-koubo finance-explainer && cd ..

4.3 连 Renoise MCP

Renoise 是 AI 视频 / 图片生成服务,streamable HTTP,浏览器登录,不用 API key。

Agent 命令
Claude Code /plugin marketplace add ArcoCodes/renoise-plugins-official 然后 /plugin install renoise@renoise-plugins-official
Codex codex mcp add renoise --url https://renoise.ai/api/public/mcp 然后 codex mcp login renoise
OpenClaw openclaw plugins install renoise --marketplace ArcoCodes/renoise-plugins-official
Claude 桌面端 Settings → Connectors → Add custom connector → URL 填 https://renoise.ai/api/public/mcp
通用配置 {"mcpServers":{"renoise":{"url":"https://renoise.ai/api/public/mcp"}}}

验证:问 agent “查一下我的 Renoise 余额”。

4.4 装本地工具

工具 macOS Windows Linux
ffmpeg brew install ffmpeg winget install Gyan.FFmpeg sudo apt install ffmpeg
Python 3 + numpy + Pillow brew install python 然后 python3 -m pip install numpy pillow winget install Python.Python.3.12 sudo apt install python3-pip
Playwright + Chromium python3 -m pip install playwright && python3 -m playwright install chromium 同 同
Node.js 18+(Remotion) brew install node winget install OpenJS.NodeJS.LTS nvm install --lts
whisper.cpp brew install whisper-cpp Releases 下载 源码编译
whisper 模型 ggml-medium-q5_0.bin → ~/models/ 同 同

一条命令检查(会跳过已有的、列出缺的):

1
bash ~/.claude/skills/digital-human-koubo/scripts/doctor.sh

4.5 生成音效和占位 BGM

仓库不附带任何第三方音频,全部用代码生成(new_edit.sh 每次新建工程会自动跑):

1
python3 ~/.claude/skills/digital-human-koubo/scripts/make_assets.py

生成 30 个音效 + 一条占位 BGM。

4.6 开工

跟 agent 用人话说话:

1
2
3
4
5
用我的数字人 Skill 讲这段:……(粘贴你的内容)
Use my digital human skill to make a 30-second livestream ad: WorkBuddy course, 10 lessons, ¥99 (was ¥999).
Make a 3-minute explainer about why Silicon Valley Bank collapsed, Xiaolin-style.
Add a map route when she mentions these countries. / Put "¥99" behind her. / Add a teaser cold open.
把包装组件图鉴发我看看 (show me the packaging gallery)

之后 agent 会:环境检查(已装的跳过)→ 一行诊断 + 推荐 2 种风格(带预览图)+ 一次性问完所有问题 → 写稿 + 场景设计 + 报价 → 你批准 → 生成第 1 段 → 你批准 → 其余的 → 质检 → 统一音色 → 按风格默认包装剪辑 → 出 mp4。


五、关键设计取舍:作者做对了什么

我把作者明显想清楚的几个点拎出来。

5.1 报价不是功能,是信任机制

任何”AI 视频生成” 工具跑第一次,你都不知道要花多少钱。这个项目的做法是先报” 段数・秒数・预估 credits・余额”,等你说好;先出第 1 段给你看音色,确认了再批量。

它牺牲了” 一键出片” 的流畅感,换来的是用户敢点第一次。

而且 README 里给了实盘成本表,让用户能在点之前就做预算。这在 AI 工具里太少了 —— 大部分只给”credits per second” 这种单价,不给” 我这个需求大概多少” 的实数。

5.2 约束前移:把模型缺陷写进生成条件

前面提到三次的例子:

  • depth 镜位要求” 头顶两侧留背景”(为了放字)
  • prompt 里写 no subtitles(因为模型会乱烧)
  • 写稿时第一段开头别放关键名词(因为第一个字容易念歪)

这三条的共同点是:它们都把” 生成后要返工” 的成本,转移到了” 生成前要想清楚” 的阶段。

一个提示词写得好不好,看的就是这个。

5.3 局部修复优先于全局重做

念错字的处理是这个项目最值得学的决策:

  • ❌ 整段重拍 → 费积分,口型还是新的
  • ❌ 整片重配音 → 口型全乱,SKILL.md 明确警告
  • ❌ 全片 OmniHuman 重做口型 → 约 5,000 积分
  • ✅ 只换出错的那一句,用 MiMo 克隆音,拉长到原句长度,切在停顿处 → 0 积分,口型不动

而且作者还解释了为什么换整句比只换两个字自然(语音连贯性),以及为什么必须切在停顿上(不然会有咔哒声)。

这就是成熟的成本直觉:修复的成本要和错误的严重程度成反比。

5.4 声学统一做到” 同一个房间” 这个粒度

大多数教程会说” 用 Audition 统一响度”。这个项目做的是频谱形状匹配 + 按原混响尾巴自适应补混响 + 共用同一个合成 IR。

最终效果是 30 段来自不同生成批次的音频,听感上是” 同一个人在同一个房间连着说了 5 分钟”。

13.2 dB → 5.9 dB 这个数字说明作者是先测出问题、再量化、最后修的,不是拍脑袋调 EQ。

5.5 把” 看起来专业” 这件事拆成可执行组件

“包装感” 在教程里通常是玄学。这个项目把它拆成 48 个有名字的组件,每个组件有参数,然后:

  • 每个风格有默认包装配方(packaging-presets.json)
  • 正文保证 stimulus_every_s 秒内有一个新视觉事件
  • recurring 类组件全片挂着
  • 用户可以点名加减(” 加地图”” 开场加预告”” 加弹幕”)

把审美决策编码成配置,这是让 agent 能稳定复现质量的关键一步。

5.6 首帧思维

“平台默认拿第一帧当封面” 这个认知,把” 要不要单独传封面图” 这个流程节点直接消掉了。产物是一个文件,不是两个。


六、和同类项目比:它站在哪

我按” 生成能力” 和” 工程化程度” 两个维度找了几类参照。

6.1 vs 闭源数字人 SaaS(Synthesia、HeyGen、Rephrase.AI 那一类)

digital-human-koubo 商业 SaaS
价格 按 Renoise credits 计(27 秒约 482,5 分钟约 3,400) 按分钟订阅,通常年付几千到几万
形象 自己的照片 + persona.json 自定义 平台模板库 + 少量定制
剪辑 Remotion 48 组件,完全可控 平台内置几套模板
数据 生成在 Renoise,剪辑全本地 全部上传到平台
上手 要装 ffmpeg /whisper/ Node / 连 MCP 网页打开就能用
门槛 高 低

结论:如果你要的是” 一次成片、不想折腾”,商业 SaaS 完胜。如果你出 5 条以上视频、或者要求每一帧可控,这个项目能给你 SaaS 给不了的东西。

6.2 vs 纯 Python 视频生成脚本(比如各种 SadTalker / Wav2Lip 封装)

  • 这类项目产出的是一段” 照片在动”,成片还得自己进 Premiere / DaVinci
  • 这个项目直接给你带花字、卡片、节奏、封面首帧的成片
  • 而且它不自己训模型,站在 Grok Video 1.5 / Wan 3.0 / OmniHuman / MiMo 之上做工程

用别人的模型,做自己的流水线。 这是 2026 年 AI 工具的典型形态:不卷基座,卷工程。

6.3 vs Remotion 模板库 / CapCut 模板

  • CapCut 模板:手工填,样式固定,改动受限
  • Remotion 官方模板:需要自己写 React,对非程序员门槛高
  • 这个项目:把 Remotion 包装成 agent 可调用的组件 + JSON 配置

多了一层” 从自然语言到 edit.json” 的翻译。

6.4 vs HeyGen 之类自带” 视频翻译 / 换语言” 的功能

这个项目的多语言是重新生成,不是配音替换。好处是口型对得上(模型自己生成语音 + 口型),坏处是每次都要重新生成,花 credits。

README 里的实测准确率(英 / 日 / 法 / 西 100%,韩 94%,阿 99%)是 whisper 回听准确率,翻译成 5 分钟多语言内容,仍然是几千积分的量级。

6.5 和同作者生态的关系

这个项目是”Agent Skill + MCP + 本地脚本 “这个范式的典型样本。同类还有 BrowserSkill(浏览器自动化)、teamai-cli(团队 AI harness),以及这个博客里写过的其他 Agent Skill 类项目。

共同点:agent 负责决策,脚本负责执行,文件负责传递状态。—

七、真实局限:别当银弹用

作者在 README 里写了不少,但我觉得还有几条值得单独拎出来说。

7.1 强依赖外部服务

  • Renoise —— 视频生成、报价、下载全靠它。Renoise 挂了、改价了、账号出问题了,整个流水线停摆
  • Grok Video 1.5 —— 当前默认模型。README 说 Wan 3.0、OmniHuman 也有文档,但主路径是 Grok
  • GPT Image 2.5 —— 场景图靠它
  • MiMo TTS —— 念错字修复、换音色靠它

作者把这些做成了可替换的(persona.json 里 engine 字段、model.name 字段),但替代方案没被同等验证。

7.2 本地依赖不轻

ffmpeg + Python + numpy/Pillow + Playwright + Chromium + Node 18+ + whisper.cpp + whisper 模型。Windows / Linux /macOS 三套装法。

“一键可用” 这个目标,这个项目没有达成。 它达成的是” 在愿意折腾的人手里,能稳定产出专业级成片”。

7.3 TextBehind 依赖 macOS

Apple Vision 人像分割,只有 macOS 能用。虽然 skill 里说了其余功能跨平台,但这是个明确的功能缺口。

7.4 数字人形象的一致性不是 100%

persona.json 里 reference_material: "material:329814" 是作者账号下的素材 ID。README 明确说:

本仓库里的 material: ID 属于作者账号,在你的账号上用不了 —— 这是预期内的。

也就是说你必须用自己的照片重新做一个形象。做新形象需要:选照片 → 让 agent 生成四视图(正 / 侧 / 侧 / 背,GPT Image 2.5 2k,约 23 credits)→ 上传拿 material id → 填进 persona.json。

这一步的成败直接决定后面所有视频的质量,而且四视图生成本身也不保证跨角度完全一致。

7.5 成本对个人创作者仍然不低

27 秒 482 credits,5 分钟 3,400 credits。这个量级下,“每周一条 5 分钟教程” 是需要认真算预算的。README 提到教程第 3 集复用了 17 段,” 复用” 是控制成本的关键手段,但复用也意味着形象和场景要保持一致,反过来限制了选题自由度。

7.6 Remotion 的 license 限制

项目是 MIT,但 Remotion 自己不是完全自由:个人和 3 人以下公司免费,更多要买 company license。作者在 README 里明确列了这条 —— 这是加分项,但公司用户要自己算账。

7.7 已知坑还没根治

README 的” 已知坑” 清单第一条就是 Grok 会烧字幕,“即使提示词写了也挡不住”。也就是说这条坑是靠重拍来解决的,不是被修掉的。

这意味着:核心体验里永远有一部分是” 抽到坏段 → 重拍 → 再花钱”。报价门让你不至于失控,但没法让你不难受。

7.8 生态绑定的开放性问题

SKILL.md 是开放的 Agent Skills 格式,脚本是普通 Python/shell,Remotion 模板是 React。技术上都是可移植的。

但 persona.json 里的素材 ID、material: 引用、--ref 指向的旧片段目录,都是 Renoise 账号相关的。你换账号,这套配置就得重做。


八、适合谁,不适合谁

适合

✅ 做系列口播内容的个人创作者 —— 48 个包装组件 + persona 固化 + --ref 跨集统一音色,都是为” 第 1 期到第 30 期” 设计的

✅ 有 Claude Code / Codex 的技术人 —— 这是一个 agent skill,不是 GUI 工具,你得习惯跟 agent 协作

✅ 小团队的内容 / 增长岗 —— 让一个人产出原本需要一个剪辑师的位置

✅ 想做数字人技术验证的人 —— 即使你不用它出片,unify.py 和 cutout_video.py 也是能单独拿出来复用的好东西

✅ 在意成本可控的人 —— 报价门 + 实盘成本表 + 复用段 + 局部修复,比大多数工具透明

不适合

❌ 完全不懂技术的运营同学 —— 需要装 ffmpeg / Node /whisper,还要能跟 agent 反复确认。一键出片的期望要放一放

❌ 只想偶尔做一条的人 —— 27 秒 482 credits + 半小时折腾环境 + 做自己形象,性价比不如买 SaaS 月费

❌ 需要严格品牌规范的企业 —— 48 个组件是” 头部博主的通用包装”,不是你的品牌设计系统。虽然 pack 数组可改,但要做到规范统一,得自己写组件

❌ 对 AI 内容有合规红线的行业 —— 项目本身有明确要求(标” 内容由 AI 数字人演绎”、只用有授权的脸和声音、不用网络梗和影视片段),但这个” 合规” 是作者自我约束,不是法律保证。所在行业有额外规定的,请自己再过一遍

❌ Windows 用户想用 TextBehind —— macOS 限定 | 期待完全离线的人 —— 生成环节必须走 Renoise 云服务


九、我的评价

作为一个项目,andyhuo520/digital-human-koubo 有三点我觉得明显高于同类:

第一,它把” 提示词工程” 落到了” 约束前移”。
大多数人在” 模型输出的效果不够好” 这件事上的反应是” 改改 prompt 再试试”。这个项目的做法是量出 480p 是 400×736、量出齿音段间差 13.2 dB、量出 4:43 里 44 段累积落后 0.38 秒,然后把结论写进生成条件或写进校验脚本。这是从” 用模型” 到” 工程化使用模型” 的分水岭。

第二,它对成本的敏感度是真实的。
“先报价再扣费”” 先出 1 段再批量”” 复用上一期的段对齐音色”” 只换出错那一句不重拍整片”” 别整片重配音”—— 这些不是产品文档话术,是被 bills 教过的人才会写下的规则。

尤其 “别整片换音色,口型跟的是原声” 这一句,一句话点破了大多数 AI 配音方案的根本矛盾。

第三,它没有假装自己是模型。
它就是一个编排层:上面是 agent(决策),中间是脚本(执行),下面是一堆第三方模型(生成)。模型换一代,它可能要改;模型不换,它照样能用。这个定位很清醒。

它的短板也很明显:门槛高、依赖外部、成本对个人不算低、部分功能有平台限制、核心体验里永远有一部分是” 抽到坏段重拍”。

但我更想说的是 —— 它展示了一种可能性:

当 agent 的能力足够强,” 领域经验” 就可以被写成 SKILL.md + 一堆 Python 脚本,然后被复用到任何一个能加载 skill 的 agent 上。

SKILL.md 里的红线、看稿子、质检、报价、混音那一套,本来是作者脑子里和剪辑师聊天才能学到的东西。这个项目把它固化成了可执行的形式。

你不需要它的任何一条 demo,你只需要看一眼这个仓库的 SKILL.md 和 scripts/ 目录,就会意识到 —— 很多我们以为” 只能靠人传” 的经验,其实可以写下来。

这可能比它生成的任何一条视频都更有价值。


十、试试看

如果你想试:

1
2
3
git clone https://github.com/andyhuo520/digital-human-koubo.git
cd digital-human-koubo
mkdir -p ~/.claude/skills && cp -R skills/digital-human-koubo skills/finance-explainer ~/.claude/skills/

然后连上 Renoise MCP,跑一遍:

1
bash ~/.claude/skills/digital-human-koubo/scripts/doctor.sh

确认环境没问题,再跟 agent 说一句” 用我的数字人 Skill 讲这段:……”。

但是,别一上来就做 5 分钟的。先做一条 27 秒的竖屏试试水 —— 就像作者 README 里那个 482 credits 的直播广告 demo。先看看音色对不对、齿音在不在、包装组件是不是你想要的风格。

先花小钱验证,再决定要不要规模化。 这也是这个项目自己教你的第一条规矩。


项目地址:https://github.com/andyhuo520/digital-human-koubo

如果这篇对你有用,欢迎点个 star。 作者 Berryxia 用 Claude Code 写出来的这个仓库,值得被更多人看见。

参考资料

  • andyhuo520/digital-human-koubo —— 仓库、README、SKILL.md、persona.json
  • scripts/voicefx/unify.py —— 音色统一・scripts/rangedl.py —— 分段并发下载・scripts/patch_words.py —— 局部念错修复
  • Remotion —— 视频渲染框架・Renoise —— AI 视频 / 图片生成 MCP・whisper.cpp —— 语音识别