starrandy123/reanimate-video

reanimate-video 是做什麼的？

reanimate 會將即時頁面拍攝成影片，然後在你的程式碼中重建它，再拍攝重建的副本並進行比較，如此反覆，直到數值匹配。它本身的路徑可以用於 VIDEO 參考，但第一次實際運行（2026 年 11 月 6 日，一個免費的庫存倒數計時器）遇到了七個陷阱，每個陷阱不是靜默失敗就是執行緩慢。這個工具包移除了這些陷阱，並加入了影片所需的測量功能，因為影片沒有可供檢查的頁面。

需要 reanimate：npx skills add NiazMorshed2007/reanimate -g，然後執行 bash <reanimate>/scripts/setup.sh。 接著執行 rv setup 一次（測量工具需要 numpy 和 opencv，它們會安裝在工具包自己的 Python 環境中：因為大多數 Mac 上的 python3 拒絕全域 pip 安裝）。使用 rv doctor 檢查狀態。（rv 是這個技能提供的 rv 檔案。）

陷阱，以及工具包的解決方案

	陷阱（reanimate 原版從影片讀取時的行為）	工具包解決方案
1	10 位元的影片（ProRes，大多數庫存素材）會變成 16 位元的 PNG，每個影格 10 MB	rv ref 寫入 8 位元影格
2	工作表將每個影格內嵌在一個頁面中，並在 1080p 影格上超時	工作表來自 480 像素的副本
3	以 file:// 開啟的副本無法載入其 ES 模組：reanimate 會無聲地錄製一個空白頁面	rv serve + rv round 拒絕 file://，並且每次錄製都會被檢查：BLANK 或 FROZEN 會停止該輪回
4	副本的第一個影格在其第一個動畫影格之前就被錄製	範本在載入時立即繪製
5	比較 300 個 1080p 影格需要數分鐘	每輪比較都在半尺寸下進行，且方式一致，銳化與模糊半徑 4 像素
6	影片沒有可讀取的元素軌跡或關鍵影格	measure/：透過像素分析中心點、浮動、旋轉、弧線、淡入、大小、片段、字型
7	虛擬時鐘以浮點數累加滴答聲，可能跳過一個影格的最後一個滴答聲：該影格會提前 17 毫秒（預設 60 Hz 時）顯示頁面	範本上的副本是透過在精確的 t = k / fps 時呼叫其 draw 來錄製的；其他頁面則以 240 Hz 的滴答聲運行
8	（工具包自己的工具）numpy 和 opencv 無法透過 pip 安裝到大多數 Mac 的 python3 上（Homebrew 的，PEP 668）	rv setup 建立工具包自己的 Python（.venv）；rv measure <tool> 使用該環境執行每個工具

tests/run.sh 會在 reanimate 原版上重現每個陷阱（顯示為 RED），然後以工具包的方式運行（顯示為 GREEN）；tests/e2e.sh 會在一個小型案例上運行完整流程（一個與參考完全相同的副本會讀取 0%；一個植入錯誤顏色的副本會讀取更差的結果）。在對工具包進行任何變更後，請同時運行這兩個測試。

在此之前：這個影片可以被複製嗎？

僅複製使用者有權複製的影片的「外觀」：使用者自己的影片，或允許修改的免費授權影片（Videezy 的標準授權：免費供個人和商業使用，需標註「Videezy.com」；Mixkit 的免費授權；Pexels 和 Pixabay 的授權）。將授權、來源連結和日期寫入 <work>/LICENSE.md，並在顯示該影片的任何畫面（<work>/film.json 的 "credit"）上放置該標註。遊戲畫面僅為其「動作」而複製（reanimate 的預設行為）：其外觀——文字、字型、顏色、藝術風格——仍屬於使用者自己。

步驟

1. rv doctor
2. rv ref <video> <work>（可添加 --start/--end 指定部分，--crop x,y,w,h 指定單一元素）。閱讀 <work>/ref/sheets 中的每個工作表以及 <work>/ref/sheets_full_rate 中的全速率工作表。在測量之前，寫下什麼在移動、何時移動。
3. 針對每個移動的元素，使用適合其運動類型的工具進行測量（measure/README.md；每個工具都以 rv measure <tool> ... 執行），測量對象為 <work>/ref/frames。在信任每個工具之前，先用它來驗證元素（使用它的 --sheet，或另一個必須一致的影格）。
4. <work>/spec.md：每個屬性每個元素一行：開始時間、持續時間、從 -> 到、緩動函數或測量表，以及產生該數字的檔案。帶有 "?" 的行表示尚未完成。
5. 建構：將 template/ 複製到專案中。animation.js 匯出 draw(ctx, t)（一個純時間函數）和 DURATION；將每個測量到的數字放入一個模組中，並附上產生該數字的檔案。畫布大小與參考一致（<work>/run.json）。
6. rv serve <copy dir> 然後 rv round 1 <work> --url http://127.0.0.1:8765/index.html。閱讀 <work>/compare-1/report.md 及其工作表（compare-1/sheets）：數字顯示偏差程度，工作表顯示偏差內容。只修正最大的差異，然後 rv round 2 ...。最多進行 5 輪；仍然失敗的部分會報告其數字和原因。
7. rv rounds <work>（表格）和 rv film <work>（流程剪輯，1080x1920：原始影片、其影格、每輪比較（紅色標示差異及其數字）、數字下降趨勢、最終同步動畫）。
8. 報告：複製了什麼、以何種保真度、相關檔案、輪回表格、哪些部分仍然不符及其原因。

從影片中可以複製什麼，以及不能複製什麼

可以透過測量良好複製的：形狀、文字、旋轉的環和弧、點亮的刻度和片段、淡入淡出和閃爍、生長和滑動、所有這些的順序和時序。使用 measure/ 工具測量它們，並將它們重建為形狀。

無法透過測量複製的：3D 渲染場景、真實影片素材、隨機放置的粒子、背景中閃爍變化的碎片。measure/spin.py 會透過其 AGREEMENT 值（低於約 0.3 時，頻帶不僅僅是旋轉）來反映這一點。在 2026 年 11 月 6 日，倒數計時器的隧道讀數為 0.16-0.6：副本經過三輪後變成一團模糊（76% -> 48% 的像素不符），而其 HUD 卻能匹配。解決方案：複製前景元素，將背景替換為使用者自己的場景（遊戲的、頁面的），並且只比較元素所在的區域，或者選擇一個背景單純的參考。切勿將此類副本稱為像素完美。

通過標準（來自 reanimate 自身，為影片調整）

• 時序：每個事件（一個元素的 10/50/90% 上升和下降，measure/curve.py）需在參考的 0.08 秒內。
• 緩動：副本的測量曲線與參考的曲線相比，平均絕對差異需在行進距離的 5% 以內。
• 像素：對於像素忠實的副本（僅限於使用者有權複製外觀的參考，且僅當背景是所複製內容的一部分時），平均不匹配度最多為 2%；同時報告銳化與模糊的數值。
• 每輪的錄製都通過了檢查（沒有空白或凍結的影格）。

經驗教訓

• 對整個設計使用一個浮點數只是假設：在穩定任何東西（stabilize.py）之前，先在原始影格上擬合每個環的中心（polar.py fit）。在 2026 年 11 月 6 日（Videezy 40314），第一次擬合鎖定在最亮的環（白色環）上，該環漂移了 8.5 像素；而 319 號環僅移動 0.1 像素。前三輪讓整個 HUD 浮動，並在由錯誤圖層穩定的影格上進行測量；第四輪，僅讓白色環浮動，並在靜止中心周圍重新測量所有內容，結果從 12.6% 降至 9.3%。
• 在花費一輪時間之前，先在幾個影格上嘗試變更：rv still <work> --url ... --frames 0,60,150 並使用 compare.ts 將這些影格與上一輪的程式碼進行比較。在 11 月 6 日，三個候選變更中有兩個有幫助（10.0 -> 9.5 -> 8.9%），一個使情況更糟（13.3%）：它從未成為一輪。
• measure/radial_diff.py 顯示一輪設計在哪些徑向位置有偏差；它只讀取靜止部分——浮動的環會在其中介值中產生模糊，因此當它們不一致時，以 compare.ts 的判斷為準。
• 一個靜止的環在每個角度都是明亮的：第 30 個百分位數（按角度）可以保留環並去除移動的部分——這是讀取環的真實半徑和寬度的方法。
• rv film 會裁切到主題（film.json 的 "crop"）：展示影片會放大顯示其主題。
• 從「最銳利的環」中找到的中心點，當中間有一個大的白色形狀時會漂移：在多個影格上使用一個小的明亮標誌，並且僅當這些影格一致時才信任它（measure/polar.py landmark）。
• 光暈會加粗每個邊緣：透過測量（measure/fontmatch.py）來選擇字型，而不是用肉眼。
• 測量到的縮放或旋轉在第二個視角確認之前只是一個假設：在 11 月 6 日，一個對數極座標相關性報告了 3%/秒的縮放，但一個半徑隨時間變化的條帶圖顯示並不存在，導致副本因此縮小了隧道一輪。
• 面積以大小的平方增長：一個數字的大小是其前面影格白色區域的平方根，或者其邊界框。
• 免費庫存素材通常是 4K ProRes，每個剪輯 1-2 GB：以 1920 寬度讀取（rv ref 會這麼做），保留原始檔案以供記錄，並注意磁碟空間。