Communitygithub.com

techgirlcrystal/product-video-skill

使用產品的實際輸出素材,建構精美、動畫風格的產品介紹/推廣影片(MP4,16:9 和 9:16),搭配螢幕字幕、動畫游標、UI 音效和背景音樂,無需旁白。

product-video-skill 是什麼?

這是一個為軟體產品製作專業、動畫化產品影片的技能,專為 Claude Code 設計。它與一般範本影片不同,完全以產品的真實輸出(如示範帳戶、報告、儀表板、圖表)為素材,透過 HTML 動畫合成並逐幀渲染成 MP4 影片。影片風格模仿現代 SaaS 發布影片,包含黑暗電影感鉤子場景、明亮的分割功能場景、動態計數器、自繪圖表、3D 瀏覽器視窗平移等動態圖形效果。 此技能支援多種平台和輸出格式:可生成標準 16:9 橫向影片、9:16 直向短影片(適用於 Reels/Shorts/TikTok),以及從現有影片中裁剪出 15 秒的短版。它提供完整的音效合成(無需授權)、音樂混音、自動化渲染流程。使用者只需提供自己的音樂曲目。 技能附帶詳細的工作流程,從檢查環境依賴、提取真實素材、製作分鏡腳本、捕獲資產、建立 HTML 動畫合成、預覽、渲染,到添加游標點擊、音效和音樂混音,最後交付並提供誠實的影片批評和後續步驟建議。整個過程強調數據真實性、時間精確度和高品質輸出。

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

在你喜歡的 AI 中提問

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

說明文件

產品影片

製作一部以音樂驅動、無旁白的產品介紹影片,將其建構為 HTML 動畫,並逐幀渲染為 MP4。螢幕上的每個數字、名稱和圖表都來自產品的真實輸出。這就是它可信的原因,也是它與一般庫存動畫圖形的區別。

運作方式: 一個目標解析度的 HTML 頁面定義了 window.seek(t),該函數以純函數方式(無 CSS 動畫、無計時器)繪製時間 t 的幀。Playwright 呼叫 seek(i/30) 並截取每一幀的螢幕截圖,然後將這些幀通過管線傳遞給 ffmpeg。由於幀不依賴於實際時間,因此任何機器上的輸出都是相同的,你可以預覽任何單一幀,並且更改只需幾分鐘即可重新渲染。

捆綁檔案:

  • scripts/render.mjs:將合成結果轉換為 MP4(--url --out [--w --h --fps --from --to])
  • scripts/preview.mjs:在選定的時間點生成靜止影像,加上 --sheet 可生成聯繫條
  • scripts/cutdown.py:從現有合成中剪出短版影片(例如 15 秒):渲染選定的時間範圍,用硬切接合,將音樂的鼓點落在第一個剪輯點
  • scripts/cues.mjs:從合成中導出音效提示列表(場景嗖聲、卡片/晶片彈出聲、計數器滴答聲、游標點擊聲、網址鈴聲,加上 window.SFX_EXTRA)
  • scripts/sfx.py:從頭開始合成 UI 音效套件(點擊、彈出、嗖聲、滴答、按鍵、鈴聲、重擊聲;無庫存音頻或授權),將提示混合成一條音軌,並進行最終的音樂+效果混音,達到 -16 LUFS
  • scripts/music.py:analyze 音軌的能量圖,並 mux 到影片下方(修剪、淡出、-16 LUFS)
  • scripts/doctor.mjs:檢查以下所有要求,並為缺少的項目列印確切的修復方法
  • scripts/_common.mjs:查找預先安裝的 Chromium 和 ffmpeg(pip 安裝 imageio-ffmpeg 作為備用)
  • assets/template.html:一個可運作的場景範本;透過直向媒體查詢,一個檔案即可渲染 16:9 和 9:16
  • assets/fonts-manrope.css:嵌入的 Manrope 字體(如果產品沒有嵌入字體時的備用)
  • assets/examples/supersnapshot/:(Super Snapshot AI,一個 GoHighLevel 工具)一個完成的 80 年代風格影片的完整原始碼(16:9 + 直向),是達到生產級水準的每個模式的實例
  • references/story-and-copy.md:故事弧線、標題規則、誠實規則、時間約定。在製作分鏡腳本前閱讀。
  • references/extraction.md:如何找到安全的資料來源,並從產品中提取 SVG、圖表和螢幕截圖。在擷取前閱讀。

要求

此技能執行 shell 命令,因此需要 Claude Code(CLI、桌面應用程式或網頁版 Claude Code)。沒有程式碼環境的純文字聊天可以規劃分鏡腳本,但無法渲染。在機器或容器上:

需要原因安裝方式
Node.js 18+執行渲染腳本nodejs.org 或 nvm install 22
playwright npm 套件,可從工作目錄匯入驅動瀏覽器逐幀操作npm i -D playwright(許多網頁儲存庫已有)
Chromium渲染幀npx playwright install chromium,或重複使用預先安裝的版本(CHROME=/path;/opt/pw-browsers 會自動被找到)
Python 3.9+ 與 numpy音效合成與混音pip install numpy
ffmpeg編碼、音樂、混音系統 ffmpeg,或 pip install imageio-ffmpeg

僅在安裝這些項目時需要網路連線。渲染完全離線進行。使用者提供自己的音樂曲目;音效是合成的,因此無需授權。

工作流程

0. 檢查設定

從產品儲存庫中,執行 node <skill>/scripts/doctor.mjs。如果出現任何 ✗,請先執行列印的修復命令(或如果無法在此環境中安裝套件,請要求使用者執行)再開始。在 30 分鐘的建置後才發現缺少 ffmpeg,會浪費整個工作階段。

1. 尋找真實素材

閱讀 references/extraction.md。找到產品的示範/範例建置(儲存庫腳本、測試固定數據,或公開範例 URL),在 Playwright 中打開它,點擊每個分頁,並傾印每個窗格的文字。截取窗格的螢幕截圖並查看它們。你要尋找的是:最令人印象深刻的真實數字(鉤子)、買家願意付費的功能,以及在動態中看起來不錯的視覺元素。

2. 分鏡腳本,然後取得同意

閱讀 references/story-and-copy.md。提議一個表格:# · 時間 · 螢幕上顯示的內容 · 螢幕字幕。保持在大約 60–75 秒(或社交媒體剪輯版為 30–45 秒)。誠實地說出哪些功能在鏡頭前看起來很弱。只問那些只有使用者才能回答的事情,不要問其他的:

  • 需要避免提及的任何事項,
  • 行動呼籲(預設:僅網址),
  • 品牌外觀(預設:匹配產品自己的標記)。

在他們同意之前不要開始建置,因為重新剪輯一個完成的渲染成品比編輯一個表格要花費更多成本。

3. 捕獲資產

將所有內容放在產品儲存庫外的一個暫存工作目錄中(如果工作階段有的話就用它的暫存區,否則用一個臨時目錄):<work>/index.html + <work>/assets/。按照 extraction.md 中的描述提取圖表 SVG、圖表 JSON 和高大的報表螢幕截圖。將產品的內嵌字體 CSS 複製到 assets/fonts.css(或從此技能複製 assets/fonts-manrope.css)。

4. 建構合成

將 assets/template.html 複製到 <work>/index.html。將每個 [括號] 佔位符替換為真實內容,刪除不需要的場景,並複製需要的場景。快速瀏覽 assets/examples/supersnapshot/index.html 中的範例,以了解更多模式(溫暖的「問題」卡片、帶有標註框的長條卡片、分數刻度盤、徑向依賴性地圖、整個帳戶的網路、帶有嚴重性標籤的修復行)。

重要事項:

  • 時間設定存在於兩個地方: SCENES 的開始時間,以及每個元素的 data-in。如果你插入了一個場景,則將之後所有的 data-in 和 seek() 中任何硬編碼的時間向後移動相同的量(對所有 data-in="…" 中大於或等於插入點的值進行一個小的正則表達式替換即可)。
  • 交叉淡入淡出: 新場景在舊場景之上淡入,舊場景保持實色。兩者同時淡出會使明亮的場景變成渾濁的灰色。
  • 揭示: SVG 部分按閱讀順序出現(從上到下,或從中心向外)。箭頭僅在它們的線條繪製完成後才出現。通過節點的標籤文字為其設定高亮。
  • 標註: 晶片和標籤絕對不能遮蓋它們所指的內容。將它們放置在它旁邊的空白空間中,如果鏡頭平移,則讓它們跟隨。

5. 在渲染前預覽

啟動目錄服務(cd <work> && python3 -m http.server 8765 &)並在每個場景的關鍵時刻渲染靜止影像:

node <skill>/scripts/preview.mjs --url http://127.0.0.1:8765/index.html --dir <work>/prev --sheet 5 9 13 22 31 43 50 60

查看每一幀。 檢查重疊、尷尬的換行(使用 <br> 強制換行)、元素在其指向的內容之前出現、空卡片以及遺留的佔位符文字。修正並重新預覽,直到乾淨為止。腳本需要 playwright:從其 node_modules 包含它的目錄執行它們(產品儲存庫通常有)。它們也會自行找到預先安裝的 Chromium,因此無需執行 playwright install。

6. 渲染並驗證

node <skill>/scripts/render.mjs --url http://127.0.0.1:8765/index.html --out <work>/video.mp4

在 1080p30 解析度下,80 秒的影片大約需要 3–5 分鐘。之後,從 MP4 本身在場景轉換處提取幀(ffmpeg -ss <t> -i video.mp4 -frames:v 1 x.jpg),以捕捉單張靜止影像可能遺漏的轉換問題。

7. 音樂

當使用者發送曲目時:

python3 <skill>/scripts/music.py analyze track.mp3             # 找到前奏、鼓點、間奏
python3 <skill>/scripts/music.py analyze track.mp3 --zoom 14 17 # 將鼓點精確定位在節拍上
python3 <skill>/scripts/music.py mux video.mp4 track.mp3 out.mp4 [--offset s]

目標是讓鼓點落在品牌揭示到第一個功能場景的剪輯點上。選擇 --offset(或調整 SCENES)來實現這一點。告訴使用者安靜的段落落在哪裡。如果一個關鍵的銷售場景位於間奏中,建議重新排序場景。

7b. 游標和音效

它們使影片感覺像一個真正的產品正在被使用,但前提是每個聲音在螢幕上都有引起它的東西。

游標: 範本中的 CURSOR 列表定義了 2–4 個點擊時刻。游標滑動到一個真實元素(通過 CSS 選擇器,每幀測量,因此它跟隨平移並在兩種方向下都有效),按下,並留下一個漣漪。每個點擊應該在約 0.1–0.3 秒後導致某些事情的發生:長條填充、步驟高亮、地圖展開、開始打字。如果需要,移動反應的 data-in。在預覽中檢查目標在被點擊時已經出現;點擊一個尚未繪製的節點看起來很糟糕。如果一個目標沒有方便的選擇器,請在 init() 中給它一個 id(例如,通過其標籤文字找到一個 mermaid 節點)。

聲音:

node <skill>/scripts/cues.mjs --url http://127.0.0.1:8765/index.html --out <work>/cues.json
python3 <skill>/scripts/sfx.py mix <work>/cues.json --duration <DURATION> --out <work>/sfx.wav
python3 <skill>/scripts/sfx.py final <work>/video.mp4 --sfx <work>/sfx.wav --music track.mp3 [--offset s] --out <work>/final.mp4

cues.mjs 從動畫本身的時間設定中放置聲音,因此它們在重新調整時間後仍與之鎖定。它無法看到的任何內容(由 JS 而非 data-count 驅動的計數器、打字、鉤子落地)都放在 window.SFX_EXTRA 中。保持稀疏:不要在標題入場時有聲音,每組計數器一個滴答運行。針對繁忙的企業音樂曲目有效的增益:點擊約 -1 dB,按鍵約 -6,滴答約 -8,彈出 -11,嗖聲 -10 到 -14。要檢查聲音是否被掩蓋,將其與音樂在 >2.5 kHz 頻段進行比較(對兩者進行高通濾波,比較峰值);全頻段峰值會產生誤導,因為音樂的低音佔主導地位。如果效果感覺被掩蓋,請先降低 --music-gain(預設 -6),然後再提高效果增益。final 使用一個靜態增益設定響度,因為動態 loudnorm 會壓平點擊聲。sfx.py kit <dir> 將每個聲音寫入 WAV 檔案以供試聽。

8. 直向 9:16

範本支援方向感知:使用 --w 1080 --h 1920 渲染同一個頁面,直向媒體查詢將生效(標題堆疊在全寬卡片上方,關鍵內容保持在 y≈250 到 y≈1550 之間,避開社交應用程式的覆蓋層)。使用 <br class="br-v"> 用於僅在直向模式下才需要的換行。對於非基於此範本建立的合成(例如範例),建立一個包含直向位置的 vertical.html 副本。也要預覽直向幀,因為文字換行方式不同。

9. 短版影片(15 秒)

一旦直向影片存在,從中剪出 2–4 個短版影片。每個影片只有一個角度(一個痛點、一個功能集群),因此每個都可以作為獨立的廣告或貼文進行測試。不要重建任何東西:從直向合成中選取時間範圍,讓 cutdown.py 渲染並接合它們。

python3 <skill>/scripts/cutdown.py --url http://127.0.0.1:8765/vertical.html \
  --seg 3.2-6.2 --seg 6.5-9.0 --seg 15.4-20.9 --seg 75.6-79.6 \
  --out <work>/reel1.mp4 --music track.mp3 --drop 15.0 --sfx

--sfx 從合成中提取每個片段的声音提示,將其重新計時到影片中,並與音樂混合。

選擇片段(參見 references/story-and-copy.md 中的「Short reels」):

  • 結構: 鉤子(2.5–3 秒)→ 1–2 個功能節拍(每個 4–5.5 秒)→ 結束卡片(4 秒)。總共 15 秒。
  • 在每個場景完全淡入之後開始該片段(場景開始後約 0.5 秒)或在一個關鍵入場點開始,並在其回報落地後結束:計數器完成、晶片彈出、高亮點亮。檢查合成中的 data-in/計數時間。計數器在計數中途被切斷是經典錯誤。
  • 在標誌彈出後約 0.6 秒開始結束卡片片段,這樣網址將在螢幕上顯示 3 秒或更長時間。
  • 保持每個片段的長度為節拍的倍數(120 BPM 時為 0.5 秒),以便所有剪輯點都落在節拍上,並傳遞 --drop 使鼓點落在第一個剪輯點。
  • 影片的第一幀必須已經顯示鉤子。沒有時間進行緩慢淡入。

渲染後,從完成的 MP4 中每個片段的中間和結束處提取一幀並查看它們。然後告訴使用者應該先發布哪個影片(以問題開場的那個)、哪些僅適用於已熟悉的觀眾(純粹的視覺享受,沒有痛點),以及在此節奏下細小文字將不可讀,因此鉤子也應放在貼文說明中。

10. 交付

將 MP4 檔案作為檔案發送給使用者。然後提供誠實的批評:總長度(80 秒太長;30–45 秒適合 Reels/Shorts)、最弱的場景,以及一個具體的剪輯或重新排序。提供後續步驟:直向剪輯、15 秒影片、音樂、修剪。除非被要求,否則不要將影片檔案或建置源代碼提交到產品儲存庫中。

交付檢查清單

  • 螢幕上的每個數字/名稱都與產品的真實輸出匹配
  • 使用者要求省略的任何內容都沒有出現在任何地方
  • 沒有遺留 [佔位符文字],在任何預覽幀中都沒有裁剪或重疊的元素
  • 鉤子數字在前 5 秒內開始計數;網址在末尾至少在螢幕上顯示 3 秒
  • 在編碼後的 MP4 中檢查了轉場,而不僅僅是在靜止影像中
  • 音樂(如果有的話)已修剪、淡出、標準化,並且其鼓點落在一個場景剪輯點上
  • 每個游標點擊都落在一個已經可見的元素上,並導致一些事情發生
  • 點擊、按鍵和滴答聲在音樂中是可聽見的(檢查 >2.5 kHz 頻段),並且最終混音為 -16 LUFS
  • 影片:每個片段在其回報落地後結束(沒有未完成的計數器),網址顯示 3 秒或更長時間,剪輯點落在節拍上

相關技能