Communitygithub.com

Video Boost(口播增強)

將一支單人口播影片(9:16 直式,30 秒至 5 分鐘)製作成「原片 + 同步圖形層」的成品——不更動原片畫面、聲音與時長,僅疊加卡拉 OK 字幕、進度標、機制圖、真實工具介面、結尾 CTA 及運鏡效果。

Video Boost(口播增強) 是什麼?

此技能為一支單人口播影片增添同步圖形層,包含卡拉 OK 字幕、進度標示、機制圖、真實工具介面截圖及結尾行動呼籲。它嚴格遵循「只加不改」原則:原片畫面、聲音、時間軸與時長完全保留。此技能支援 HyperFrames 與 GSAP 動畫,並內建完整素材評級制度——從真實來源(新聞、報告、產品介面)到客製化示範元件,確保每個圖形都提供額外資訊,而非重複口播內容。此技能還包含自動化流程(語音辨識、對齊、字幕修復、渲染與評分),以及一套完整的品質評估系統,包含 23 項自動檢查。主題系統允許在不同設計語言間切換(如 Knock 或私有品牌主題),而運鏡規則(全螢幕、分割畫面、慢推、硬切放大)確保觀看體驗流暢。最終交付前必須通過所有評估門檻,並附上自動評分與可接受的警告說明。

相容平台✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/Minerva67/video-boost/tree/HEAD/skill/video-boost

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Video Boost(口播增強) 是做什麼的?

工程目錄:倉庫根目錄(公開倉庫 github.com/Minerva67/video-boost;本機在 ~/CC/knock-video-boost/)。HyperFrames 渲染 + GSAP 時間軸 + 自建元件庫。 範本:runs/example/beats.mjs(結構樣板)+ references/components.md(每個元件的資料寫法)。判斷規則全在 references/rules.md(負荷類型、劃段、版式輪換、樣板入場順序、小標題),不依賴任何外部文件。

鐵律(使用者反覆確認過的,違反即返工)

  1. 只加不改:原片畫面、鏡頭順序、時間軸、原聲、時長全部不變。CTA 也是疊在最後幾秒,不加長片子。
  2. 卡片不許複述口播。每張圖過一遍測試:「關掉聲音和字幕,這張圖多給了什麼?」答案是「同樣的字」就刪。字幕已經在說話了,卡片再寫一遍 = 三重重複(v4 被否的原因)。
  3. 能演出來就別寫出來,能拿到真東西就別演:口播提到真實存在的新聞/報告/產品/地方,優先放真實截圖或照片(photo 元件,劃出那個數字);口播提到「用 X 工具做了 Y」,就把 X 的真實介面和 Y 的產出物演出來(Claude Code 會話逐字打指令→工具呼叫→結果表/報告),不要灰條佔位(v5→v6 被點名要求)。
  4. 示意 ≠ 編造:允許示意介面(視窗角標「示意」),但不加原片沒說的觀點;任何數字/來源必須真實檢索(WebSearch+WebFetch 核實頁面原文;多家口徑不同就寫區間並都標出),範例標題類內容不帶熱度/點讚數字。
  5. 不擋臉、不擠:人永遠貼底居中——全螢幕 / 62%(普通圖形)/ 50%(資訊密的圖形,使用者 10-02 要求「資訊量大就把人放小,多留地方做可視化」)。子母畫面(人縮到 30% 角落)被否。
  6. 皮膚 = 主題(theme),預設使用者自己的 Knock〃 設計系統 B 線密度(brand/themes/knock/);也有私有主題(brand/themes/<私有主題>/,按品牌規範 B 線)。換主題:node build.mjs runs/<name> --theme=<name>(輸出到 public-<theme>/)。Knock 版細則:紙白打底、門黃只做小色塊、敲擊橙 ≤5%、1.5px 墨黑描邊、無陰影;右上角橫版 logo 常駐。Claude 風格皮膚被否("設計系統還是用我的"),Knock 三色大面積鋪屏也被否("太鮮豔很累")。
  7. 拆分邏輯:六類負荷 + 複合類型 + 相鄰段不同版式 + 旁支不增強,規則見 references/rules.md §1–2(源自使用者的影片增強 PRD V3 與《可視化選型規範 · 30 樣板》,已摘全)。低負荷的勸導/觀點類口播,大部分時間應該回到全螢幕,只留 4–6 個圖形。

流水線

./prep.sh <影片檔案> <name>                      # 拷源片(HDR 自動 avconvert 轉 SDR)、抽音訊、medium 模型 beam5 轉錄、按標點重切段
# → 讀 runs/<name>/segs_beam.json,校對寫 runs/<name>/script.txt(| = 字幕斷點)
.venv/bin/python align.py runs/<name> <時長>       # 校對文字對齊回 ASR 字級時間 + VAD 校時 → transcript.json / captions.json / voiced.json
.venv/bin/python fix_caps.py runs/<name> <時長>    # 自動合併 <1s 或 >9字/s 的字幕屏,重對齊(不跨章節/句子/停頓合併)
# → 先寫 runs/<name>/structure.md(論證結構)→ cut.md(剪輯臺本)→ 再寫 beats.mjs(從 runs/example/beats.mjs 複製改)
# 真實素材:node grab.mjs <網址> runs/<name>/assets/x.png --find "關鍵句";python3 commons.py "<英文關鍵詞>" runs/<name>/assets
node build.mjs runs/<name>
npx hyperframes lint runs/<name>/public            # 0 error 即可(caption 的 nested 警告是已知的)
HYPERFRAMES_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  npx hyperframes render runs/<name>/public --sdr -q draft -o runs/<name>/draft.mp4   # 156s ≈ 100s
./review.sh runs/<name>/draft.mp4 <每段末尾的時間點…>   # 出聯繫表,逐張看
# → 剪輯師審片:派獨立子 agent,只給聯繫表 + cut.md,按 references/editor.md §5 逐段「過 / 打回」;打回的改完複審
# 修完 → 去掉 -q draft 出正式版 output.mp4
./evaluate.sh runs/<name> [--theme <主題>] [--platform xhs]   # 最後一步:Eval(測字號/安全區 + 23 項自動檢查)→ runs/<name>/eval.md
# 門檻不過不交付;WARN 逐條判斷能修就修、修完重跑;通過後 → 拷到 ~/Desktop/口播增強_<版本>_<主題>.mp4 → SendUserFile

每一支片子都以 Eval 收尾,交付訊息裡必須寫:門檻是否通過、自動分、剩下的 WARN 以及為什麼可以接受。

環境:ffmpeg/ffprobe 在 ~/.local/bin;whisper 模型 ~/.cache/kvb-models/ggml-medium-q5_0.bin(被清盤刪過一次,prep.sh 會自動重下,515MB);渲染用系統 Chrome。

校對 script.txt 的要點

  • 先看 prep 的兩項輸出:①「ASR 覆蓋檢查」,漏句要逐條重轉補進稿子;②「源片自帶燒錄字幕」,檢測到就預設關掉我們的字幕(見 rules.md §8)。
  • 格式:| 是換屏;句子結束處寫 。,它只當邊界、不顯示;問號、驚嘆號照常保留;其餘標點不寫。
  • 只改錯字、不改說法;去氣口(嗯/呃)可以,不潤色不補詞。專名按真名寫(ClockCode→Claude Code,Codeash→Codex)。
  • 聽不清的詞:.venv/bin/python retranscribe.py runs/<name> <起> <止> --terms "3–5 個本段術語",會給出原速、加術語、0.8 倍慢放三種結果。仍不確定的,交付時帶時間列給使用者聽。
  • 斷屏:直式 ≤10 字/屏(拉丁字母算半個),在語義停頓處斷;專名、數字+單位不拆;不以掛空的「的/和/在」結尾。語速快時 fix_caps 會在不跨句的前提下合併,上限 14 字。

主題(換設計系統)

元件裡不寫死任何顏色,全部走角色(brand/themes/<name>/theme.json):

角色用途Knock私有主題
paper / card畫布 / 卡片紙白 / 白Gray50 / 白
ink · ink70 · ink40正文三級灰墨黑系Gray900/700/500
line · lineSoft分割線石灰Gray300/100
mark + markInk點亮態填充(目前項、勾、進度標)門黃Tappy Green
accent一屏一處的強調(終點框、指令符、關鍵詞)敲擊橙Signal Purple
frame · stroke · shadow · radius卡片邊框/陰影/圓角1.5px 墨黑描邊、無陰影、181px 淺灰邊+極淡陰影、16
fontCn / fontEn / fontMono + fonts[]字型(本機 ttf,渲染不聯網)OutfitPlus Jakarta Sans / Inter / JetBrains Mono
logo · logoPill右上角 logo,是否套膠囊套裸放
caption.style字幕:pill 膠囊卡拉 OK / stroke 白字黑描邊pillstroke(私有主題 PRD V3 字幕規範)

接一個新設計系統的步驟:①讀它的規範,找 B 線/產品 UI 密度那一檔(影片疊層要克制,行銷 A 線的大色塊不要搬);②把品牌色分配到 mark(大面積點亮也不刺眼的那個)和 accent(只出現一處的那個),飽和品牌色寧可降成 mark 也別鋪底;③字型下 OFL 版放進主題目錄;④建 theme.json → build → 跑 eval + 人工 H4/H6;⑤白底亮髮等場景檢查字幕可讀(stroke 風格要加粗描邊)。

寫 beats.mjs:先判斷,再選元件

第零步:先理結構,再寫小標題

通讀全文,寫出 runs/<name>/structure.md:論點、結構類型(路徑 / 框架 / 並列 / 問題→解法 / 對比)、每段的角色和結論。小標題 = 角色詞 · 結論(≤12 字),連起來讀應該就是論證本身。不要一段一段單獨起名,那樣寫出來的話題標籤(使用者兩次否掉)。細則和樣例見 references/rules.md §4。

第一步:剪輯臺本——先想「剪輯師在這裡會切到什麼畫面」(最重要,見 references/editor.md)

先寫 runs/<name>/cut.md,再寫 beats.mjs。逐段填:口播在講什麼 → 功能(解釋 / 證明 / 重置注意力,都不是就不加圖)→ 剪輯師會切到的畫面 → 素材等級 → 為什麼不用更高一級。

  • 素材等級從高往低找:①真實素材(新聞/官網截圖、真實照片、真實介面,用 grab.mjs / commons.py 取,photo 元件放)→ ②示範(cc / folio / resume / checktable)→ ③資料圖 → ④文字卡。選 ③④ 必須寫出具體理由。
  • 口播提到一個真實存在的東西(新聞、報告、公司、產品、地方、人群),先試 ①。
  • 一個畫面只講一件事,按口播順序逐項進入;出現空格子、整張表一次性擺出來、大片留白,就要拆或者換素材。
  • 只是觀點、過渡、情緒、口頭總結 → 全螢幕,不加圖(可以慢推)。全片 4–6 個圖形就夠。

第二步:元件選型

素材等級定了,再挑元件。第 ③④ 級按內容形狀查 references/rules.md §6 的表;元件寫法見 references/components.md。

  • 全片有「N 點」結構時,進度標由 build 根據 CH + TRACK 自動生成。
  • cc 能演任何「指令 → 步驟 → 產出」的軟體操作,不限於 AI 工具。
  • 口播出現「留言 / 關注 / 私訊」時,用 cta。
  • 庫裡沒有合適的元件:按 components.md 末尾的「新元件清單」新寫一個。
  • 用口播外的真實資料,先看 rules.md §7 的邊界。

HyperFrames 官方目錄(npx hyperframes catalog)有 tiktok-follow / yt-comment-card / claude-exchange / chatgpt-exchange / code-typing 等現成塊,但自帶平台配色和假帳號/假評論/假點讚——只借動作,換 Knock 皮,不用假社交證明。新元件寫進 components.mjs + brand/components.css,入場順序遵循 references/rules.md §2;寫法清單見 references/components.md 末尾的「新元件清單」。

字號(不按感覺定)

所有圖形文字只用 6 檔字號:hero 140 / display 96 / title 54 / body 36 / small 28 / micro 22,字幕 76 是畫面裡最大的閱讀文字。一個圖形最多 3 檔;dense 不放大字號。規範、業界依據和平台安全區見 references/typography.md,由 Eval 的 T1–T5、S1 實測檢查。

動效素材庫(只用能掛到 GSAP 時間軸上、能逐格對齊的)

  • GSAP 全套外掛(2025 年起免費,可商用;已在 node_modules 裡,build 自動載入):DrawSVG 線條描畫,MorphSVG 形狀變形(比如「修補」碎裂),MotionPath 沿路徑運動(比如逃逸軌道的 escape 元件)。
  • rough.js(MIT):手繪圈注。beat 上寫 annot: [{ sel, kind: 'circle'|'underline'|'box'|'strike', at }];路徑用固定種子在 Node 裡生成,每次渲染都一樣;只給結論用,每個圖形 ≤2 處。
  • HyperFrames 官方元件目錄(Apache-2.0):只借動作,換成本主題的皮膚。
  • 可以用但有限制:Lottie 免費動畫可商用,但不能再分發原檔案,只能留在本機,不進公開倉庫。不用:純 CSS 動畫庫(不能逐格對齊)。

品牌 logo / 圖示(真實的,不手畫)

圖形裡一出現產品/公司名,就在名字前加真 logo:文字裡寫 :openai: ChatGPT,md() 會內聯 brand/icons/openai.svg。

  • 取圖:./fetch_icons.sh openai gemini google claudecode codex deepmind …(Lobe Icons,MIT;si:xiaohongshu 走 Simple Icons,CC0);來源記在 brand/icons/SOURCES.txt。
  • 一律用單色版(繼承主題 ink 色):彩色 logo(Gemini 漸變、Google 四色)會破壞「強調色一屏一處」。
  • 名字和 logo 要對得上真實歸屬(Veo 用 DeepMind 標);庫裡沒有的品牌就只寫字,不拿近似圖示湊。
  • 只做指代(誰的產品),不暗示合作/背書。

第三步:時間

所有時間用 t('…原話…') 從校對稿裡取(不手填秒數),圖形元素在關鍵詞被說出的那一刻出現;指令類文字逐字打出(dur 大約等於那句話的長度)。

運鏡規則(寫在 beats.mjs 的 CAM 裡)

佈局什麼時候參數
full 全螢幕人是內容:鉤子、觀點、過渡、「從前怎麼做」的敘述、收尾、CTAs 1
split 讓位只在圖形承載資訊時;兩段圖形間隔 < 4s 不回全螢幕(避免一縮一放)s .62 貼底
dense 密集資訊密的圖形(表格 ≥8 行、清單 ≥6 項、示意會話/報告/履歷),beat 上寫 dense: true;多出來的空間用 below 放第二層可視化,不是放大字體s .50 貼底居中,圖形區 760px(見 rules.md §5)
push 慢推關鍵判斷、定義、回顧到片尾1.00→1.06,d 5–9s
punch 硬切放大只給鉤子金句,換章時硬切回s 1.14,d 0;貼臉自拍用 beats 裡 LAYOUT.punch 降到 1.07

讓位(split)用 snapBefore():只往前找停頓,保證人先開始讓位、圖形後入場(build 會對違反的圖形報警,Eval C6 檢查)。其餘移動用 snap() 吸到說話停頓(voiced.json 的間隙;±0.7s 找不到就放寬到 ±1.4s;語速快到完全沒停頓時退到最近的字幕斷點),鏡頭不在詞中間動;split 的落位要早於圖形入場。

Eval(交付前必跑)

流水線最後一步 ./evaluate.sh runs/<name>(內部先跑 node audit.mjs 實測字號與位置,再跑 python3 eval.py)→ eval*.md:門檻 A1–A5(不過不交付)+ 自動 B1–B6/C1–C5 + 人工 H1–H6 評分表。標準、閾值、出處、基線分見 references/eval.md。交付時報:門檻是否通過、自動分、主要 WARN 及是否屬於可接受的判斷項。

交付前自檢(看 review 聯繫表,每段末尾一幀 + 每個示意介面 3–4 幀)

  • 有沒有卡片在複述字幕?有就刪。
  • 字/元素有沒有出界、壓進字幕帶(y 1520–1670)、遮臉?
  • 示意介面:空容器是否先於內容露出(要整塊淡入)?長內容是否自動上滾?數字有沒有出處?
  • 進度標對不對(目前點/已完成/回顧全勾)?
  • 時長 = 原片(ffprobe 對一下)。

交付話術:說清每個圖形在哪一秒、給觀眾多了什麼;哪些是示意、哪些是真實檢索(附來源連結);還要使用者聽一下的不確定字。

已知坑

  • iPhone/可立拍原片常是 HLG HDR:只改色彩標籤會膚色發黃,用 avconvert -p Preset1920x1080(prep.sh 已處理);渲染加 --sdr。
  • Whisper 會把片頭靜音時間拉向 0 → align.py 的 VAD 校時處理;長段無標點 → resegment.py。
  • 不能在 class="clip" 元素上動 opacity,出場動畫打在內層;GSAP 時間軸必須 paused 並掛 window.__timelines["main"]。
  • 在 Python 裡改 components.mjs 時 '\n' 會被轉義成真換行導致 JS 語法錯——用 '\\n'。
  • GSAP 不能動 left/top(lint 報 gsap_non_transform_motion)——用 x/y,需要寬度就在頁面腳本裡量 clientWidth。
  • 樣板字串 ${} 在 Node 裡求值,別在裡面寫 document.*(要放進輸出的 JS 字串裡)。
  • 刪除 review 幀別用 rm 萬用字元(會被安全檢查攔);直接覆蓋寫同名檔案。

版本史(口味演進,別回頭)

v1 Knock 三色鋪屏 + 子母畫面 → 否(太豔、擋臉)|v3 Claude 皮 → 否(用我的設計系統)|v4 PRD 每段必增強 → 否("你是把他說的話又可視化了")|v5 只留進度/機制圖/示意 mock ✓|v6 示意改成真實介面+真實資料 ✓|v7 補作品集/履歷示意 + 運鏡規則 ✓("這一版很好了")|10-01 skill 首跑 ai-value + 主題化(Knock/私有主題)+ Eval v1|10-02 泛化成「內容形狀 → 元件」後盲測片變成一大堆表格文字卡 → 否(「可視化沒有之前好了」)→ 加剪輯師視角:剪輯臺本 + 素材等級 + 真實素材元件 + 審片

相關技能