talking-head-video

Turn a raw 口播 / talking-head selfie video + its script into a finished explainer — vertical 9:16 or landscape 横屏 16:9 — synced burned-in subtitles, animated knowledge-graphic segments, and a circular picture-in-picture avatar that shrinks the speaker into the top-left while a chart / data-card / diagram fills the screen during explanations.

This is a Claude Agent Skill. Drop it in and ask, in plain language, to "把这段口播剪成成片，加字幕和动态讲解图" — the agent runs the whole pipeline.

full face ──┐         ┌── graphic full-frame + circular avatar top-left ──┐         ┌── full face
            │  cross  │   ("knowledge window")                            │  cross  │
   subtitles burned over EVERYTHING, the whole time

What it produces

• Vertical 1080×1920(视频号 / 抖音 / Shorts)or Landscape 1920×1080(B站 / YouTube / 知识科普)
• Burned-in subtitles, timed by faster-whisper and corrected against your verbatim script (no more mis-heard brand names / 同音字)
• Animated knowledge graphics built with Remotion in a dark "premium / scientific" design system — six reusable archetypes: image+callout, data cards, before/after comparison, flow diagram, big-number reveal, key-point list
• Circular PiP avatar of the speaker, top-left, only during explanation beats

⚠️ 使用约定:画幅和图卡风格,先问用户

开工前,Skill 会先向你确认两件事,给出推荐但由你拍板,不会默默替你决定:

1. 画幅:横屏 16:9 还是竖屏 9:16(通常跟随源视频);
2. 图卡风格:讲解画面用哪种风格,三选一(见下节)。

两种画幅都是一等公民,各自的参数集:

参数	竖屏 9:16 (1080×1920)	横屏 16:9 (1920×1080)
头像直径 / 位置	300px / 40:120	380px / 44:44
字幕	PlayRes 1080×1920, MarginV 210	generate_subs.py --land(1920×1080, MarginV 90)
头像脚本	make_avatar.sh SRC OUT CROP RING 300	make_avatar.sh SRC OUT CROP RING 380
图形安全区	左上头像 + y≳1540 字幕带	左上头像(x<470, y<470)+ 底部字幕带

🎨 三种图卡风格(内置)

风格	一句话	适合	字体(随仓库附带,全免费)
darkcard 深色科技卡(默认)	深底、辉光、边框卡片、大数字	价格/参数/对比/新闻/评测	得意黑 + DIN Condensed + PingFang
watercolor 纸上水彩	米黄纸、水彩物件、铅字标题、物理点睛	生活类比/故事感/章节卡	汇文明朝体 + Special Elite
inkline 白纸简笔	纯白、细黑线"画出来"、大字+灰注、诗意收尾	原理/定义/一句话洞察	霞鹜文楷 Light/Bold

• 工艺规范与选择速查:references/styles.md;darkcard 六个 archetype:references/design-system.md
• 三风格完整示例(同一概念「边际成本」三种表达):assets/remotion/src/examples/
• 也可不带源视频单独出卡:知识卡/概念卡/章节卡,6 秒无声,16:9 或 9:16,可输出透明 PNG 序列叠加

字体与授权:随仓库分发的均为免费字体——思源宋体 Heavy、霞鹜文楷、得意黑(SIL OFL)、汇文明朝体修正版(免费)、Special Elite(Apache 2.0)。Anthropic Serif/Sans(Claude 官方字体)不在仓库内,scripts/setup_fonts.sh 会在本机装有 Claude 桌面端时自动拷入作混排回落,没有则优雅降级。

How it works

1. Transcribe the audio to word-level timings (scripts/transcribe.py, faster-whisper). Trust the timing, not the text.
2. Segment map — decide which time windows become knowledge graphics vs stay full-face (let the face carry the hook and conclusion). See scripts/segments.example.json.
3. Graphics — copy the closest archetype in assets/remotion/src/, rewrite its content, render to ProRes 4444 (alpha) so edges crossfade onto the face (scripts/render_graphics.sh).
4. Avatar — circular alpha PiP, crop tuned so the whole head + chin fits (scripts/make_avatar.sh).
5. Subtitles — ASR → corrected styled .ass (scripts/generate_subs.py; edit the per-video CORRECTIONS list).
6. Composite — scripts/build_composite.py reads a segments.json and emits the ffmpeg filtergraph: graphics overlaid in their windows + avatar top-left + subtitles burned + original audio untouched (perfect sync).

Full step-by-step is in SKILL.md; design tokens, geometry, and the archetype catalog are in references/design-system.md.

Prerequisites

• ffmpeg with libass + prores_ks (Homebrew ffmpeg has both)
• faster-whisper: python3 -m pip install faster-whisper
• Node + Remotion: cd assets/remotion && npm install
• A CJK font libass can find (macOS PingFang SC works out of the box)

Install as a Claude skill

Option A — import the packaged skill: download talking-head-video.skill and import it in Claude.

Option B — drop in the folder:

git clone https://github.com/Vibetool/talking-head-video.git \
  ~/.claude/skills/talking-head-video

Then just describe what you want; the skill triggers on 口播 / 讲解 / 知识科普 short-video editing requests.

Repo layout

SKILL.md                     workflow + conventions (the entrypoint)
references/design-system.md  palette, geometry, archetype catalog
scripts/                     transcribe · subtitles · avatar · render · composite
assets/remotion/             design system (theme.tsx) + 6 archetype components
talking-head-video.skill     prebuilt importable package

License

MIT © Vibetool