Communitygithub.com

daniela-socoloski/raiz-engine

對話驅動的影片剪輯,適用於短版直式(Reels、TikTok、Shorts)與長版橫式影片。在需要剪輯、調色、上字幕、添加圖形、製作配樂、轉錄或準備影片編輯時使用。執行第一階段(音訊主導的乾淨剪輯與調色),獲得批准後,再進行第二/第三階段的 Remotion 視覺與音訊建構。

raiz-engine 是什麼?

Cena Raiz 是一個 AI 驅動的影片編輯引擎,專為處理從短版直式到長版橫式等多種格式而設計。它採用嚴格的兩階段流程:第一階段專注於音訊主導的乾淨剪輯與調色,以確保結構穩固;第二階段則利用 Remotion 加入字幕、圖形與音訊。該引擎強制執行一道「階段閘門」,在剪輯獲得批准之前,禁止任何第二階段的工作。 此工具的核心原則是將音訊視為主要參考點,視覺效果則以音訊為基礎。剪輯候選方案來自於語音邊界與靜音間隙,確保不會在字詞中間進行剪輯。它還透過本地 WhisperX 與強制對齊技術提供先進的轉錄功能,產生精確到字詞層級的時間碼,無需任何 API 金鑰。 Cena Raiz 支援 Claude Code、Codex Desktop/CLI 等平台,並提供一個標準化的預覽介面,包含互動式時間軸、波形與修剪控制項。它包含一套全面的輔助工具,用於攝入、轉錄、剪輯驗證、調色與語音平衡,所有操作都在本地執行,以確保隱私與速度。第二階段可以選擇性地使用 API 金鑰來獲取圖像或 AI 配樂,但第一階段完全不需要任何外部服務。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/daniela-socoloski/raiz-engine/tree/HEAD/skills/cena-raiz

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Cena Raiz

原則

  1. 兩個階段,中間一個閘門。 第一階段是乾淨剪輯 + 調色;第二階段是字幕、圖形和圖像。(硬性規則 1 強制執行此閘門。)
  2. LLM 從原始轉錄稿 + 按需視覺進行推理。 唯一值得保留的衍生產物是打包好的短語級別轉錄稿(takes_packed.md)。其他所有內容都在決策時推導。
  3. 音訊為主,視覺為輔。 剪輯候選來自語音邊界和靜音間隙。
  4. 詢問 → 確認 → 執行 → 迭代 → 持久化。 在使用者用簡單明瞭的語言確認策略之前,絕不觸碰剪輯。
  5. 概括。 查看素材,詢問使用者,然後進行編輯——絕不預設影片類型。
  6. 藝術自由是預設值。 此處的具體數值是範例,而非強制要求。只有硬性規則是強制性的。
  7. 將 token 花費在品味所在之處。 機器資料是給程式用的,不是給人讀的;驗證在視覺之前是數值化的。你的注意力是稀缺資源——將其放在編輯上,而不是解析 JSON。(硬性規則 12 和 13 說明了此原則禁止的內容。)

硬性規則(生產正確性——不可協商)

  1. 階段閘門是真實存在的。 在剪輯獲得批准之前,不得進行第二階段的工作。
  2. 逐段提取 → 無損 -c copy 拼接,絕不使用單次 filtergraph。(在預設的 J-cut 下,一個 take 的畫面和聲音會作為單獨的範圍提取,音訊軌道會相加——這是唯一經批准的混音,而影片路徑仍然是逐段 + 無損拼接。)
  3. 每個片段邊界處有 30 毫秒音訊淡入淡出(在 render.py 中編碼)。
  4. 絕不在單詞內部剪輯——從轉錄稿中對齊單詞邊界。
  5. 填充每個剪輯邊緣(30–200 毫秒視窗;尾部略長於頭部。盡可能在靜音處剪輯。)
  6. 按來源快取轉錄稿。 除非來源發生變化,否則絕不重新轉錄。
  7. 在提取期間逐段進行調色,絕不在拼接後進行。
  8. 執行前需確認策略。
  9. 所有會話輸出都在 <videos_dir>/edit/ 中——絕不在 cena-raiz 儲存庫內部。
  10. 第二階段僅使用 Remotion——不得使用 ffmpeg/PIL 燒錄文字或疊加層。
  11. 第二階段是資料驅動的。 透過複製軌道模板來建立架構;在 public/edit-data.json 中描述影片。絕不閱讀或編輯模板 TSX(src/Main.tsx 等)——唯一可編輯的程式碼檔案是 src/CustomGraphics.tsx,僅用於自訂圖形。
  12. 首先以數值方式驗證。 對每個渲染的剪輯執行 verify_cut.py;僅在標記的連接處打開圖像。將任何多影格檢視批次處理為一個 contact_sheet.py / grade.py --candidates 拼貼圖。
  13. 絕不將機器資料讀入上下文: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 會顯示等待狀態):

  1. 寫入 <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 標籤頁。)

  2. 選擇執行階段適配器;絕不呼叫另一個主機的工具。

    • 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。顯示預覽後,告訴使用者在選擇儲存並重新……” …(截斷以進行翻譯)

說明:原始 markdown 內容在結尾處被截斷。以上翻譯涵蓋了所提供的完整內容,並保留了所有結構和程式碼片段。對於截斷的部分,由於原文未提供,故未進行翻譯。

相關技能