KyaniteLabs/kinocut

kinocut 是做什麼的？

當代理需要結構化的影片編輯介面，而不是手寫 FFmpeg 指令時，請使用 Kinocut。它提供了 MCP 工具、Python 用戶端與 CLI，用於編輯、分析、字幕、音訊、Hyperframes、圖層合成以及本機重新利用工作流程。

預設路徑（請先執行此步驟）

1. 執行 kino doctor，然後執行 kino --format json info <file>。
2. 對於不熟悉的任務，請使用使用者的任務（例如，「移除贅詞」或「保持臉部在畫面內」）呼叫 search_tools，然後檢查回傳工具所需的輸入。使用 video_intent 規劃支援的意圖（可選的 goal= 會編譯一個 cutfile；360/desk/table/x4 目標也會提出一個 360_assembly_plan）。在渲染之前，請確認該提案確實滿足請求。
3. 渲染（video_cutfile_render、video_edit、工作流程或單一引擎工具）。對於 360：對該計畫執行 video_review_decide 並批准/拒絕，然後再渲染——切勿渲染 proposed 的計畫。.insv 會被拒絕；需要一個已拼接的 360 MP4。指南：docs/360_ASSEMBLY.md。
4. 執行 video-quality-check / assert_quality。除非跳過/ allow_fail，否則 repurpose 和 shorts-package 同步會在分數低於 80 時失敗關閉。
5. 人工視覺/音訊審查。切勿將收據視為已發布。

深度（救援、搶救、合成、Hyperframes、精簡音訊 S12）：docs/TOOLS.md、docs/RESCUE.md、docs/WORKFLOWS.md。工作流程允許清單：probe、trim、resize、convert、crop、add_text、merge、composite_layers、burn_in。

必要時載入相關指南。使用來源證據進行編輯決策；保留名稱、數字、否定和限定詞。回報遺失的證據或不支援的動作，而不是憑空捏造來源聲明、時間戳記或功能。規劃工具會提出編輯建議；它的存在並不表示所需的檢測器或模型已執行。程式碼負責時序、轉換、驗證和執行；人工審查仍獨立於模型判斷。

Revideo 本機程式碼影片流程（開發技巧）

當呼叫者需要一個可檢查的暫存專案時，請使用 revideo_materialize、revideo_install 和 revideo_render。對於單次呼叫中的相同受保護步驟，請使用 revideo_render_job。所提供的場景是可信的可執行 TypeScript：請在使用前檢查它，且切勿執行不受信任的場景程式碼。相依性安裝可能會存取 npm；渲染會在本地針對 Kinocut 的固定模板執行。渲染收據會將觀察到的媒體和輸出位元組綁定到精確的、有限範圍的磁碟作業檔案摘要。.mp4、.webm 和 .mov 會選擇固定的 MP4、WebM 和 ProRes 4444 匯出器模式，並在發布前進行驗證。請根據輸出位元組驗證收據，執行 video_quality_check 和 video_release_checkpoint，然後要求人工視覺審查。

從這裡開始

• 閱讀 ../../README.md 了解安裝和安全性合約。
• 在 FFmpeg / Hyperframes / AI 擴充功能之前執行 kino doctor。

選擇一種介面

• MCP：最適合 Claude Code、Cursor、Codex 風格的用戶端和其他代理主機。設定 uvx --from kinocut kino。
• CLI：最適合直接的本機編輯、快速診斷、composite-layers --dry-run、批次作業和 CI 友善的 JSON 輸出。
• Python 用戶端：最適合需要結構化結果、輸出路徑和已儲存圖層計畫收據的可重複管線。

360 雙鏡頭組裝（已發布 1.14.0）

當來源是來自任何相機（Insta360、Ricoh Theta、GoPro MAX、DJI Osmo 360 …）的已拼接等距柱狀投影 360 MP4，且需求是兩個虛擬相機作為分割/切換/子母畫面/單一畫面時使用。

1. 執行 video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) 或 Client.propose_360_assembly(...)。
2. 顯示相機、佈局和分鏡圖。不要憑空捏造 yaw/pitch。
3. 執行 video_review_decide / Client.decide_360_assembly 並帶有 approve 或 reject。
4. 僅渲染已批准的計畫（Client.render_360_assembly 或 video_review_decide + output_path）。

沒有 video_360_* MCP 工具，也沒有 kino 360 指令。CLI 的 intent 和 review-decide 不執行此編譯器。Director 鉤子接受注入的 JSON 提案者；設定的模型名稱本身不會執行模型。雲端提案需要 allow_cloud；director 永遠不會寫入像素。

產品/物體去背（已發布於 1.15.1；目前為 1.15.3）

可選的物體去背擴充功能已於 1.15.3 發布。請使用現有的 hyperframes-remove-background / hyperframes_remove_background 指令。預設模型是人物。對於目錄 SKU、珠寶、瓶子、鞋子、包裝或任何非人物的物體：

1. 執行 hyperframes_remove_background(info=true) — 列出模型，無需下載。
2. 執行 pip install "kinocut[object-matte]"，然後使用 model="birefnet-general"。
3. 產品影片可選用 --mask-interval 3。如有殘留的轉盤/支架/三腳架/掃掠，可選用設備覆蓋。
4. 使用 composite-layers 合成到商品底板上。將所有 src 保留在規格目錄內。

不要憑空捏造 video_product_matte；這不是一個新的 MCP 工具。不要在缺少物體擴充功能時回退到人物模型。指南：docs/PRODUCT_MATTE.md。範例：examples/product-matte/。

專用影片救援

當需求是修復一個本機片段，同時保留其來源、故事和時間軸時，請使用 video_rescue_*、rescue-* 或 Client.rescue_*。

必要順序：

1. 呼叫規劃並儲存規劃成品。
2. 向使用者呈現 safe_repairs、recommendations、unavailable_repairs、blocked_repairs、預覽、套件意圖、功能和估計。
3. 在渲染前檢查規劃。取得或推斷對 safe_repairs 中 ID 的明確批准；省略 ID 列表表示已審查規劃中的所有安全 ID。
4. 使用那些已批准的安全 ID 呼叫渲染。
5. 檢查渲染收據，然後回報告套件路徑、不可用的附屬檔案、完整性、閘控驗證、隱私、恢復和清理狀態。

切勿直接從未經審查的規劃進行渲染。切勿將建議 ID、不可用 ID 或封鎖 ID 加入批准。切勿使用雲端工具、燒錄救援字幕、改寫來源，或將「不可用」視為自動失敗。取消或驗證失敗必須保持未發布或隔離狀態。

確定性 AI 影片檢查

當生成的素材需要在編輯決策前取得證據時，請使用 video_ingest、video_preflight 和 video_inspect_temporal（或其扁平化 CLI 和 Python 等效功能）。先進行擷取，然後透過回傳的雜湊值來定址素材。切勿在公開邊界用主機路徑取代該素材 ID，或建構 AssetRecord。時間檢查會回傳完整的取樣幀和動態條紋套件、確定性發現，以及明確的不可用提供者功能。提供者缺失是預期情況，不得觸發下載或網路回退。

受治理的 AI 影片審查與搶救

對於精確素材的編輯決策和衍生復原，請使用 video_verdict、video_acceptance_eval、video_body_swap 和 video_salvage（或其扁平化 CLI 和 Python 等效功能）。未批准的判決可能會捕獲代理分析，但已批准的處置必須綁定一個主動的、精確的人為決策，並帶有明確的需求、角色和成品證據。驗收評估是衍生性的，而非批准行動，且每個搶救輸出都從一個新的未批准審查插槽開始。

切勿憑空捏造決策 ID、傳遞未儲存的批准，或尋找強制/覆寫路徑。除非呼叫者選擇明確的政策，否則身體交換會拒絕持續時間不匹配的情況。搶救需要一個現有的私人專案、一個已儲存的來源素材、一個有界限的配方政策，以及一個精確的驗收規格 ID。

驗收評估需要主動儲存的 acceptance_spec_id 和 verdict_ids，而非呼叫者建立的證據物件。公開的身體交換總是先接受 project_dir，且兩個來源路徑都必須解析為該專案中的有效素材。

在操作此工作流程之前，請閱讀 docs/AI_VIDEO_REVIEW_AND_SALVAGE.md。將每個衍生作品視為新的未批准工作，並在發布前保持明確的人工視覺/音訊閘控。

救援後規劃

當需求需要語義檢索、一般清理編輯、主體感知轉換、還原、合成、創意協調或遠端輸出時，請使用配對的 video_* MCP 工具、扁平化 CLI 指令或 Client 方法。傳遞 JSON 相容的證據和意圖；在任何單獨的渲染步驟之前，先呈現回傳的規劃和差異。

切勿憑空捏造來源描述、隱藏不確定性、從規劃推斷批准，或將缺少本機執行器視為使用雲端提供者的許可。遠端工作需要單獨的輸出清單和批准。缺乏證據或功能的規劃必須棄權。

圖層合成

當編輯是圖片、影片或純色圖層的有序堆疊時，請使用 composite-layers / video_composite_layers，特別適用於下方三分之一、子母畫面變體、模糊背景版、遮罩/去背，或特定平台的佈局變體。

當代理需要變換、不透明度、開始/持續時間視窗、遮罩/去背 Alpha 來源，或可在發布前審查的收據時，請優先使用此路徑而非原始 FFmpeg filtergraph。

規劃優先流程：

1. 使用 canvas、有序的 layers 和明確的輸出編寫 JSON 規格。
2. 執行 kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json。
3. 檢查圖層計畫中的來源雜湊值、filtergraph 雜湊值、變換、旋轉/樞紐、混合模式、時序視窗和遮罩。
4. 僅在計畫看起來正確後才進行渲染。
5. 執行 video-quality-check、storyboard 或 thumbnail，以及 video_release_checkpoint。

合成器支援允許清單中的全畫布和定位混合模式（multiply、screen、overlay、darken、lighten），並帶有不透明度和時序視窗；收據保持 layer_plan v2。非 normal 混合在兩種幾何中支援不透明度和 start/duration 視窗：在 {0,0} 處無明確尺寸的全畫布，或具有正整數 width 和 height 以及畫布內非負整數位置的定位矩形。RGB 混合避免將顏色算術應用於子取樣色度平面。縮放、旋轉/樞紐、遮罩/去背、分數位置和畫布外矩形保持延遲，並以 unsupported_blend_geometry 失敗關閉。影片圖層和影片遮罩在其宣告的開始處開始播放。將所有來源和遮罩保留在規格目錄內。輸出僅為影片；anchor 是與 pivot 不同的位置別名。旋轉 + 遮罩、音訊合成和完整 NLE 適配器保持延遲。在人工審查之前檢查收據；不要將其視為完整的 NLE 替代品。

代理工作流程引擎

當編輯是多步驟作業（而非單一工具呼叫）時，請使用工作流程引擎，透過一個 JSON 作業規格來規劃、驗證、渲染、復原和證明——透過 video_workflow_*（MCP）、workflow-*（CLI）或 Client.workflow_*（Python）。操作是小型允許清單（probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in），綁定到經過審查的引擎；媒體引用是符號化的（@sources.*、@work/*、@outputs.*）且限制在工作區內；所有操作都失敗關閉。請參閱 ../../docs/WORKFLOWS.md。

規劃 → 驗證 → 渲染 → 檢查 → 恢復：

1. workflow-validate --spec job.json — 廉價的結構性閘控；不渲染任何內容。
2. workflow-plan --spec job.json --save-plan plan.json — 乾執行操作圖 + 來源探測/雜湊值；不渲染任何媒體。
3. workflow-render --spec job.json --save-receipt receipt.json — 順序執行；產生出處收據（每個步驟的雜湊值、清理清單、確定性警告）。為批次變體新增 --all-variants。
4. workflow-inspect --receipt receipt.json — 唯讀完整性重新檢查 + 人工審查指標，然後再信任收據。
5. workflow-render --spec job.json --resume receipt.json — 恢復一個失敗但保留中間產物的作業（規格變更時失敗關閉）。

收據僅儲存相對於工作區的路徑——保持規格和範例收據不含主目錄路徑、使用者名稱和令牌。

工作流程

1. 首先檢查輸入：kino info <file> 或等效的 MCP/Python。
2. 制定低風險計畫：修剪、調整大小、標準化音訊、字幕、疊加、效果或 Hyperframes 渲染。
3. 在執行昂貴或破壞性匯出之前，優先使用預覽或乾執行清單：
   • 使用 preview 進行快速視覺審查。
   • 在 repurpose 之前使用 repurpose-plan。
   • 在完整渲染之前，使用 Hyperframes 的 inspect、snapshot 或 still。
   • 對於已儲存的 shorts 計畫：shorts-plan-show → shorts-review → shorts-render → shorts-package。
   • 對於精簡音訊：sound-capabilities 然後 sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr（或 kino sound <action>）。
   • 提供音訊持續時間、增益、響度和設定檔版本的數值；布林值在強制轉換之前會被拒絕。明確的無效計畫無法選擇範例計畫。類型化計畫會重新驗證；請參閱 docs/SOUND_INPUT_VALIDATION.md 了解特定欄位的相容性規則。
   • 真實的 ASR 使用已雜湊的音訊/參考請求和明確的根目錄；保留其文字記錄 ZIP 並誠實地回報不匹配。僅使用快取的本地 Whisper；無自動下載。僅有雜湊值的舊式呼叫是模擬。請參閱 docs/SOUND_ASR_REQUESTS.md。
   • 對於真實的單聲道/立體聲 PCM16 響度品質保證，提供 SoundLoudnessRequest 加上專案根目錄，並檢查 within_tolerance；成功測量可能不符合規範。需要 FFmpeg，且無輸入的測試裝置標示為示範。請參閱 docs/SOUND_LOUDNESS_REQUESTS.md。
   • 對於保留的單聲道/立體聲母帶處理，提供 SoundMasterRequest 和明確的根目錄給 sound-master-render；請參閱 docs/SOUND_MASTER_REQUESTS.md。檢查已驗證的 ZIP、實際標準化模式和測量的最終政策合規性，然後再聆聽。輸入通道會被保留；現有輸出永遠不會被取代。
   • 對於實際的本機 EN/ES 字幕，使用帶有 hyperframes-caption --language en,es 的 video_caption（或 CLI/Python 等效功能）。對於 SRV3 分段，使用 mode=srv3。自動說話者偵測需要 detect-speakers 和 loudness=on 參數。請參閱 docs/CAPTIONS.md。