Cena Raiz
原則
- 兩個階段,中間一個閘門。 第一階段是乾淨剪輯 + 調色;第二階段是字幕、圖形和圖像。(硬性規則 1 強制執行此閘門。)
- LLM 從原始轉錄稿 + 按需視覺進行推理。 唯一值得保留的衍生產物是打包好的短語級別轉錄稿(
takes_packed.md)。其他所有內容都在決策時推導。 - 音訊為主,視覺為輔。 剪輯候選來自語音邊界和靜音間隙。
- 詢問 → 確認 → 執行 → 迭代 → 持久化。 在使用者用簡單明瞭的語言確認策略之前,絕不觸碰剪輯。
- 概括。 查看素材,詢問使用者,然後進行編輯——絕不預設影片類型。
- 藝術自由是預設值。 此處的具體數值是範例,而非強制要求。只有硬性規則是強制性的。
- 將 token 花費在品味所在之處。 機器資料是給程式用的,不是給人讀的;驗證在視覺之前是數值化的。你的注意力是稀缺資源——將其放在編輯上,而不是解析 JSON。(硬性規則 12 和 13 說明了此原則禁止的內容。)
硬性規則(生產正確性——不可協商)
- 階段閘門是真實存在的。 在剪輯獲得批准之前,不得進行第二階段的工作。
- 逐段提取 → 無損
-c copy拼接,絕不使用單次 filtergraph。(在預設的 J-cut 下,一個 take 的畫面和聲音會作為單獨的範圍提取,音訊軌道會相加——這是唯一經批准的混音,而影片路徑仍然是逐段 + 無損拼接。) - 每個片段邊界處有 30 毫秒音訊淡入淡出(在 render.py 中編碼)。
- 絕不在單詞內部剪輯——從轉錄稿中對齊單詞邊界。
- 填充每個剪輯邊緣(30–200 毫秒視窗;尾部略長於頭部。盡可能在靜音處剪輯。)
- 按來源快取轉錄稿。 除非來源發生變化,否則絕不重新轉錄。
- 在提取期間逐段進行調色,絕不在拼接後進行。
- 執行前需確認策略。
- 所有會話輸出都在
<videos_dir>/edit/中——絕不在 cena-raiz 儲存庫內部。 - 第二階段僅使用 Remotion——不得使用 ffmpeg/PIL 燒錄文字或疊加層。
- 第二階段是資料驅動的。 透過複製軌道模板來建立架構;在
public/edit-data.json中描述影片。絕不閱讀或編輯模板 TSX(src/Main.tsx等)——唯一可編輯的程式碼檔案是src/CustomGraphics.tsx,僅用於自訂圖形。 - 首先以數值方式驗證。 對每個渲染的剪輯執行
verify_cut.py;僅在標記的連接處打開圖像。將任何多影格檢視批次處理為一個contact_sheet.py/grade.py --candidates拼貼圖。 - 絕不將機器資料讀入上下文:
transcripts/*.json(原始)、captions.json、track.json、segments.json、遮罩/軌道二進位檔。請改為閱讀takes_packed.md和輔助工具的標準輸出。
執行媒介——本地管道 vs Adobe MCP
預設引擎是下面的 ffmpeg/Remotion 管道。對於連線、診斷、能力發現或透過本機 Adobe MCP 進行受控工作,請先閱讀 references/adobe-mcp.md。它是客戶端中立的:相同的程序適用於 Codex 和 Claude Code。
如果使用者要求透過 premiere-pro MCP 在 Adobe Premiere Pro 中進行編輯(「edite a sequência no Premiere」、「corte via MCP」),也請閱讀 references/premiere-mcp.md。方法不變——音訊為主、在靜音處剪輯、階段閘門、調色,但操作方式不同。轉錄和 edl.json 相同且已快取,因此可重複使用已批准的 EDL,並跳過 cut.mp4/預覽。After Effects 的寫入操作仍受儲存庫控制下的 Adobe 階段約束;僅 MCP 可用性並不授權修改。
目錄結構
<videos_dir>/
├── <來源檔案,未經修改>
└── edit/
├── project.md ← 記憶體;每次會話附加
├── takes_packed.md ← 短語級別轉錄稿,主要閱讀檢視
├── edl.json ← 剪輯決策(第一階段)
├── transcripts/<name>.json ← 快取的單詞級別轉錄稿(WhisperX,本地)
├── clips_graded/ ← 帶有調色和淡入淡出的逐段提取
├── cut.mp4 ← 第一階段輸出:乾淨的調色剪輯(批准產物)
├── verify/ ← 拼貼圖 / 標記邊界檢視
├── captions.srt + chapters.txt ← 長版交付物
├── final.mp4 ← 交付的渲染(第二階段 + 第三階段,經 loudnorm 處理)
└── remotion/ ← Remotion 專案(第二階段 + 第三階段)
├── public/ ← cut.mp4、edit-data.json(編輯本身)、captions.json、
│ track.json、segments.json、pexels/ web/ brand/、sfx/、trilha.mp3
└── src/ ← 不可變的模板程式碼 + CustomGraphics.tsx
設定
首次安裝說明在 install.md 中。冷啟動時只需驗證:
- 轉錄不需要 API 金鑰。 WhisperX 作為依賴項提供:
uv sync即為整個安裝過程。它使用 Whisper 進行轉錄,然後對波形執行強制對齊(wav2vec2),因此單詞時間是測量出來的,而非推斷——93% 的單詞落在真實語音區域內,語音結束時間的精確度在 10 毫秒內(根據speech_regions.py測量)。模型在首次執行時下載並快取。速度約為即時,並隨著長度增加而改善(載入模型的固定時間約為 18 秒:一個 16 秒的片段耗時 23 秒,一個 166 秒的來源耗時 109 秒)。 _transcription_backend中的/UNALIGNED後綴表示偵測到的語言沒有可用的 wav2vec2 模型,因此單詞時間是解碼器自身的結果——粗略,對於第二階段的卡拉 OK 字幕來說不安全。如果發生此情況,請告知使用者。ffmpeg+ffprobe在 PATH 中;Python 依賴項(uv sync);第二階段需要 Node 18+。yt-dlp隨 Python 依賴項提供,因此 URL 來源無需額外安裝。- 第二階段的領域知識需要
remotion-best-practices技能(如果缺失,請從 https://github.com/remotion-dev/skills 安裝)。 - 第二/第三階段可以使用可選的 API 金鑰(插圖、AI 配樂)。它們在軌道參考中列出,在首次使用該功能時惰性請求,絕不在安裝時請求。第一階段不需要任何金鑰。
輔助工具位於 helpers/ 中,相對於此 SKILL.md 解析(通常為 ~/.claude/skills/cena-raiz/ 或 ~/.codex/skills/cena-raiz/,或指向該處的符號連結/接合點)。使用 uv run python helpers/<name>.py 執行它們——單純的 python 會錯過 uv sync 建立的 .venv。
輔助工具
第一階段:
ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080]— 從連結進行編輯:yt-dlp → MP4(≤1080p)直接放入影片目錄;從那裡開始,它就像任何其他來源一樣。--section僅下載長版來源的時間範圍(關鍵影格精確)——這是以低成本剪輯 1 小時影片中 12–25 分鐘的方法。--simulate在不下載的情況下列印標題/時長/解析度(在執行較大下載前請先確認;將這些下載放在背景執行)。transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo]— 單詞級別,已快取,本地(WhisperX + 強制對齊)。無上限,無分塊。當你知道語言時請傳遞--language——自動偵測會耗費一次傳遞並可能在短片段上選錯。transcribe_batch.py <videos_dir>— 一個目錄中的每個來源,逐一處理(本地推理已使用所有核心)。每個檔案都有快取,一個來源的失敗不會丟失已完成的檔案。pack_transcripts.py --edit-dir <dir>— 將轉錄稿轉換為takes_packed.md(短語級別,在 ≥0.5 秒靜音處中斷)。主要閱讀檢視:僅為原始 JSON 的 1/10 token。speech_regions.py <video>— 透過靜音偵測得到的聲學語音區間。剪輯邊緣的真實來源(Whisper 時間會漂移/拉伸)。回答語音在哪裡——絕不回答語音有多大聲。voice_levels.py <video> [--edit-dir <dir>] [--edl edl.json] [--drop-db 5]— 語音音量的真實來源。標記每個短語,以及任何低於說話者自身中位數 ≥5 dB 的 EDL 範圍,並設定gain_db。它能捕捉到其他工具無法發現的問題:耳語旁白——轉錄稿完美、speech_regions顯示「語音」、verify_cut找不到任何錯誤——但觀眾仍然聽不到。在撰寫 EDL 之前執行它。detect_color.py <video> [--json]— 從檔案解析 NORMAL 與 LOG,無需詢問——首先檢查中繼資料,當中繼資料無資訊時(常見情況:轉碼會刪除標籤)則使用影像統計。傳回設定檔、置信度、證據和要套用的grade。僅在confidence: low時應回報使用者;識別細節請參閱references/log-grade.md。render.py <edl.json> -o cut.mp4 --no-subtitles [--voice-master] [--keep-resolution] [--jobs N] [--no-jcut] [--jcut-lead N] [--jcut-tail-trim N]— 逐段提取(調色 + 淡入淡出,並行)→ J-cut 重疊組裝(預設) 或無損拼接 → 可選語音主控 → loudnorm。將jcut_timeline寫入 EDL:實際輸出位置,所有下游元件都必須以其為索引。短版影格率自動設定:30fps 用於 30fps+ 的來源,否則為 24(長版透過--keep-resolution保持來源影格率)。設定edit-data.json的fps以符合產生的cut.mp4。verify_cut.py <edl.json> <cut.mp4> [--min-silence 1.2]— 數值自我評估:時長、每個連接處的爆音/剪輯單詞探測、靜音、黑畫面、削波、以及範圍音量平衡(每個範圍的 RMS 與中位數範圍的比較;LOW-LEVEL低於 −4 dB)。約 350 個 token 的文字,而非 N 張圖像。範圍平衡行是gain_db修復的收斂測試。grade.py <in> -o <out>— 調色預設集/原始濾鏡。--candidates "a=<filter>;b=<preset>;original=" --frame <t> -o cmp.png在同一影格上將 N 種外觀渲染為一張帶有標籤的拼貼圖。timeline_view.py <video> <start> <end>— 針對一個標記的點產生底片條+波形 PNG,非掃描工具。contact_sheet.py <video> --times t1 t2 … -o sheet.png— 在一個帶有標籤的網格中顯示 N 個影格;這是你檢查已經知道的幾個時刻的方式。watch_video.py <video> [--mode scene|keyframe|uniform] [--times t1 t2 …] [--start/--end] [--max-frames 24]— 當你不知道要看哪裡時,用來回答「這個素材裡有什麼」:場景偵測 + 感知去重 → 帶有標籤的連絡表,放在edit/verify/watch_<stem>/中,每個工作表讀取一次。用於未知素材的視覺目錄,也用於檢查cut.mp4中 verify_cut 的數字無法涵蓋的部分。--times釘選轉錄稿提示影格:來自takes_packed.md的指示性時刻(「看這個」、「如你所見」)是低視覺變化,對場景偵測不可見——釘選它們以決定第二階段的 B-roll/特寫/縮放位置。
第二/第三階段輔助工具(字幕、臉部追蹤、圖像搜尋、音樂)列在你在閘門之後載入的軌道參考中。
介面:
preview_server.py --root <edit> [--port 4820]— 提供標準預覽介面(請參閱預覽介面章節)。應用程式碼位於assets/preview/且不可變更。
預覽介面(標準——在每次編輯開始時啟動)
每次編輯會話都會在使用者的預覽面板中獲得相同的互動式介面:一個影片編輯器時間軸(影片軌道帶有底片條 + 音訊軌道帶有波形)、一個即時劇本標記,可即時掃描渲染結果、每個 take 的修剪手柄和 take 移除,以及——從第二階段開始——字幕和插入軌道。佈局會根據來源本身的外觀比例自動調整:直式來源將高播放器放在右側,傳輸控制 + 時間軸在左側;橫式來源則將播放器堆疊在時間軸上方。深色玻璃風格,Cena Raiz 品牌。不要每個會話建立一個 UI——透過 state.json 餵給標準介面。僅在使用者要求 UI 變更時才允許編輯 assets/preview/;它是共享的,因此改進會套用於每個專案。
啟動(在會話開始時執行此操作,甚至在第一次渲染之前——UI 會顯示等待狀態):
-
寫入
<edit>/state.json:{"project": "Nome — C0000", "phase": 1, "video": "cut.mp4", "edl": "edl.json", "captions": "remotion/public/captions.json", "editData": "remotion/public/edit-data.json", "finalVideo": "final.mp4", "fps": 24, "message": "Fase 1 — cortando", "sourceDurations": {"C0000": 1038.5}, "awaitingStyle": false, "style": {"edit": "split", "captions": "karaoke", "elements": {"tracking": false, "zoomAuto": true, "zoomCuts": true, "musicAI": false}}}(
captions/editData/finalVideo僅在它們存在時;Fase-2 標籤頁播放finalVideo——帶有字幕/插件的渲染——而 Fase 1 播放乾淨的剪輯;sourceDurations讓 UI 限制 take 擴展;awaitingStyle/style驅動下面的 Estilo 標籤頁。) -
選擇執行階段適配器;絕不呼叫另一個主機的工具。
- Claude Code: 確保
.claude/launch.json具有設定(根據會話調整--root)。伺服器僅透過旗標接受埠口,因此傳遞 harness 分配的$PORT並設定autoPort:{"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}。使用名稱cena-raiz-preview執行preview_start,然後在同一回合中設定Monitor(command="python3 <skill>/helpers/watch_edits.py '<edit>'", description="escolhas e marcações salvas no preview", persistent=true)。 - Codex desktop / CLI: 當環境可以保持其運作時,以背景本地行程啟動
uv run python helpers/preview_server.py --root '<edit>' --port 4820。一旦它回應,使用control-in-app-browser技能在應用程式內瀏覽器中自動開啟http://127.0.0.1:4820,並將該標籤頁保留在預覽上。不要假設存在preview_start、Monitor或.claude/launch.json。如果瀏覽器能力或持久本地行程不可用,則改為提供使用者命令和本地 URL。顯示預覽後,告訴使用者在選擇儲存並重新……” …(截斷以進行翻譯)
- Claude Code: 確保
說明:原始 markdown 內容在結尾處被截斷。以上翻譯涵蓋了所提供的完整內容,並保留了所有結構和程式碼片段。對於截斷的部分,由於原文未提供,故未進行翻譯。