pr-explainer-film
一部預設無聲、長度約30秒、分為五個樂章的影片。其結構的巧妙之處在於:觀眾首先會覺得差異化內容難以閱讀,接著獲得白話解答,再看到實際證明,最後知道該輸入什麼指令。
| 時間 | 樂章 | 目的 |
|---|---|---|
| 0-2秒 | 鉤子 | 說明變更規模(例如「已變更15個檔案」) |
| 2-8秒 | 差異模糊 | 實際的程式碼區塊快速閃過;計數器持續上升 |
| 8-13秒 | 白話摘要 | 一句話標題加上三個簡短重點 |
| 13-23秒 | 四個能力展示 | 每個能力展示一個功能,並同時顯示背後的真實程式碼 |
| 23-30秒 | 結尾 | 逐字打出安裝指令,然後顯示網址 |
輸入
在開始建構之前收集以下資訊。僅詢問缺少的項目。
- 變更來源:一個GitHub PR或發行版本(使用
gh pr diff、gh pr view --json title,body,files),或本地工作目錄(使用git diff加上未追蹤的檔案)。僅限唯獨操作;絕不修改儲存庫。 - 觀眾:那些不會閱讀差異化內容的人(客戶、團隊成員、粉絲)。這將決定摘要和能力展示中的用語。
- 行動呼籲:確切的安裝指令和/或網址。請完全按照原文使用。如果該產品只有一個標準指令,則僅顯示該指令,不顯示其他工具的名稱。
- 品牌:色板、標誌(你自己的檔案)、字型。範本中的預設值為中性且深色。
工作流程
- 閱讀變更。 取得包含新增/刪除計數的檔案清單以及實際的程式碼區塊。用非工程師也能理解的一句話來描述變更;如果你做不到,表示你還不理解這項變更。
- 挑選內容(參閱
references/content-rules.md):鉤子數字、用於模糊效果的5-8個程式碼區塊、3個摘要重點、恰好4個能力展示、行動呼籲。 - 建立專案骨架。
npx --yes hyperframes init <dir> --non-interactive --example=blank,然後將template/index.html和template/film.config.js複製覆蓋產生的檔案。如果你有標誌,請放在assets/logo.png。 - 填寫
film.config.js。 所有文字、程式碼片段和數字都在此定義。僅在需要更改:root中的品牌變數、時間軸或版面配置時,才編輯index.html。 - 驗證:
npx --yes hyperframes lint然後npx --yes hyperframes check。修復所有錯誤。已知可接受的警告:nested_structure_needs_subcomposition(影片刻意使用單一檔案,以便於重新品牌化)。 - 檢查畫面。
npx --yes hyperframes snapshot --at 1,4,6,8.3,11,14,17,19.5,22,26,29並開啟snapshots/contact-sheet-*.jpg。根據下方的清單進行檢查;修正問題並重新拍攝快照,直到一切正常。 - 渲染。
npx --yes hyperframes render --quality high --workers 2 --output final.mp4。使用ffprobe確認其為1920x1080、H.264、且長度為28-34秒。 - 再次檢查從MP4中擷取的4-6個影格(使用
ffmpeg -ss T -i final.mp4 -frames:v 1 f.png),而不僅是快照。
確保格式有效的規則
- 差異化內容必須是真實的。 從實際的差異化內容中複製實際的程式碼行。絕不虛構程式碼或計數。計數應從
git diff --shortstat加上新檔案的wc -l計算得出。 - 刻意設計為不可讀。 滾動速度會加速(使用
power2.in)並變得模糊。不要為了讓人能閱讀而放慢速度;「資訊太多無法閱讀」的設計正是為了鋪陳後續的解釋。 - 先給出文字說明,再展示證據。 摘要必須在任何能力展示之前出現。每個能力展示的標題是2-4個字的好處;描述是一句沒有術語的句子;程式碼片段是1-5行真實的程式碼,並將關鍵行標示出來。
- 恰好四個能力展示,每個展示一個概念,每個約2.6秒。優先刪除較弱的展示,而不是縮小文字。
- 交替背景。 差異化和能力展示使用深色背景,摘要使用一個淺色場景。背景的變化傳達「現在一切變得簡單」的訊號。
- 以指令結尾。 逐字打出真實的指令,然後顯示網址。沒有第二個行動呼籲。
- 內容整潔。 在程式碼片段顯示之前,移除那些提及競爭對手或不相關工具的名稱的程式碼註解。永遠不要顯示行動呼籲指令以外的任何CLI。
- 使用自己的素材。 使用你自己的標誌、電腦上已有的字型,並且不使用任何庫存或第三方媒體。音樂為選用;如果使用,僅限於獲得商業使用授權的音軌(透過
media-use解決),並確保影片在沒有聲音的情況下仍完全可讀。 - 確定性。 在構圖中不使用
Math.random、Date.now或網路請求;透過補間動畫進度值來驅動打字文字和計數器的動畫,以便精確定位。
影格檢查清單(步驟6和8)
- 鉤子數字和文字與實際變更相符。
- 差異化內容視窗裁剪在其框架內;檔案標題以及綠色/紅色行在靜止時清晰可辨,移動時則模糊。
- 計數器最終停在正確的數字上。
- 摘要投影片在淡出前顯示所有三個重點。
- 每個能力展示的標題、句子和程式碼片段都同時可見,沒有任何內容被裁切。
- 最終影格顯示完整的指令和網址,拼寫完全正確。
交付成果
交付 final.mp4 和專案資料夾(index.html、film.config.js、assets/、meta.json)。報告檔案路徑、影片長度,以及任何被接受的驗證警告。該資料夾可以使用相同的指令重新渲染;如果要為下一個版本重新品牌化或重複使用,只需編輯 film.config.js。
參閱 references/content-rules.md 了解尺寸和文字限制。