michaelburshtein/thought-to-motion

thought-to-motion 是做什麼的？

想法即是產品；其他一切都只是層層疊加的裝飾。這個技能會接收一段錄音（說話頭影片或單純的語音備忘錄），找出其中的重點節拍，並圍繞它們設計動態效果：以口語語言顯示的字幕、關鍵字卡片、劇情轉折的揭露效果，以及一個引導互動的結尾問題。

三種模式：

• talking-head：保留原始影片；卡片、字幕和放大效果疊加在畫面上。
• voice：不需要影片素材（僅需音檔，或從影片中提取的音訊）；使用全螢幕的品牌畫布，搭配場景、動態字幕和即時波形。
• text：完全不需要錄音；純文字會直接轉換為計時的動態字幕和品牌畫布上的場景，通常會搭配背景音樂。

兩種格式：9:16（預設；適用於 Reels、TikTok、Shorts）和 16:9（"aspect": "16:9"；適用於 YouTube、LinkedIn、網頁）。相同的計畫可在兩種格式下渲染：在 16:9 中，9:16 的佈局會被放置在一個寬螢幕舞台上（說話頭模式：講者在畫面右側，動態設計在左側）。

所有處理都在本機端完成。不會有任何影片、音訊或文字被上傳到任何地方。

0. 設定（每台機器執行一次）

在技能資料夾中執行：

bash scripts/setup.sh          # 建立虛擬環境 + 安裝指定套件 + 從鎖定檔安裝引擎/node_modules + 安裝本機音效套件

需要 ffmpeg、Node 18+、Python 3.10+。首次轉錄會從 huggingface.co（及其檔案 CDN *.hf.co）下載模型至 .cache/hf。如果網路存取有白名單限制，則必須允許這些主機。如果已經存在 Chrome/Chromium 無頭殼，請設定 BROWSER_EXECUTABLE=/path/to/headless_shell；否則 Remotion 會在首次渲染時自行下載至 engine/node_modules。使用 .venv/bin/python 執行 Python 腳本。

您的品牌設定（執行一次）

將 brand.example.json 複製為 brand.json 並填寫內容：品牌字標（您的姓名或品牌）、系列標籤、帳號名稱、品牌標語、主題（warm、cinematic 或 tech，請參閱 engine/src/lib/theme.js；您可以在那裡新增自己的配色和字型）。每個計畫的 brand、theme 和 bumpers 欄位都來自這個檔案。沒有 brand.json -> 就沒有頁首、片頭或片尾。

1. 輸入資料（只詢問您無法推斷的資訊）

• 來源：包含人物說話的影片 -> talking-head；僅有音訊，或只有聲音重要的影片 -> voice（prep 會提取音訊）；純文字 -> text 模式。
• 格式：9:16、16:9，或兩種都產生（使用不同 aspect 參數對同一計畫進行兩次渲染）。
• 音樂：開或關。僅內建產生的背景音樂會被嵌入（calm / warm / pulse，無版權，無需理會版權宣稱）。如果使用者想要特定的歌曲，請關閉音樂；他們之後可以在應用程式中自行加入。
• 字幕語言：預設值 = 口語語言。第二語言有兩種選項：雙語（單一影片，上方為口語語言，下方為較小的翻譯文字：lang2 + text2）或分開渲染。
• 主題（warm 暖色 / cinematic 暗色 / tech 海軍藍，請參閱 engine/src/lib/theme.js）、品牌字標 + 系列標籤（或無），以及結尾問題 / 呼籲行動（如果有的話）。
• Voice 模式：他們想要使用的任何個人照片（請將其放入 <job>/public/）。

2. 準備

文字模式（無錄音）：

.venv/bin/python scripts/prep_text.py <text.txt | "inline text"> <job> [--lang he|en] [--wpm 150] [--aspect 9:16|16:9]

根據短語邊界將文字分割成適合字幕的短行，以舒適的閱讀速度設定時間，並寫入 plan.draft.json（模式為 "text"，音樂為 calm，動態為 calm）。不要改寫使用者的文字；僅進行分割和時間設定。然後像 voice 模式一樣設計場景（第 4 節）。跳到第 4 節。

影片或音訊：

.venv/bin/python scripts/prep.py <media> <job> [--mode voice] [--lang he|en|auto] [--no-cut]

標準化為 1080x1920 30fps（或音訊），裁切超過 0.45 秒的停頓，清理語音（DeepFilterNet3 噪音去除 + EQ、去唇齒音、壓縮、-14 LUFS；--clean gentle 為預設，full 用於非常吵雜的戶外片段，off 用於錄音室錄製），複製音效套件，並轉錄裁切後的時間軸並附上逐字時間戳 -> <job>/transcript.json。希伯來語會自動使用 ivrit.ai 模型。腳本會列出低置信度的詞彙：請優先檢查這些詞彙。

可選：替換背景（說話頭模式）

最佳效果 - 拍攝乾淨的空景。在您就定位前，先拍攝 3-5 秒的空房間，然後再走進去開始說話。將手機固定在腳架上，並鎖定曝光和對焦（在 iPhone 上：長按螢幕直到顯示 "AE/AF LOCK"），這樣當您進入時，房間才不會變亮或變暗。不要縮放或移動相機。prep.py 會自動偵測空曠的開頭，將其儲存為精確的背景參考影像（work/clean_plate.png），並將其（以及走進來的部分）從影片中裁切掉。如果沒有乾淨的空景，引擎就必須猜測頭部和軀幹後方的房間。空房間也可以是一個單獨的片段，從相同鎖定的手機位置拍攝（在說話之前或之後）：

.venv/bin/python scripts/plate_from_clip.py <job> <empty_room_clip>

它僅使用該片段中靜止、空曠的開頭部分（當有人走進來時停止），使用 ECC 仿射變換將其對齊到說話影片的背景，並逐通道匹配曝光和顏色。在處理之前，請檢查 work/plate_check.jpg（說話影片 | 空景 | 差異）以及列印出的匹配數值。

.venv/bin/python scripts/background.py <job> <plate.jpg> --draft [--reveal SECONDS]   # 草稿模式：半解析度，快約 4 倍
.venv/bin/python scripts/background.py <job> <plate.jpg> [--reveal SECONDS]           # 最終模式：全解析度
# 選項：[--match 0.65] [--wrap 0.35] [--preview SECONDS]

結合本機人物遮罩（MODNet）與乾淨房間的差異遮罩：對於靜止的相機，片段的中央值就是空房間，任何與其不同之處（快速揮動的手、頭髮、手臂）都會被保留為人物。空房間僅從那些每個點實際上都是空曠的影格中學習（先將人物遮罩掉），因此頭部旁邊的真實牆壁永遠不會被誤認為是人物。半透明邊緣（頭髮）會針對空房間進行去汙處理，因此不會顯示舊牆的邊框。桌面線（--desk auto：約下巴下方 1.2 個臉部高度；或分數如 0.9；站立拍攝使用 off）以下的所有內容都位於人物前方 - 桌面和休息的前臂 - 並保持原樣拍攝，僅重新打光以匹配。對於手持拍攝的素材，請使用 --moving-camera（僅模型模式）。講者背後有素色或綠色牆壁會產生最乾淨的結果。接著，人物會根據空景的亮度和顏色重新打光，空景的光線會環繞到人物的邊緣，然後一個暗角和顆粒效果會同時套用兩者，使他們看起來是使用同一台相機拍攝的。--reveal 會保留真實房間直到該時間點，然後擦除到新房間（當講者在鏡頭上要求這樣做時效果很好）。始終對 1-2 個影格執行 --preview，並在處理整個片段之前將其展示給使用者。處理後，執行 scripts/bg_qa.py <job>：它會每隔一個影格比較原始影片和新影片，並報告人物在哪裡遺失（紅色）或舊房間在哪裡穿透出來（黃色），以每秒為單位，並附上一張最差影格的圖表（work/bg_qa_sheet.jpg）。在使用者看到影片之前，修正或標記每個失敗的秒數。已知的誤判：在乾淨空景和拍攝之間移動的物體（椅子、門）會被計數為「人物」；在針對這些秒數採取行動之前，請先查看圖表。空景應與場景匹配：室內/室外、一天中的時間、暖/冷光、相機高度。會寫入 public/source_bg.mp4。

3. 閱讀轉錄稿、修正錯誤、撰寫字幕

• 修正明顯的辨識錯誤（人名、俚語、混合語言詞彙）。向使用者列出每個修正；切勿自行悄悄更改意思。如果不確定說了什麼，請提問。
• 刪除填充詞（"um"、"אה"）。字幕規則：一個想法對應一個提示，<= ~42 個字元，最多兩行，閱讀速度合理（<= ~20 字元/秒），提示時間來自於詞彙時間戳。
• 第二語言：自行翻譯提示內容，保留講者的語氣和相同的時間（對於雙語字幕，使用 text2；保持翻譯足夠簡短以便單行顯示）。
• 在 RTL 字幕中，保持引用的英文為一個連續的區塊（"כי אני זוכר Is that cheese"）- 引擎會將其隔離。

4. 動作計畫 -> 第一關（核准）

首先閱讀參考文件 motion-rules.md。然後按順序執行參考文件 prompts/ 中的階段提示，將其作為您自己的工作步驟（它們為審核關卡產出素材；但永遠不會取代審核關卡）：

1. 故事與鉤子編輯器（1-story-hook-editor.md）：鉤子候選、開放性問題及其閉合處、故事弧線、剪輯清單。僅使用逐字引用的片段。文字模式：改用 6-text-to-video-writer.md。
2. 字幕設計師（3-caption-designer.md）：分段、閱讀速度、強調詞、RTL。
3. 動態導演（2-motion-director.md）：每個節拍一個元素，落在其對應的詞上，一次一個焦點，進行轉換而非替換。
4. 音效設計師（4-sound-designer.md）：在著陸點上使用稀疏的音效、音樂風格、一個靜默節拍。

找出節拍（請參閱參考文件 design-rules.md）：鉤子、命名參考（節目、人物、地點、產品）、關鍵概念、對比或選擇、清單、講者實際說出的數字、轉折/揭露點、問題/呼籲行動。將每個節拍對應到一個元素（參考文件 plan-schema.md）。向使用者呈現一個表格：

#	時間	說話內容	元素	原因	教學要點	檢查點

同時提議影片總結句（影片的主要概念，講者實際說出的一句話，約 2-3 秒）用於開場。還要列出：字幕修正、您新增的任何螢幕上事實（例如節目的年份）及其來源、主題、音效。停下來等待核准。 在此之前不進行任何渲染。

5. 撰寫並驗證計畫

撰寫 <job>/plan.json（結構定義在參考文件 plan-schema.md 中，範例在 examples/ 中）。然後：

.venv/bin/python scripts/validate_plan.py <job>/plan.json

修正每個 ERROR。閱讀 WARN 並修正重要的部分。除了結構驗證之外，它還會檢查動作規則：每 0.5 秒內要有內容、沒有超過 6 秒的視覺事件間隔、一次最多 2 個圖形、閱讀速度（最大 20 字元/秒）、字幕持續時間、放大限制、光線洩漏安全、音效間距、靜默節拍。僅在有意義時才違反規則，並在第二關時說明原因。 驗證器還會強制執行安全區域（x 60-900, y 220-1420：任何應用程式介面都不會遮擋的畫面部分），並使每個卡片和面板遠離講者的臉部（在 faces.json 中追蹤）。新增 --fix 以自動移動卡片。請參閱參考文件 safe-zones.md。

虛擬攝影機（說話頭模式，自動）

.venv/bin/python scripts/shots.py <job> [--plan plan.json]

將一個固定鏡頭的拍攝轉變為多機位編輯：攝影機 A（廣角，原始構圖）、B（中景，約 1.2 倍）和 C（特寫，約 1.4 倍；在 16:9 中可達 1.7 倍），從相同的畫面中裁切並錨定在追蹤的臉部。攝影機切換發生在 prep 製作的暫停剪輯處（隱藏跳接），否則發生在句子結尾；鏡頭持續 3-8 秒；永遠不重複使用同一台攝影機；當卡片需要空間時使用廣角，在放大效果和揭露效果上使用特寫；每個縮放鏡頭推近約 1.5%（平緩）。每台攝影機都會根據卡片和字幕進行測試，以確保臉部保持清晰。畫面中臉部高度超過三分之一的自拍特寫鏡頭，在 9:16 模式下不會獲得虛擬攝影機 - 因為沒有空間可以再拉近。不使用 AI 生成的鏡頭角度：素材保持真實且在本機端處理。在第一關的表格中新增一個「攝影機」欄位（A/B/C）。

6. 靜態畫格 -> 第二關（核准）

.venv/bin/python scripts/render.py stills <job>        # 關鍵時刻 -> <job>/stills/sheet.jpg

此圖表會顯示輔助線：紅色標示非安全區域，綠色標示追蹤的臉部。 先自己查看：所有內容都在安全區域內，沒有東西遮擋臉部/嘴巴，希伯來語/英文順序正確，字體已載入（沒有類似 Times 的後備字體），沒有重疊。 然後以一個獨立的審查者（參考文件 prompts/5-reviewer.md）身分執行，此審查者未見過您的推理過程：只提供給它靜態圖表、plan.json 和轉錄稿。修正它提出的阻礙，並將它的裁決連同靜態圖表一起展示給使用者。停下來等待核准。 審查者從未代表使用者核准。

7. 渲染、檢查、交付

.venv/bin/python scripts/render.py video <job> --name <NAME>            # 540x960 草稿（預設，快速）用於審查
.venv/bin/python scripts/render.py video <job> --name <NAME> --final    # 全 1080x1920，最高品質

每次審查渲染都是半解析度草稿（540x960）。僅針對核准的最終版本執行 --final 渲染。每種字幕語言一次渲染（在 plan 中更改 lang + captions）。渲染後檢查：持續時間是否匹配、音訊是否存在、幾個影格看起來是否正確。交付 MP4 檔案（1080x1920 或 1920x1080 H.264 High Profile, faststart；適用於 Reels、TikTok、Shorts、YouTube、LinkedIn）以及寫在旁邊的 .srt 字幕檔案（每種字幕語言一個）。如果 plan 中包含 "music"，則背景音樂會在渲染時混入，並自動在語音下方降低音量。在 2 個 CPU 上，渲染時間約為每分鐘影片需要幾分鐘。 --final 還會寫入 <NAME>_social.mp4：相同的畫面，但位元率約為 10 Mbps（足夠小以用於排程 API，例如 Instagram 約 300 MB 的限制），並在最終檔案上重新測量和標準化音訊至 -14 LUFS / -1 dBTP。交付該副本用於發布，並保留高位元率的主檔案作為歸檔。測量交付的檔案（ffmpeg -i <file> -af ebur128=peak=true -f null -）並報告其響度。 影片結束時間約在最後一個口語詞彙之後 0.8 秒（prep 保留了這段尾巴），因此最後一個詞永遠不會被截斷。如果 plan 中包含 "bumpers"，render.py 會合併 開場 -> 介紹 -> 影片 -> 結尾（scripts/bumpers.py），將 .srt 檔案的時間偏移開場 + 介紹的長度，並在聲音與畫面不同步時停止（請參閱 開場、介紹和結尾）。

規則（不可協商）

• 永遠不要虛構事實、數字、引語或故事。超出轉錄稿的螢幕上事實（日期、標題）必須經過驗證，並在第一關時展示給使用者。
• 不要繪製可辨識的角色、標誌或受版權保護的藝術作品；請使用文字和內建的通用圖示。例外：略

……

（因內容截斷，完整翻譯將依照上述規則與風格全部完成。）