dyachkovp/product-motion

Product Motion

製作展示功能運作方式的短片：產品介面在畫面中、游標點擊、文字輸入、輸入片段下方的標籤、卡片層疊出現、鏡頭引導視線、語音解說。此方法已在多個產品的影片中驗證；在此將其與特定品牌分離。

原則

1. 幀為時間的函數。 影片是 HTML 頁面，其中 render(t) 根據時間計算每一幀的狀態，而 scripts/render.py 逐一捕捉幀並傳遞給 ffmpeg。不使用 CSS 動畫、計時器或螢幕錄製：沒有抖動或不同步，任何時間點都可透過單一幀驗證。引擎為 templates/engine.js（references/engine.md）。
2. 只展示產品中存在的功能。 螢幕、標題、狀態——來自當前專案的程式碼、原型、docs/ 或螢幕截圖。影片中不會出現不存在的功能。資料使用虛構的簡短名稱。為場景構想的內容（回應、狀態文字）會告知用戶進行確認。
3. 風格來自產品而非技能。 顏色、強調色、字型、標誌——來自專案的品牌設定檔（motion/brand/），從其程式碼中收集（references/brand.md）。技能的預設設定檔僅用於草稿。
4. 我們不自行合成語音。 本機 TTS 聽起來像機器人。用戶會收到獨立的 Gemini TTS 文字與提示（或自行錄音）並提供音檔；align_vo.py 會將音檔按單詞對齊。在此之前，影片僅包含字幕與音樂。
5. 先檢查視覺效果，再進行渲染。 在選擇的格式中輸出關鍵時刻的連拍圖，並使用 verify_scene.py——在完整渲染之前捕捉構圖錯誤的成本最低。
6. 不替用戶做決定。 語言、格式、速度、音樂、發佈——來自需求簡報或提問。以下預設值僅在用戶未指定時使用。

流程

0. 環境設定（每台機器一次）

python3 <skill>/scripts/check_env.py

需要 Python 3.9+、ffmpeg/ffprobe、pip install playwright numpy scipy pillow（+ 語音對齊用 faster-whisper）、python -m playwright install chromium；加速版本需要帶 rubberband 的 ffmpeg。建議在專案虛擬環境或相鄰目錄中安裝；未經用戶同意勿自行安裝相依套件——請提示指令。

1. 需求簡報

功能；時長（未指定時：單一功能 30–35 秒，區段 60–75 秒）；目標受眾與用途（教學、宣傳、投資人、登陸頁面）；語言；格式（未指定時：提供 16:9 橫向與 9:16 直式）。每次提問不超過兩個；其餘採用合理預設值，並在回覆中說明。詳細內容請見 references/brief.md。

2. 功能事實——從當前專案中獲取

閱讀功能程式碼、原型、docs/、螢幕截圖：螢幕、準確標題、佔位符、按鈕、狀態、存在與不存在的內容。如果不確定用戶在主操作後會看到什麼，請詢問。

3. 品牌設定檔——每個專案一次

如果專案中還沒有 motion/brand/——請依照 references/brand.md 收集它：brand.css（從 CSS 變數、主題、tailwind 設定中提取令牌）、本機字型（需確認授權）與標誌。在第一支影片之前向用戶展示範例幀。後續影片將使用已準備好的設定檔。

4. 腳本

表格：「時間碼 · 畫面內容 · 鏡頭/動畫 · 台詞」（references/storyboard.md：按時長提供的骨架，文字密度為每秒 1.3–1.6 個單詞，場景原型）。如果影片長於 30 秒或需求簡報不完整——展示表格並等待用戶回覆「好」；簡短且需求明確的影片——可直接開始製作，並在首批幀產生時一起展示表格。

5. 影片專案

如果專案中已有存放影片的目錄（promo/、design/motion/ 等）——則放在那裡；否則放在 motion/<slug>/。

python3 <skill>/scripts/new_project.py motion/<slug> --brand motion/brand --lang ru --title "功能 · 產品"

內部包含：video.html、plan.js、cues.js、tmap.js、engine.js、processing.js、base.css、brand/、build/、out/、README.md。除非用戶另有決定，否則 build/ 和大的 out/*.mp4 應加入專案的 .gitignore。如果專案中有 docs/，請在其中加入指向影片及其 README 的簡短連結。

6. plan.js 與場景

plan.js 是單一來源：duration、fps、canvas、language、product、audience、hold、台詞 vo[]（id、at、text、tts、subs）、pronounce、emphasis、music。window.PLAN = 之後必須是嚴格的 JSON。

在 video.html 中，將示範內容替換為功能的螢幕：build（重複元素）、setup（E.measureAt + E.rect 測量、兩種格式的鏡頭關鍵點、游標、點擊）、scene(t)。螢幕上的事件應與台詞單詞同步（E.sync('p3:單詞', 備用)）。深色螢幕與模態框透過 E.dim() 和在 #app2 中實現。場景範例請見 references/scenes.md，運動與鏡頭規則請見 references/motion.md。附帶時間軸滑桿的預覽：透過 python3 -m http.server 在影片專案目錄中打開 video.html?preview=1。

7. 幀檢查

python3 <skill>/scripts/verify_scene.py video.html --fmt both
python3 <skill>/scripts/render.py video.html stills --fmt both --times 1,6,9,12,15,19,23,27,31,34 --sheet

打開 build/stills/sheet_h.jpg 與 sheet_v.jpg：鏡頭對準動畫；標籤在正確的片段下方；文字未換行或裁切；強調色僅出現在正確位置；在「處理 → 結果」的銜接處沒有白色閃爍；在 9:16 格式中，文字較大，字幕位於底部面板上方。持續修改直到關鍵幀清晰無誤。首次渲染前，請查閱 references/pitfalls.md。

8. 語音

python3 <skill>/scripts/vo_pack.py plan.js            # --model 3.8 用於 Gemini 3.8 Flash TTS，--voice female

以兩個獨立的程式碼區塊提供 out/voiceover/tts_text.txt 與 tts_prompt.txt（文字放在文字欄位，提示放在風格欄位）、語音選擇（俄語男性為 Schedar 首選）、要求一次完整錄製、以及 timing.md 中的表格。用戶也可根據相同文字自行錄製。規則請見 references/voiceover.md。

9. 收到語音 → 對齊

python3 <skill>/scripts/align_vo.py plan.js voice.wav        # build/vo_aligned.wav、cues.js、out/subtitles.srt、報告

閱讀 build/align_report.md：標記為「需要聽覺確認」的單詞，請將時間碼告知用戶；偏移的台詞最好在 plan.js 中修正。如果台詞延伸到最終幀（hold），腳本會停止。

加速——僅作為建議。 如果影片「拖沓」，建議使用 retime.py（語速 +4.5%，停頓縮短，為影片、語音、音樂與字幕生成單一時間對應表）。僅在獲得用戶同意後才執行主要加速。

10. 音樂、混音、渲染、封裝

python3 <skill>/scripts/music.py plan.js --out build/music.wav                         # 根據 music 區段進行草稿合成
python3 <skill>/scripts/prepare_music.py plan.js track.mp3 --end-align --out build/music.wav   # 或使用用戶提供的曲目
python3 <skill>/scripts/mix.py build/music.wav build/vo_aligned.wav --out build/mix.wav
python3 <skill>/scripts/render.py video.html video --fmt h --out build/h_subs.mp4
python3 <skill>/scripts/render.py video.html video --fmt h --qs subs=0 --out build/h.mp4
python3 <skill>/scripts/assemble.py --video build/h.mp4 --audio build/mix.wav --out out/<slug>_16x9.mp4
python3 <skill>/scripts/assemble.py --video build/h_subs.mp4 --audio build/mix.wav --out out/<slug>_16x9_subs.mp4
#   … 對 --fmt v 也執行相同操作（_9x16、_9x16_subs），如果需求簡報中有直式格式
python3 <skill>/scripts/verify_media.py plan.js out/*.mp4 --sheet

渲染時間約為每格式影片每分鐘 2–5 分鐘——可在背景執行或分段執行（--start/--end，透過 assemble.py --video part1 part2 … 拼接）。合成音樂為臨時用途；對於公開影片，建議使用授權曲目。詳細資訊請見 references/audio.md。如有要求，可使用 export_web.py（純 MP4、WebVTT、海報、最終幀）以供網站播放器使用；未經用戶明確決定，請勿執行發佈。

提供給用戶的內容

• 所選格式的檔案：<slug>_16x9.mp4、<slug>_16x9_subs.mp4（+ _9x16）、SRT、語音套件（在錄製語音前）、連拍圖。檔案路徑；如果有檔案傳送工具，請傳送它們。
• 簡要說明：時長、各場景的內容；哪些是虛構的且需要與產品確認；哪些音樂是臨時的；哪些未經檢查（例如未聽過語音）。
• 更新影片專案目錄的 README：狀態、需求簡報的決定、如何重新構建。
• 不要重述流程，也不要宣傳「革命性 AI」。

技能檔案

templates/engine.js	幀引擎：鏡頭、游標、點擊、暗化與上層 #app2、字幕（subs=0）、時間對應表 tmap.js、預覽 preview=1、測量、markup/grad/plural
templates/base.css	基於品牌令牌的元件：頁首、漸層欄位、標籤、提示、深色處理、結果、彈出框、聊天、評分、結尾
templates/brand/	預設品牌設定檔：brand.css、Manrope（OFL）、佔位標誌
templates/processing.js	預設處理動畫（環、強調色光澤、飛入卡片）
templates/starter.html, plan.js	一個可運作的約 36 秒示範影片，展示虛構產品 Demo 中的「智慧搜尋」功能：鉤子 → 帶標籤的輸入 → 提示 → 處理 → 帶「為什麼」的結果 → 儲存 → 評分 → 結尾
scripts/	check_env、new_project、verify_scene、render、vo_pack、align_vo、retime、music、prepare_music、mix、assemble、verify_media、export_web
references/	brief.md · brand.md · storyboard.md · scenes.md · motion.md · engine.md · voiceover.md · audio.md · pitfalls.md