product-video — 用程式碼製作的產品介紹影片

product-video — 用程式碼製作的產品介紹影片 是做什麼的？

將產品的畫面用 HTML 重新製作，把動畫寫成「僅由時間決定」的方式，然後在無頭瀏覽器中逐幀拍攝，最終合成影片。音樂和音效也在瀏覽器中合成。只需要 Node.js、ffmpeg 和 Chromium。

這個技能內含一個可立即運作的模板（assets/template/）。裡面有拍攝、音效和品檢所需的工具，以及一個 30 秒的範例影片。所以不需要從頭建立機制，只需複製模板並替換內容即可。

重要前提：你自己看不到也聽不到

你無法播放影片來確認效果。因此，這項工作的品質取決於你輸出靜態圖片並親眼檢查的次數，以及用數值衡量的品檢。如果只寫了程式碼就認為「應該可以了」而繼續進行，文字截斷、重疊、瞬間的錯亂一定會遺留下來。每完成一個場景，就必須並排查看、修正，然後再進行下一個。你聽不到聲音，所以必須出示測量到的數值，並請他人協助聽覺方面的確認。

必須遵守的事項（附帶理由）

1. 外觀僅由時間決定。 動畫必須使用 tl.* 來設定「在幾秒時」發生，或使用 onFrame((t) => …) 直接根據 t 計算。不要使用 CSS 的 animation / transition、setTimeout、Math.random() 或當前時間。因為無論跳到哪個時間點都能看到相同的畫面，所以才能並行拍攝，並且只需重新拍攝部分片段。
2. 寫完就檢查。 每寫完一個場景，就使用 --sheet 將其並排顯示，然後打開圖片查看。場景切換處要以 0.1～0.2 秒為間隔檢查。在沒有檢查之前，不要進入下一個場景。
3. 不要讓含有文字的元件緩慢移動。 瀏覽器為了將文字位置對齊到像素，如果花費數秒緩慢移動，文字就會細微顫抖。容器或標題應該在大約 1 秒內移動到位，然後在靜止的畫面中移動容器內的內容。只有背景光可以緩慢移動。
4. 進場使用 tl.in，退場使用 tl.out / tl.hide。 如果使用 tl.fromTo 來處理進場，在開始時間之前它會保持原始值，導致在開始之前會瞬間被看到。
5. 產品畫面的 CSS 必須寫在畫面根元素的 class 之下。（例如：.ui-chat .row）。如果裸寫 .row .title 這類簡短名稱，可能會與模板的元件或其他畫面衝突，導致難以察覺的錯亂。
6. 確保文字可讀。 影片也會在手機上觀看。標題至少 68px，容器內正文在畫面上至少 18px（字型大小 × 縮放比例）。如果畫面較小，可以將容器整體放大，或者將鏡頭靠近想展示的部分。
7. 不要扭曲事實。 不要加入任何無法從資料確認的內容。不要展示「做不到」的事情為「做得到」。不要添加未經確認的數值、與其他公司的比較、推薦用語。不要畫出其他公司的 Logo，只以文字書寫名稱。請在最後一張卡片上，以小字標註畫面為重新製作（brand.fine）。
8. 場景的邊界和大的動作應放在小節的開頭。 Logo 就位的瞬間、場景切換、最後一張卡片，都應與音樂的重拍（hit: true）在同一時間點。僅此一項就能讓整個影片看起來更緊湊。
9. 不要改變音量和音色。 kit/audio.js 的值是經過測量並取得平衡的。在無法聽到的狀態下改變會導致失衡。可以改變的只有音樂的段落（plan.js）和音效提示。
10. 不要將未經測量的事情寫成「已確認」。 在報告中必須明確寫出你沒有聽到聲音。

執行步驟

每個階段結束時都要進行確認。不要跳過確認直接進行下一步（事後修正的成本會更高）。

這是一項長期工作。如果過程中上下文被壓縮而忘記了細節，請重新閱讀此文件和該階段的 references/ 目錄。已確定的結構（場景表）可以作為註解保留在 src/js/plan.js 的開頭，這樣即使中斷也能從中斷處繼續。

0. 準備

node "${CLAUDE_SKILL_DIR}/scripts/new.mjs" video     # 將模板複製到 video/ 目錄（位置根據需求調整）
cd video && npm install --ignore-scripts
node render.mjs --sheet 0:29:2                       # 如果範例影片的清單輸出到 out/sheet.png 即表示準備完成

${CLAUDE_SKILL_DIR} 是此 SKILL.md 檔案所在的資料夾。如果看到的是字面文字，請將其替換為此檔案所在資料夾的絕對路徑。

如果提示沒有瀏覽器，請執行 npx playwright install chromium。如果環境無法執行此指令，則使用已安裝的 Chrome 或 Edge（執行時加上環境變數 CHROME_CHANNEL=chrome 或 CHROME_CHANNEL=msedge）。如果缺少 ffmpeg，請安裝它。

首先，請查看範例的 src/js/scenes.js 以及匯出的 out/sheet.png。關於元件的用法，看範例會比看說明更快理解。

1. 調查

影片中呈現的所有事實都必須有來源。請閱讀 README、文件、設計規範（顏色、文字、間距）、實際畫面的用詞，並整理出以下內容。

• 這是誰的、什麼樣的困擾、以及如何解決的產品（用一句話描述）
• 想要展示的功能及其依據（來自哪份資料的哪個部分）
• 畫面上出現的真實用詞（按鈕名稱、狀態顯示、通知文字）。虛構的用詞很容易被熟悉實際產品的人看穿
• 實際畫面的外觀。如果有螢幕截圖或畫面模擬圖，請打開查看，並記錄其佈局、顏色、間距、文字大小。如果沒有，請從 UI 的程式碼（組件、樣式、設計 Token）中讀取
• 支援環境、限制、前提（以避免過度承諾）

如果需求中未指定，請自行決定並繼續進行，然後在報告中說明：時長（60～90 秒。如果需求簡短則為 30 秒）、語言（產品畫面和文件的語言）、明亮場景和暗色場景的運用。只有在無法從資料中確定品牌的顏色、Logo、字型時，才向需求者詢問。

2. 決定結構

在開始製作之前，先建立一個場景劃分表。關於結構的類型、標題的寫法、時間的決定方式，請參考 references/direction.md。請務必閱讀。

• 傳達的內容只有一個。每個場景的標題也只有一個。不要做成功能列表
• 開頭不要從產品開始，而要從「困擾」開始
• 場景的邊界應放在小節的開頭（120 BPM 則以 2 秒為間隔）
• 根據此表格，在 src/js/plan.js 中設定 T（場景開始時間）和 music（音樂段落）

將決定的結構簡短地展示給需求者。可以不等回覆就開始製作（如果方向錯誤，也能及早發現）。

3. 準備品牌和畫面

• src/js/brand.js：名稱、一句話描述、顏色、字型、Logo。值應從實際產品中取得
• src/css/app.css 和 scenes.js 中的 HTML：重新製作產品畫面。顏色、尺寸、用詞要與實際產品一致
• 在開始動畫之前，先在靜止狀態下使用 --shot 輸出並與實際產品比對。如果在這個階段不像，即使加上動畫也不會像

畫面要用 HTML 重新製作，而不是貼上螢幕截圖。因為這樣可以逐個移動元件，放大時也能保持清晰，並且可以根據場景切換顏色。

4. 逐個場景製作

在 scenes.js 中，為每個場景編寫函數。關於元件和寫法，請參考 references/kit.md。在開始撰寫之前，請先閱讀。

針對每個場景，重複以下步驟。

node render.mjs --sheet 14:26:1        # 將該場景以 1 秒為間隔排列 → 打開 out/sheet.png 查看
node render.mjs --shot 16.6,22.5       # 以原始倍率查看有疑問的時間點 → out/shots/
node render.mjs --sheet 13.4:14.6:0.1 --cols 7 --w 420   # 以 0.1～0.2 秒為間隔查看場景切換
node render.mjs --lint                 # 以機械方式檢查文字截斷、重疊、文字過小

檢查時的重點：文字是否被截斷、是否重疊、是否可讀、間距是否不均勻、是否能一眼看出要看哪裡、前一場景的元件是否殘留。

作為一個標準，每個場景至少檢查 3 次（剛寫完後、修正後、以及與前後場景的切換處）。如果在清單中太小而看不清楚的地方，請使用 --shot 以原始倍率確認。

5. 加入音效

音樂會根據 plan.js 中的段落順序自動編曲。音效則是在組織場景時，透過 cue("種類", 時間點) 堆疊的聲音來播放。詳細資訊請參考 references/audio.md。

node render.mjs --audio                # 輸出 out/audio-master.wav。會顯示音量和峰值

6. 進行全片預覽和品檢

node render.mjs                        # 以原始倍率輸出全片（30 秒的影片需要幾分鐘）。out/video.mp4
node tools/qa.mjs                      # 檢查格式、音量、單幀錯亂、掉幀、全黑、無聲
node render.mjs --sheet 0:90:1.5 --cols 6     # 全片一覽（秒數請根據影片長度調整）

修正所有顯示為 ✗ 的項目。關於品檢結果的讀法和常見問題的修正方法，請參考 references/qa.md。

從這裡開始是收尾工作。 首次通過的版本通常「沒有明顯錯誤，但會讓人覺得不夠精彩」。請查看全片一覽，列出至少 5 個想要修正的地方，然後再進行修改。需要尋找的項目：

• 超過 2 秒沒有任何變化的時間
• 過大的空白、偏離中心的畫面、容器內的空洞（例如手機螢幕下半部是白色的）
• 難以理解什麼觸發了什麼變化的瞬間（按下 → 變化，但看不到對應關係）
• 與實際產品不同的用詞、顏色、佈局

如果找不到 5 個點，表示檢查間隔太粗。請以 1 秒為間隔檢查，對於有疑問的場景則以 0.25 秒為間隔重新檢查。

7. 輸出正式版本

node render.mjs --scale 2 --keep-frames     # 以 2 倍解析度拍攝後縮小（需時約原始解析度的 3～4 倍）。可在背景執行
node tools/qa.mjs
node tools/extras.mjs web                   # 輸出小於 10 MB 的輕量版（可用於聊天或 GitHub）
node tools/extras.mjs poster 15.9           # 輸出用於標題的靜態圖片（選擇最能傳達內容的時間點）

以 2 倍解析度拍攝是為了使輪廓更平滑，並將文字抖動減少一半。如果中途停止，請加上 --resume --reuse-audio 參數從中斷處繼續。如果只修正了部分內容，請刪除該區間的幀（out/frames/ 中的對應編號），然後使用 --resume 即可只重新拍攝該部分。

8. 報告

請簡短、誠實地報告以下內容（格式請參考 references/qa.md 的最後部分）。

• 完成的內容（檔案位置、時長、解析度）以及結構摘要
• 已經確認的事項（品檢結果）以及尚未確認的事項。因為你沒有聽到聲音，所以必須寫「數值在標準範圍內。請協助確認聽覺感受。」
• 自行決定的事項（時長、語言、顏色處理方式等）以及因為無法從資料確認而未能加入的內容
• 畫面是重新製作的事實。以及希望修正時的請求方式

當被要求修改時

修正由此模板製作的影片時，不需要從頭開始執行上述步驟。

1. 閱讀 references/kit.md 以及要修改部分的程式碼。標題或畫面用詞在 scenes.js 中，最後一張卡片的文字在 brand.js 中，時間表和音樂在 plan.js 中，畫面外觀在 app.css 中
2. 進行修改
3. 使用 --shot / --sheet 檢查修改的場景及其前後的切換。也要執行 --lint
4. 如果改變了場景長度或音樂段落，請執行 node render.mjs --audio 確認沒有出現警告
5. 如果需要輸出影片檔案，請依照步驟 6～7 進行輸出。如果不需要，請報告你檢查了哪些地方，並詢問是否需要輸出

如果不加任何參數直接執行 node render.mjs，它將開始輸出全片（需要數分鐘或更長時間）。如果只是想確認內容，請務必加上 --shot、--sheet 或 --lint 中的一個參數。使用方法請參考 node render.mjs --help。

品質標準

在輸出之前，請自行確認。

• 即使關閉聲音，僅憑標題也能理解內容
• 在最初的 3 秒內，呈現出能讓人感覺「這是在說我的問題」的困擾
• 在任何場景中，需要觀看的地方都只有一個（沒有同時移動兩個地方）
• 了解產品的人觀看後，對畫面和用詞沒有違和感
• --lint 和 tools/qa.mjs 沒有顯示 ✗
• 已經以 0.1～0.2 秒為間隔檢查過所有場景切換

參考資料

檔案	內容	何時閱讀
references/direction.md	結構類型、時間表、標題寫法、畫面配置、動畫方式	在決定結構之前（務必閱讀）
references/kit.md	模板檔案的角色、引擎和元件的使用方法	在撰寫場景之前（務必閱讀）
references/audio.md	音樂段落、音效提示列表、測量方法	在添加音效時
references/qa.md	品檢結果的讀法、常見問題與修正方法、報告格式	在預覽和正式輸出時
assets/template/src/js/scenes.js	範例影片。元件用法的實際範例	最初使用時