13kailouis-stack/wecut

wecut 是做什麼的？

wecut 將 JSON 專案檔渲染為 MP4（或 GIF），使用本機安裝的 FFmpeg。您描述編輯內容，WeCut 負責處理影片工作。它絕不呼叫任何網路服務。

若 wecut 不在 PATH 中，請使用 npx -y wecut（Node 16+）替代下列所有指令。若 WeCut 以 MCP 伺服器方式連接，則相同步驟對應的工具為 wecut_doctor、wecut_probe、wecut_validate、wecut_preview（回傳幀圖像陣列）、wecut_render、wecut_list、wecut_schema、wecut_example、wecut_analyze（回傳幀圖板為單張圖片）、wecut_recipe_list、wecut_recipe_show、wecut_recipe_apply 和 wecut_recipe_from_project；需將專案以 project（物件）或 projectFile（路徑）傳入。

工作流程

1. 檢查機器一次： wecut doctor。若回報缺少 FFmpeg，請遵循其 hint（例如 sudo apt-get install -y ffmpeg）。
2. 將媒體放入工作目錄。 專案中所有路徑皆相對於執行 wecut 的資料夾（或 --root DIR）。不接受 URL：請先下載檔案。
3. 查看媒體資訊： wecut probe media/talk.mp4 media/music.mp3 提供時長、大小、幀率及是否有音訊。使用這些數據於 from/to。
4. 撰寫 project.json（格式如下）。wecut example podcast-clip 列印完整範例；wecut schema 列印 JSON Schema；wecut list 顯示所有風格、字型、轉場與濾鏡名稱。
5. 驗證： wecut validate project.json。錯誤會回傳 JSON 指標（/clips/0/to）及 hint。修正後重複驗證。
6. 渲染前預覽： wecut preview project.json --at 0.5,3,10 將小型 JPG 幀寫入 out/preview/。開啟查看構圖、文字大小與字幕位置。
7. 渲染： wecut render project.json。使用 --preset draft 進行快速 540p 檢查，預設 final 為最終輸出。

每個指令輸出一個 JSON 物件。結束代碼：0 正常、2 無效輸入、3 缺少依賴、4 渲染失敗、5 超過限制。可透過 wecut render - 以管線輸入專案。

專案格式

{
  "wecut": "1",
  "output": { "file": "out/clip-01.mp4", "ratio": "9:16", "res": 1080, "fps": 30 },
  "clips": [
    { "src": "media/talk.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } },
    { "src": "media/talk.mp4", "from": 795.5, "to": 812.0, "zoom": 1.15 }
  ],
  "texts": [
    { "text": "How I made my first $10k", "start": 0, "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } }
  ],
  "captions": { "words": "media/talk.words.json", "src": "media/talk.mp4", "style": "karaoke" },
  "audio": [ { "src": "media/music.mp3", "volume": 25, "loop": true, "duck": true, "fadeOut": 1.5 } ]
}

重要規則：

• 兩種時間軸。 片段 from/to 是來源檔案的秒數。其他所有內容（texts、overlays、audio.at、filters、effects）是最終影片的秒數。wecut validate 會顯示最終 duration。
• 轉場重疊。 片段 N 上的 transition 會與片段 N+1 融合，並使影片縮短其 duration。
• 取景。 預設 fit 為 cover（填滿並裁切）。使用 focus（0..1；x 0.3 保留左側）和 zoom 控制裁切。使用 "fit": "contain" 搭配 "background": "blur" 顯示完整畫面。
• 位置 為畫布的分數，0.5 為中心。字型 size 為 1080p 下的像素值。
• 圖片 使用 duration（預設 3），並可設定 motion：in、out、left、right、up、down。
• 表情符號 不會在文字中繪製。請將其放入 PNG 並使用 overlays。

字幕

提供帶有單詞時間軸的逐字稿，WeCut 即可建立字幕：

• words：一個 .json、.srt 或 .vtt 路徑，或內嵌陣列 [{"word": "hi", "start": 0.1, "end": 0.4}]。OpenAI/Groq verbose_json 和 whisper.cpp JSON 可直接讀取。
• src：設定為逐字稿所屬的影片。這樣逐字稿保留來源檔案自身的時間，而 WeCut 會將每個單詞移動至輸出時間軸上（透過每個從該檔案裁剪的片段，包含速度調整）。若無 src，時間必須已為輸出時間。
• style：classic、yellow、box-black、box-white、bold、comic、shadow（一次顯示一個短語）、karaoke、karaoke-green（唸到的詞高亮）、pop（一次一個大字）。

若需要逐字稿：wecut doctor 會報告 local_transcription: true（當此 FFmpeg 包含 Whisper 濾鏡時）。否則請使用您已有的語音轉文字工具，並將其單詞時間軸儲存為 JSON。

模板：複製有效的方法

食譜（recipe） 是一個編輯的形狀，不包含內容：包含章節（例如一個 5 秒鉤子搭配標題卡片，然後是演講）、文字插槽、字幕與音樂風格、效果。將其套用至新片段、逐字稿和音樂即可產生一個專案。

1. 分析一個曾爆紅的影片： wecut analyze media/viral.mp4 回傳鏡頭與節奏、前 3 秒的剪輯點、閃爍、節奏、停頓、一個無聲的平台結尾（可忽略），以及 sheet：每個鏡頭一幀的單張圖片。查看圖片以了解標題卡片、文字風格、構圖和字幕風格。
2. 選擇或撰寫一個食譜： wecut recipe list（內建：news-headline、news-headline-blur、quote-hook、vlog-phrases、podcast-punch、photo-slideshow，加上工作目錄中的 recipes/*.json）。wecut recipe show <name> 列出其角色與文字插槽。若要撰寫，請遵循 wecut recipe schema。
3. 套用食譜：

{
  "recipe": "news-headline",
  "clips": [
    { "src": "media/broll.mp4", "role": "hook" },
    { "src": "media/talk.mp4", "from": 120, "to": 165 }
  ],
  "texts": { "label": { "text": "頁面名稱" }, "headline": { "text": "一句話的主張", "emphasis": ["claim"] } },
  "transcript": "media/talk.words.json",
  "write": "projects/clip-01.json"
}

wecut recipe apply --input request.json（或 --input - 從標準輸入讀取 JSON）檢查所有項目並儲存專案；接著 preview 和 render。未指定角色的片段會填入 body；若某章節沒有片段，則借用下一個鏡頭的開頭片段。

4. 儲存自己的食譜： wecut recipe from-project projects/clip-01.json --name my-style --write recipes/my-style.json 保留章節、轉場、文字插槽、字幕風格、效果以及預設音樂軌道。

音樂：一個食譜可攜帶自己的曲目（music.src），預設使用，如同 CapCut 模板中的歌曲。傳入 "music": "media/song.mp3"（或一個影片，使用其音軌）來取代，或傳入 "none"。從他人影片中取得的歌曲在上傳後可能會被平台靜音；在應用程式中於發布時加入熱門音效可以避免此情況。

複製結構，而非內容：他人的片段、確切措辭和音樂仍屬他人所有。

從一個長影片製作多個片段

1. wecut probe 來源檔案並取得含單詞時間軸的逐字稿。
2. 閱讀逐字稿並挑選時刻（由您決定；WeCut 不判斷內容）。
3. 為每個片段撰寫一個專案，每個專案中 captions.src 指向同一個來源，讓一份逐字稿服務所有片段。
4. wecut preview 其中一個，調整 focus，然後 wecut render 每個片段。

疑難排解

• E_RANGE：to 超過檔案結尾。使用 wecut probe 取得實際時長。
• E_PATH：路徑在工作目錄之外或為 URL。
• E_MEDIA：檔案非可讀取的影片、圖片或音訊檔案，或類型不符合該欄位要求（音樂放在 clips、影片放在 overlays）。
• E_DEPENDENCY：缺少 FFmpeg，版本低於 6，或編譯時未包含 libass。執行 wecut doctor。
• 渲染太慢：使用 --preset draft、較低的 output.res，或減少每個專案的片段數量。結果中的 render_seconds 和 realtime_factor 顯示本機速度。
• 查看 FFmpeg 實際執行的指令：wecut render project.json --dry-run。