cli-anything-shotcut

cli-anything-shotcut 是做什麼的？

一個有狀態的命令列視訊編輯工具，基於 MLT XML 格式。專為 AI 代理與進階使用者設計，無需圖形介面即可建立和編輯 Shotcut 專案。

安裝

此 CLI 作為 cli-anything-shotcut 套件的一部分安裝：

pip install cli-anything-shotcut

必要條件：

• Python 3.10+
• melt（MLT CLI）— 用於渲染和播放
• ffmpeg / ffprobe — 用於媒體探測
• 系統上必須安裝 shotcut

使用方法

基本指令

# 顯示說明
cli-anything-shotcut --help

# 啟動互動式 REPL 模式
cli-anything-shotcut

# 建立新專案
cli-anything-shotcut project new -o project.json

# 以 JSON 輸出執行（供代理使用）
cli-anything-shotcut --json project info -p project.json

REPL 模式

當不帶子指令呼叫時，CLI 會進入互動式 REPL 會話，並支援復原/重做：

cli-anything-shotcut
# 或搭配專案：
cli-anything-shotcut --project my_project.mlt

REPL 指令

工作流程： 始終先使用 media import 取得 clip_id，然後使用 add-clip 將其放置到時間軸上。

專案與會話：

• new [profile] — 建立新專案（預設：hd1080p30）
• open <path> — 開啟 .mlt 檔案
• save [path] — 儲存專案
• info — 顯示專案資訊
• xml — 列印原始 MLT XML
• status — 顯示會話狀態
• undo / redo — 瀏覽操作歷史

媒體（兩步驟模型）：

• media import <file> [--caption name] — 將檔案匯入專案素材箱，傳回 clip_id（例如 clip0）
• media — 列出所有已匯入的媒體
• probe <file> — 分析媒體檔案

時間軸：

• add-track <video|audio> [name] — 新增音軌
• tracks — 列出所有音軌
• show — 視覺化時間軸概覽
• add-clip <clip_id> <track> [in] [out] [--at time] — 將已匯入的剪輯放置到音軌上
• clips <track> — 列出音軌上的剪輯
• remove-clip <track> <clip> — 移除剪輯
• trim <track> <clip> [--in tc] [--out tc] — 修剪剪輯
• split <track> <clip> <at> — 在指定時間碼分割剪輯

濾鏡：

• list-filters [video|audio] — 瀏覽可用的濾鏡
• filter-info <name> — 顯示濾鏡詳細資料
• add-filter <name> [--track n] [--clip n] [key=val ...] — 將濾鏡新增至剪輯、音軌或全域
• filters [--track n] [--clip n] — 列出啟用的濾鏡
• remove-filter <idx> [--track n] [--clip n] — 依索引移除濾鏡
• set-filter <idx> <param> <value> [--track n] [--clip n] — 設定濾鏡參數
• volume-envelope [--track n] [--clip n] TIME=LEVEL ... — 關鍵幀音量（例如 00:00:00.000=1.0 00:00:03.000=0.35）
• duck [--track n] [--clip n] START..END ... — 閃避音量封套（例如 00:00:06.000..00:00:09.000）

匯出：

• presets — 列出匯出預設
• render <output> [--preset name] — 渲染成視訊檔案

指令群組

專案

專案管理：新建、開啟、儲存、資訊。

指令	說明
new	建立新的空白專案
open	開啟現有的 .mlt 專案檔案
save	儲存目前專案
info	顯示詳細專案資訊
profiles	列出可用的視訊設定檔
xml	列印目前專案的原始 MLT XML

時間軸

時間軸操作：音軌、剪輯、修剪。

指令	說明
show	顯示時間軸概覽
tracks	列出所有音軌
add-track	在時間軸上新增音軌
remove-track	依索引移除音軌
add-clip	透過 clip_id 將已匯入的剪輯新增至音軌；支援 --at 進行絕對放置
remove-clip	從音軌移除剪輯
move-clip	在音軌或位置之間移動剪輯
trim	修剪剪輯的入/出點
split	在指定的時間碼將剪輯分割為兩個
clips	列出音軌上的所有剪輯
add-blank	在音軌上新增空白間隔
set-name	設定音軌的顯示名稱
mute	靜音或取消靜音音軌
hide	隱藏或取消隱藏視訊音軌

濾鏡群組

濾鏡操作：新增、移除、設定效果。

指令	說明
list-available	列出所有可用的濾鏡
info	顯示濾鏡及其參數的詳細資訊
add	將濾鏡新增至剪輯、音軌或全域
remove	依索引移除濾鏡
set	設定濾鏡的參數
list	列出目標上的啟用濾鏡
volume-envelope	在音軌或剪輯上建立或取代關鍵幀音量封套
duck	在一個或多個時間視窗上建立實用的閃避音量封套

媒體

媒體操作：探測、列出、檢查檔案。

指令	說明
import	將媒體檔案匯入專案素材箱
probe	分析媒體檔案的屬性
list	列出目前專案中的所有媒體剪輯
check	檢查所有媒體檔案是否存在
thumbnail	從視訊檔案產生縮圖

匯出

匯出/渲染操作。

指令	說明
presets	列出可用的匯出預設
preset-info	顯示匯出預設的詳細資料
render	將專案渲染成視訊檔案

轉場群組

轉場操作：溶解、劃像及其他轉場。

指令	說明
list-available	列出所有可用的轉場類型
info	顯示轉場類型的詳細資訊
add	在兩個音軌之間新增轉場
remove	依索引移除轉場
set	設定轉場的參數
list	列出時間軸上的所有轉場

合成群組

合成：混合模式、子母畫面、不透明度。

指令	說明
blend-modes	列出所有可用的混合模式
set-blend	設定音軌的混合模式
get-blend	取得音軌目前的混合模式
set-opacity	設定音軌的不透明度 (0.0-1.0)
pip	設定剪輯的子母畫面位置

會話

會話管理：狀態、復原、重做。

指令	說明
status	顯示目前會話狀態
undo	復原上一個操作
redo	重做上一個復原的操作
save	將會話狀態儲存至磁碟
list	列出所有已儲存的會話

預覽

預覽組合包與即時預覽會話，用於迭代式編輯審查。

指令	說明
preview recipes	列出預覽配方
preview capture	渲染低解析度預覽組合包
preview latest	傳回最新的現有組合包
preview live start	開始即時預覽會話並發佈第一個組合包
preview live push	在即時會話中發佈新的組合包
preview live status	查詢目前的即時會話狀態而不渲染
preview live stop	停止即時會話而不刪除成品

典型的 quick 組合包內容：

• preview.mp4
• 數個取樣幀
• 中點 hero.png
• 包含專案事實的 summary.json

支援輪詢模式：

cli-anything-shotcut --json --project edit.mlt preview live start --recipe quick --mode poll --source-poll-ms 500

preview live status --json 包含會話參考以及精簡的 trajectory_summary，讓代理能夠低成本了解最近的幾次發佈。

檢視器指令：

cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session

範例

建立新專案

建立一個新的 shotcut 專案檔案。

cli-anything-shotcut project new -o myproject.json
# 或搭配 JSON 輸出以供程式化使用
cli-anything-shotcut --json project new -o myproject.json

互動式 REPL 會話

啟動一個支援復原/重做的互動式會話。

cli-anything-shotcut
# 以互動方式輸入指令
# 使用 'help' 檢視可用的指令
# 使用 'undo' 和 'redo' 瀏覽歷史紀錄

匯出專案

將專案匯出為最終輸出格式。

cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite

確定性時間軸重建

對於重建，建議優先使用絕對放置而非僅追加剪輯插入：

cli-anything-shotcut --project myproject.mlt media import intro.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip0 \
  --track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000

cli-anything-shotcut --project myproject.mlt media import broll.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip1 \
  --track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000

• --at 會自動在目標時間位於空白區域時插入空白。
• CLI 會拒絕與現有剪輯重疊。
• 建議使用明確的 --in 和 --out 值，以便後續的絕對放置保持一致。

音訊自動化

cli-anything-shotcut --project myproject.mlt filter volume-envelope \
  --track 2 \
  --point 00:00:00.000=1.0 \
  --point 00:00:03.000=0.35 \
  --point 00:00:05.000=1.0

cli-anything-shotcut --project myproject.mlt filter duck \
  --track 2 \
  --window 00:00:06.000..00:00:09.000 \
  --window 00:00:15.000..00:00:18.000 \
  --normal 1.0 --duck 0.25

CLI 透過以下方式維護會話狀態：

• 復原/重做：最多 50 層歷史紀錄
• 專案持久化：將專案狀態儲存/載入為 JSON
• 會話追蹤：追蹤修改和變更

輸出格式

所有指令都支援雙重輸出模式：

• 人類可讀（預設）：表格、顏色、格式化文字
• 機器可讀（--json 旗標）：供代理使用的結構化 JSON

# 人類輸出
cli-anything-shotcut project info -p project.json

# 供代理使用的 JSON 輸出
cli-anything-shotcut --json project info -p project.json

給 AI 代理的提示

當以程式化方式使用此 CLI 時：

1. 始終使用 --json 旗標 以獲得可解析的輸出
2. 檢查回傳碼 — 0 表示成功，非零表示錯誤
3. 解析 stderr 以取得失敗時的錯誤訊息
4. 在所有檔案操作中使用絕對路徑
5. 在匯出操作後驗證輸出是否存在
6. 在重新建立已知剪輯時，優先使用 timeline add-clip --at
7. 在關鍵幀音量或閃避音量變更後，檢查最終渲染結果
8. 使用 preview capture 或 preview live ... 以視覺化方式驗證節奏、剪輯點和濾鏡效果
9. 讀取回傳的成品路徑，例如 hero.png 和 preview.mp4；JSON 承載會參照磁碟上的檔案
10. 在讀取完整的 trajectory.json 之前，先使用 preview live status --json
11. 僅使用 cli-hub previews ... 來檢查/開啟現有的組合包或即時會話

更多資訊

• 完整文件：請參閱套件中的 README.md
• 測試覆蓋率：請參閱套件中的 TEST.md
• 方法論：請參閱 cli-anything-plugin 中的 HARNESS.md

版本

1.0.0