github.com/feitangyuan/onetake

工具使用手冊 · 動態設計 / Agent Skill

OneTake
連續運鏡
與 HTML 動效

OneTake 是製作短篇產品展示影片的 Agent Skill，以單一 HTML 合成、時間函式與動作庫控制畫面，再逐影格渲染成影片。它將段落之間的元素延續、節奏、構圖與聲音納入自動檢查；官方授權僅允許非商業用途。

1080p

草稿預設 · 30 fps

正式輸出 · 60 fps

內附視覺預設

PolyForm 非商業授權

工具定位與核心概念

單一合成檔與
畫面延續

OneTake 由 Patrick（feitangyuan）公開原始碼，主要處理短篇產品介紹、預告與功能展示。Agent 依工作協定編寫 HTML／Canvas 合成，Python 腳本透過 Chromium 擷取畫面，再交由 FFmpeg 編碼。

Carry 指某個可見元素跨越段落邊界並轉變成下一段畫面的構成，例如輸入框擴展為視窗，或視窗重排成手機介面。分鏡需記錄每次交接保留的元素，並透過 probe 檢查。

時間函式 指任意時間都能直接算出畫面狀態。合成呼叫 window.__seek(t)；重複前往同一時間必須得到相同畫面，才能支援逐影格渲染與快門內的多次取樣。

官方製作順序

參考分析→ 概念選擇→ 節拍表→ 合成與素材→ 草稿與聲音→ 驗收

主要組件

SKILL.md：製作程序、概念選擇與品質規則。
lib/motion.js：回傳位置、比例、透明度與矩陣等數值的動作函式。
lib/ui_kit.js：介面重建、元素量測、語言字串及時間映射。
scripts/：參考分析、畫格檢視、渲染、聲音及自動驗收工具。

長篇談話影片與既有影片的一般剪輯，不是官方列出的主要使用範圍。來源：製作協定、合成架構。

Skill 與工具相依

安裝位置與
環境準備

依使用的 Agent 選擇下列安裝位置。這兩條指令直接取自 README；目標目錄若已有安裝，先確認既有內容，再決定更新方式。

git clone https://github.com/feitangyuan/onetake.git ~/.claude/skills/onetake

git clone https://github.com/feitangyuan/onetake.git ~/.agents/skills/onetake

依用途準備相依工具

合成與渲染：Python 3、Playwright 與 Chromium、NumPy、SciPy、Pillow、Matplotlib、FFmpeg／ffprobe。
動作庫測試：Node.js；使用 node scripts/test_motion.js 檢查動作函式的數值。
視覺預設：fonttools 與 brotli；look.py 會將使用的字型子集內嵌到 look.js。
參考片動態分析：opencv-python。
旁白：faster-whisper 與 Kokoro；官方另列 kokoro-onnx、soundfile，以及日文所需的 misaki[ja]、unidic-lite。

安裝後以自然語言向 Agent 提供產品畫面、參考片、片長及使用目的。官方流程先提出三種視覺概念供選擇，再製作節拍表與合成。

來源：README 安裝說明、完整相依清單、look.py。

授權範圍。官方使用 PolyForm Noncommercial 1.0.0，README 明確標示不允許商用。此處的安裝範例用於學習與非商業實驗；商業專案需另向權利人確認授權。

能力與腳本對照

合成、渲染與
驗收工具

動作庫提供可重複計算的數值，合成檔負責畫面，腳本負責擷取與檢查。以下按實際使用階段分組。

分析 · 01

analyze_ref.py

參考片量測

產生動態能量圖、切點、靜止比例與影格總覽，建立節奏參考。

視覺 · 02

look.py

色彩與字型

選擇預設、從截圖取色、檢查對比，輸出帶字型子集的 look.js。

素材 · 03

record_footage.py

實際網站 操作素材

透過 Playwright 操作網站，記錄影格、指標路徑與操作起始標記。

合成 · 04

motion.js

時間函式 動作庫

包含文字入場、形狀變換、碰撞、相機與模擬；輸出數值供 DOM 或 Canvas 使用。

介面 · 05

ui_kit.js

介面重建與 語言映射

提供 UI 量測、畫面字級、聚焦框及 timeWarp，協調旁白與原時間軸。

預檢 · 06

probe.py / stills.py

連續性與 定格檢查

在完整渲染前檢查可見元素、段落交接與指定時間的畫面。

渲染 · 07

render.py

逐影格 影片輸出

以快門取樣產生運動模糊，輸出 MP4 與 .render.json；--final 切換為 4K60。

聲音 · 08

sfx_palette.py / vo_tools.py

音效與 旁白工具

提供合成音效材料、語音產生、詞級時間與字幕處理；聲音配置仍由影片事件決定。

驗收 · 09

verify_promo.py

節奏與 品質判定

檢查靜止段落、聲音、連續性、曲線與主體出框；各項檢查取決於提供的參數。

依問題選擇工具

目前問題	先做的檢查	修正位置
段落只是輪流出現	Probe 交接結果	節拍表與延續元素
放大後文字難讀	UI 字級與鏡頭尺度	介面重建與構圖
快速位移出現分身	快門與取樣設定	位移回報及渲染參數
更換語言後聲畫錯位	詞級時間與時間映射	同一合成檔的語言資料

來源：動作庫、合成與渲染、功能展示。

官方製作原則

節奏與連續性的
設計條件

製作協定要求先決定概念，再選擇動作與視覺。模板可提供程式架構，但其故事、配色與節拍不應自動成為每支影片的預設。

三種不同的視覺概念

分別描述畫面由什麼構成、段落如何交接，以及採用的視覺方向。選定一種後才寫節拍表；換文案但沿用相同卡片結構不算不同概念。

來源 · SKILL §2

每個段落的延續元素

在節拍表列出時間、動作、靜止部分及交給下一段的元素。可用 morphRect、iris、zoomThrough 等動作實作；允許的硬切需符合選定概念。

來源 · rhythm

長短節拍與靜止段落

官方設計規則要求鏡頭長短至少有四倍差異，並保留畫面與聲音的停頓。這是創作規則；驗收腳本對節拍另採變異係數判定。

來源 · SKILL §3、verify_promo.py

可見的動作原因

讓指標、角色或物件的行為引發畫面反應。相機使用畫面座標追蹤主體；在 __meta.inFrame 宣告必須留在畫面中的元素。

來源 · composition

相同時間的相同畫面

每次 seek 都直接設定完整狀態。物理模擬使用固定種子預先計算，不在渲染路徑呼叫 Math.random() 或累積前一影格的狀態。

來源 · 時間函式契約

以產品實際內容重建介面

按截圖重建 UI 時，逐狀態與原畫面比對。圖表數值、結果與輸出檔名須取自產品實際資料；第二語言使用字串表及時間映射。

來源 · product-demo

非商業學習範例

15 秒介面展示的
製作與驗收

以下是本手冊設計的操作示例，沒有實際生成影片，也不代表已取得商業使用授權。目標為個人筆記 App 的學習展示，素材包含介面截圖、真實範例內容與可使用的參考片。

先請 Agent 提出三種概念。此處假設讀者選定「文字插入點延伸為筆記卡片，卡片展開為列表，最後收攏成圖示」，再為這個概念編寫 0、2、2.5、6、9、13.5 秒開始的六個節拍；時間是示例設定，須隨成片調整。

Agent brief · 本手冊示例

需求 › 為我的個人筆記 App 製作 15 秒非商業學習展示。用提供的截圖重建介面，畫面內容使用附上的真實範例。先分析參考片，提出三種不同的視覺概念，等我選定。

概念選定後的製作要求 › 每個段落列出延續到下一段的元素。以單一 comp.html 實作，保留 __seek、__ready 與 __meta。宣告主體的 inFrame 範圍，回報相機與物件的畫面位移。先交付定格總覽、1080p30 草稿與驗收結果。草稿確認後才輸出 4K60。

工作目錄與合成起點

以下命令在 OneTake 專案根目錄執行。先建立範例目錄；接著由 Agent 依選定概念編寫合成，補齊素材及聲音，不直接把模板的原故事當成新影片。

mkdir -p cases/my-film && cp templates/comp.html lib/motion.js cases/my-film/

模板素材相依。原模板含 footage 路徑與示範節拍。複製後必須依自己的素材修改，或改成不依賴影片影格的 DOM／Canvas 合成；確認瀏覽器能從頭到尾播放後，再執行以下命令。

預檢、草稿與正式輸出

此處假設合成檔、ref.mp4 與對應時間軸的 cases/my-film/sfx.wav 已完成。腳本不會自動替你補出這些輸入。

# 先檢查交接與指定畫面
python3 scripts/probe.py cases/my-film/comp.html --out cases/my-film/probe
python3 scripts/stills.py cases/my-film/comp.html \
  --times 0.7,2.4,3.8,6.2,9.9,13.8 --out cases/my-film/stills.png

# 產生 1080p30 草稿
python3 scripts/render.py cases/my-film/comp.html \
  --out cases/my-film/draft.mp4 --sfx cases/my-film/sfx.wav

# shots 必須與實際節拍起點一致
python3 scripts/verify_promo.py cases/my-film/draft.mp4 \
  --comp cases/my-film/comp.html --ref ref.mp4 \
  --shots 0,2,2.5,6,9,13.5
      

python3 scripts/render.py cases/my-film/comp.html \
  --out cases/my-film/film.mp4 --final --sfx cases/my-film/sfx.wav
      

交付驗收條件

定格總覽中的文字、指標與主體可見；介面內容與提供的原始畫面一致。
probe 的各段交接能指出延續元素；沒有未處理的 __seek 錯誤。
驗收結果逐項檢視 PASS、WARN、FAIL 與 skip；已通過的項目不代表略過的項目也已檢查。
draft.mp4 可完整播放，並保留 draft.render.json 記錄渲染設定。
正式輸出後再次播放及驗收 film.mp4；保留合成、素材來源與授權紀錄。

來源：合成與預檢、渲染參數、驗收行為。

授權、成本與檢查範圍

使用限制與
判定邊界

非商業授權。README 與 LICENSE 指定 PolyForm Noncommercial 1.0.0。公開原始碼不表示可直接用於付費客戶、商業宣傳或其他商業目的；商業使用需另確認授權。
案例未附合成原始碼。cases/ 提供成片與製作拆解，案例中的 comp、score 及聲音原始素材未公開。不要把說明文件提到的檔名當成已附上的可執行範例。
驗收有條件啟用。未傳入 --shots 會略過 cadence；未傳入 --comp 不會執行 continuity、curves 與 framing。未宣告 __meta.inFrame 也會略過主體出框檢查。
WARN 不會使總判定失敗。目前程式把 carry score 小於 0.5 判為 FAIL，0.5 至小於 0.7 判為 WARN，其餘為 PASS。總結果沒有 FAIL 即可通過；仍需閱讀各項警告與略過項目。
自動分數不判斷創意。官方記錄過 carry 1.00 仍因過於接近既有影片而退回的案例。Rhythm 文件也記錄過零個可判定邊界卻得到 1.00 的情況；需核對偵測範圍並人工檢視敘事。
旁白與安靜比例可能衝突。product-demo 文件明示，連續旁白影片可能因沒有足夠安靜區間而觸發音訊項目失敗。記錄適用情境，分別檢查削波、峰值與旁白清晰度，不為取得 PASS 而任意刪改內容。
快門取樣增加擷取成本。每個移動影格會多次擷取；workers 會啟動多個 Chromium 程序。先以草稿評估時間與資源，再決定正式渲染設定，不把案例耗時當成所有機器的保證。
字型與音樂需另行處理。新增文案後重新產生字型子集；中文等字元需提供適用字型。音樂、錄製音效與影片範例的使用權各有來源，專案授權不會自動涵蓋所有外部素材。

來源：LICENSE、案例範圍、驗收程式、旁白限制、聲音來源。

進階路徑

介面重建與
多語言版本

建議研讀順序

先看交接範例。在 gallery 動態示範與影格圖中觀察 morphRect、iris、zoomThrough 等動作，記錄什麼元素跨越段落。
建立最小合成。先實作一個主體、兩個段落與一個連續相機移動，確認任意跳轉時間仍得到一致畫面。
補齊畫面追蹤。使用 __track 回報畫面座標，__motion 回報相機與物件位移，__meta.inFrame 指定需要保留的主體。
重建需要展示的 UI 狀態。使用 ui_kit 量測文字與元件，逐狀態比對參考圖；只建立影片會顯示的介面狀態。
沿用同一合成檔新增語言。將文案放入字串表，用 timeWarp 對齊語意對應的旁白時間點，再以 frame_diff 檢查原語言版本是否保持一致。

官方案例與文件

OneTake launch 案例：提示框如何延續成不同展示畫面，以及相機的節拍配置。
Composition：時間函式、相機、快門模糊與畫面座標追蹤。
Product demo：UI 重建、旁白、字幕及多語言時間映射。

本手冊核對於 2026-09-27，依據原始碼 36072d3。README、SKILL 與渲染參考文件的部分數量及預設描述不同；本文未列動作總數，CLI 參數行為以當次腳本為準。