changelog-video

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog → Branded Video

更新日志 → 品牌化视频

Input: a changelog .md (themes + items, like the weekly HyperFrames digest). Output: a lint-clean, seam-gate-green HyperFrames project in

projects/active/weekly-changelog-<range>/

. Render only when asked.

Load first, non-negotiable:

motion-doctrine

cut-the-curve

oversized-cursor

if a cursor appears,

seam-craft

) and

captions-overlay

. This skill supplies the changelog-specific pipeline; the doctrine supplies the motion law.

输入：更新日志.md文件（包含主题与条目，例如每周HyperFrames摘要）。输出：一个无语法错误、seam-gate检测通过的HyperFrames项目，存储于

projects/active/weekly-changelog-<range>/

。仅在用户要求时进行渲染。

必须优先加载：

motion-doctrine

（若出现光标则额外加载

cut-the-curve

、

oversized-cursor

以及

seam-craft

）和

captions-overlay

。本技能提供更新日志专属处理流程；doctrine提供动效规则。

The prime directive: visualize, don't list

核心准则：可视化呈现，而非罗列

Every theme is illustrated by an animated mock of the actual UI or a faithful analog acting out the change in experience — never text bullets. Route every theme/item through

references/visualization-registry.md

BEFORE writing the script; the registry decides ui-recreate / ui-analog / terminal / checklist. Text checklist is the LAST resort, reserved for genuinely non-visual items (reliability fix lists).

每个主题都需通过实际UI的动画模拟或忠实的替代界面来展示体验变化——绝不能用文本项目符号。在编写脚本前，务必将每个主题/条目对照

references/visualization-registry.md

进行匹配；该注册表会决定采用复刻UI/替代UI/终端/清单哪种形式。文本清单是最后选择，仅用于完全无法可视化的条目（如可靠性修复列表）。

Pipeline

处理流程

1 · Parse + editorial cut

1 · 解析与编辑剪辑

Extract: week range, headline stats (releases, commits), themes, items.
Budget: 45-60s total. Title ≤2s, outro ≤3.5s, 4 themes ≈ 9-12s each.
Per theme keep ONE hero visualization + at most 3 spoken items. Everything else exists only as the outro's "full digest" pointer. Cutting is the job: a changelog with 30 items still yields ≤14 spoken beats.
Order themes by story: marquee feature → product surface → performance → reliability (the digest usually already reads this way).

提取：周范围、核心统计数据（发布版本、提交次数）、主题、条目。
时长预算：总计45-60秒。标题≤2秒，片尾≤3.5秒，4个主题每个约9-12秒。
每个主题保留1个核心可视化内容+最多3个语音播报条目。其余内容仅作为片尾“完整摘要”的跳转链接。剪辑是关键工作：即便更新日志有30条条目，最终语音播报节拍也需≤14个。
按叙事逻辑排序主题：重磅功能 → 产品界面 → 性能优化 → 可靠性修复（通常摘要本身已遵循此顺序）。

2 · Visualization routing

2 · 可视化匹配

For each theme, pick the surface from

references/visualization-registry.md

and write one line:

theme → surface → the 2-4 sequenced actions the mock performs, each tied to a script phrase

. If no registry surface fits and no faithful analog exists, it's a checklist scene — don't invent fake UI for something we can't represent honestly.

针对每个主题，从

references/visualization-registry.md

中选择对应界面，并编写一行内容：

主题 → 界面 → 模拟界面执行的2-4个连续操作，每个操作对应脚本中的一句话

。若注册表中无匹配界面且无合适替代方案，则采用清单场景——切勿为无法真实呈现的内容虚构UI。

3 · Two-layer script (spoken vs display)

3 · 双层脚本（语音播报 vs 显示文本）

Write the script as token lines per

references/script-voice.md

: conversational register, every technical term carrying a

spoken

phonetic form from

references/lexicon.json

while

display

keeps standard spelling. Captions show

display

; the VO reads

spoken

. Any term not in the lexicon: STOP and ask the user how it's pronounced, then add it to the lexicon. Save as

script-tokens.json

in the project.

按照

references/script-voice.md

的要求，将脚本写成令牌行：采用口语化风格，每个技术术语需携带

references/lexicon.json

中的

spoken

音标形式，而

display

保留标准拼写。字幕显示

display

内容；语音旁白读取

spoken

内容。若词汇表中未收录某术语：立即停止并询问用户发音方式，随后将其添加至词汇表。将脚本保存为项目中的

script-tokens.json

。

4 · VO — Annie (HeyGen, pinned)

4 · 语音旁白 — Annie（HeyGen，固定使用）

bash

undefined

bash

undefined

spoken-layer text only; words JSON = ground-truth timestamps of the SPOKEN text

仅包含语音层文本；words JSON为语音文本的真实时间戳

Repo-native path: the changelog-video skill runs from the hyperframes repo root,

仓库原生路径：changelog-video技能从hyperframes仓库根目录运行，

so it uses the tracked hyperframes-media TTS helper directly (no `npx hyperframes

因此直接使用已追踪的hyperframes-media TTS工具（无需执行`npx hyperframes

skills` install step). If you've copied the skill into another repo, swap in

skills`安装步骤）。若你已将该技能复制到其他仓库，请替换为你自己的media-use / hyperframes-media heygen-tts.mjs路径。

your own path to the media-use / hyperframes-media heygen-tts.mjs.

—

node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt
-o voiceover.mp3 --words vo-words.json
--voice 330290724a1b470fb63153f34d4c0183 # Annie — lifelike (do not substitute)


Requires `heygen` CLI ≥0.3.0 authenticated (`heygen auth login --oauth`).
Then align spoken timestamps back to display tokens:

```bash
node <SKILL_DIR>/scripts/align-captions.mjs \
  --tokens script-tokens.json --words vo-words.json --out captions.json

captions.json

is the caption-rail input (display spelling, spoken timing). The aligner prints

MISMATCH

warnings — resolve every one before building (usually a lexicon spelling the TTS renders as multiple words). The audio is the clock: all beat times come from

vo-words.json

; a VO regen re-opens every seam.

node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt
-o voiceover.mp3 --words vo-words.json
--voice 330290724a1b470fb63153f34d4c0183 # Annie — 拟真音色（请勿替换）


要求`heygen` CLI ≥0.3.0且已完成认证（`heygen auth login --oauth`）。随后将语音时间戳与显示令牌对齐：

```bash
node <SKILL_DIR>/scripts/align-captions.mjs \
  --tokens script-tokens.json --words vo-words.json --out captions.json

captions.json

是字幕轨道的输入文件（包含显示拼写、语音时间戳）。对齐工具会打印

MISMATCH

警告——在构建前需解决所有警告（通常是词汇表中的拼写导致TTS拆分为多个单词）。音频是基准时钟：所有节拍时间均来自

vo-words.json

；重新生成语音旁白会打破所有时间同步。

5 · Build

5 · 构建

references/build-spec.md

exactly: brand tokens + fonts (bundled in

<SKILL_DIR>/assets/

), the animated background encode, scene scaffold, chrome, caption rail, one rationed green moment per scene. Then the doctrine order:

ledger.json

(all ordinary seams cut-the-curve LEFT) → seam-stamp → internal beats on VO words → seam-gate verify.

严格遵循

references/build-spec.md

：品牌令牌+字体（包含在

<SKILL_DIR>/assets/

中）、动态背景编码、场景框架、界面元素、字幕轨道、每个场景仅保留一处绿色高亮（#5ef17c）。然后按照doctrine顺序执行：

ledger.json

（所有常规接缝采用cut-the-curve LEFT）→ seam-stamp → 基于语音单词的内部节拍 → seam-gate验证。

6 · Gates (all green before presenting)

6 · 检测门限（全部通过后再交付）

```
bun run --cwd packages/cli hyperframes check
```
(or the installed
```
hyperframes
```
CLI from the repo-local
```
skills/hyperframes-cli/
```
skill) — 0 errors (contrast: dim text ≥ .66 alpha). Do NOT reach for
```
npx hyperframes@latest
```
; the tracked repo-local CLI is the source of truth for the composition contract this skill produces against.
```
seam-gate.mjs verify
```
— 0 fail.
Restart the preview server (it caches the bundle), spot-check 3-4 beats via
```
__player.seek
```
on the raw comp page.
Do NOT render unless the user asks. After a requested render, verify frames from the MP4 (
```
ffmpeg -ss <t> … -frames:v 1
```
): captions present, background video not black, no tiny/frozen frames.

```
bun run --cwd packages/cli hyperframes check
```
（或使用仓库本地
```
skills/hyperframes-cli/
```
技能中已安装的
```
hyperframes
```
CLI）——0错误（对比度：暗文本透明度≥0.66）。请勿使用
```
npx hyperframes@latest
```
；仓库本地追踪的CLI是本技能生成成果需遵循的合成协议的唯一可信来源。
```
seam-gate.mjs verify
```
——0失败。
重启预览服务器（它会缓存打包文件），通过原始合成页面的
```
__player.seek
```
随机检查3-4个节拍。
仅在用户要求时进行渲染。完成请求的渲染后，验证MP4中的帧（使用
```
ffmpeg -ss <t> … -frames:v 1
```
）：字幕存在、背景视频无黑屏、无极小/冻结帧。

Project layout

项目结构

projects/active/weekly-changelog-<range>/
├── index.html            # single-doc master (scenes as slides, stamped seams)
├── ledger.json           # vector ledger (seam-stamp input)
├── script-tokens.json    # two-layer script (source of truth for VO + captions)
├── vo-spoken.txt         # generated: spoken layer, one line
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3               # copy from <SKILL_DIR>/assets/bgm.mp3 (the house track) unless the user supplies one
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4

projects/active/weekly-changelog-<range>/
├── index.html            # 单文档主文件（场景作为幻灯片，已标记接缝）
├── ledger.json           # 矢量账本（seam-stamp输入文件）
├── script-tokens.json    # 双层脚本（语音旁白与字幕的可信来源）
├── vo-spoken.txt         # 生成文件：语音层内容，单行格式
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3               # 从<SKILL_DIR>/assets/bgm.mp3复制（默认背景音乐），除非用户提供自定义音乐
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4

Anti-patterns

反模式

Don't	Instead
Bullet-point slides for UI changes	Mock the surface acting out the change
Fake UI for un-representable items	Honest checklist scene
Plain "JSON"/"CLI" in the TTS text	Lexicon spoken forms; display stays standard
Phonetic spellings in captions	Captions always render the display layer
Guessing an unknown term's pronunciation	Ask, then grow the lexicon
Speaking every changelog item	≤3 per theme; the digest link carries the rest
Green accents everywhere	One green moment per scene (#5ef17c)

禁止做法	正确做法
用项目符号幻灯片展示UI变更	模拟界面来演示变更效果
为无法呈现的内容虚构UI	使用诚实的清单场景
TTS文本中使用普通的"JSON"/"CLI"表述	使用词汇表中的语音形式；显示文本保留标准拼写
字幕中使用音标拼写	字幕始终显示标准文本层内容
猜测未知术语的发音	询问用户，然后更新词汇表
播报更新日志中的每一条条目	每个主题≤3条；剩余内容通过摘要链接展示
随处使用绿色高亮	每个场景仅保留一处绿色高亮（#5ef17c）