命令列介面

將 OpenShot 帶入您的命令列工作流程。匯入素材、剪輯並排列片段、套用效果、使用關鍵影格動畫屬性，並從終端機匯出影片。使用幾個指令自動化重複編輯，為重複專案撰寫腳本，或讓 AI 代理協助組裝和精煉影片。

命令列與編輯器使用相同的專案。您可以控制已開啟的編輯器並隨時檢視變更，或在無頭模式（headless session）下工作而不開啟視窗。工作階段會在指令間保持專案開啟，包括編輯、復原歷史和匯出工作。隨時將其儲存為 .osp 專案，以便稍後繼續編輯。

開始使用

使用您已安裝的 OpenShot 執行檔，後接 --cli。以 intro 開始，獲得關於工作階段、編輯、動畫和儲存的簡短指南，或使用 help 查看指令總覽。這些指令不需要啟動工作階段。以下範例需要包含命令列編輯功能的 OpenShot 版本。

Linux AppImage

從包含您下載的 AppImage 的目錄開始:

./OpenShot.AppImage --cli intro
./OpenShot.AppImage --cli help

將 OpenShot.AppImage 替換為您下載的檔名。如果 AppImageLauncher 顯示桌面整合對話框，請在執行指令前設定 APPIMAGELAUNCHER_DISABLE=1:

APPIMAGELAUNCHER_DISABLE=1 ./OpenShot.AppImage --cli intro

對於腳本或重複指令，請在目前的 shell 中設定一次:

export APPIMAGELAUNCHER_DISABLE=1
./OpenShot.AppImage --cli session start

此變數必須在啟動 AppImage 前設定：AppImageLauncher 可能會在 OpenShot 接收 --cli 前攔截它。相對媒體路徑和 @batch.json 檔案會從您的工作目錄解析。當工作階段或匯出執行時，請保持 AppImage 檔案可用。

Linux Snap

對於 OpenShot Snap，請使用:

snap run openshot-qt --cli intro
snap run openshot-qt --cli help
snap run openshot-qt --cli session start

Snap 的檔案權限同樣適用於命令列編輯。請將媒體、專案和匯出放在 Snap 可存取的位置，例如您的家目錄。若要允許存取外接硬碟，請連接 removable-media 權限:

sudo snap connect openshot-qt:removable-media

Windows

重要

在 Windows 上請使用 openshot-qt-cmd.exe 進行命令列編輯。 此控制台執行檔會在終端機顯示指令結果、說明和錯誤。桌面執行檔 openshot-qt.exe 不會在互動式終端機顯示標準輸出，導致指令無法看到回饋，使 CLI 難以使用。

在 PowerShell 中，從 OpenShot 安裝目錄:

& .\openshot-qt-cmd.exe --cli intro
& .\openshot-qt-cmd.exe --cli help
& .\openshot-qt-cmd.exe --cli session start

如果您在不同目錄，請使用 openshot-qt-cmd.exe 的完整路徑。執行檔名稱後保留 --cli。

macOS

若安裝於 Applications 目錄:

"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli intro
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli help

尋找指令

在本指南中，openshot-cli 是您安裝指令的簡寫，例如 snap run openshot-qt --cli 或 ./OpenShot.AppImage --cli。部分安裝也直接提供 openshot-cli 指令。從原始碼執行時，請在 OpenShot 的 Python 環境中使用 python3 src/launch.py --cli。

單獨使用 --cli、--cli help 和 --cli --help 顯示相同的總覽。隨著您瀏覽指令，說明會變得更具體:

openshot-cli clip help
openshot-cli clip keyframe help
openshot-cli clip keyframe set help
openshot-cli edit help
openshot-cli text help
openshot-cli effects list
openshot-cli effects audiovisualization help
openshot-cli effects audiovisualization help --property background

群組說明以範例解釋工作流程；操作說明描述參數和行為。--help 等同於尾隨的 help。所有說明指令均可在無編輯工作階段下使用。

effects list 顯示可用效果及簡短描述。效果說明解釋其屬性、預設值、選項和範圍。effects instances 列出已附加於片段的效果及其父片段 ID。類別名稱、顯示名稱和底線別名皆識別相同效果。

與腳本及 AI 代理合作

像 Codex 和 Claude Code 這類 AI 程式代理可以使用 CLI 透過終端機指令檢視和編輯 OpenShot 專案。提供代理 OpenShot 執行檔路徑、要處理的媒體或專案，以及期望結果：長度、尺寸、動畫風格和輸出位置。請它在開始前閱讀 --cli intro。相同指令無論您親自輸入或從腳本執行皆適用。

從 intro 開始，然後根據需要使用特定指令說明。一個實用的工作流程是選擇工作階段、檢視專案、進行少量修改、檢查結果並儲存。指令會回傳結構化 JSON，讓腳本和代理能直接使用物件 ID 和結果，而非解析螢幕輸出。

編輯前先檢視。 使用回傳的 ID 和屬性資訊，而非猜測名稱、軌道編號或時間。當開啟多個專案時，請明確選擇工作階段。
群組重複編輯。 使用 edit apply 進行一連串變更，或使用 edit bulk 對選取片段套用範本。套用批次前，請用 --dry-run 驗證。
檢查動畫。 選擇座標空間，從幾個關鍵影格開始，並使用緩動預設來達成熟悉的動作。keyframe preview 會取樣曲線，讓您在匯出前能發現暫停或跳躍。也請檢視渲染後的動作；僅靠聯絡表無法呈現動畫的感覺。
儲存並追蹤匯出。 請明確儲存專案，並在視輸出為完成前檢查匯出工作的狀態。若請求逾時，請先檢查其狀態再重複編輯。

以下章節說明這些工作流程及其時間慣例。

工作階段與輸出

啟動或尋找工作階段

啟動一個無頭工作階段（無編輯器視窗）:

openshot-cli session start

要在啟動時開啟現有專案，請加入 --project "/path/project.osp"。成功的 JSON 回應包含 result.session_id。請複製該值。若 OpenShot 已在執行，或您忘記 ID，請使用以下指令尋找可用工作階段:

openshot-cli session list

選擇您打算編輯的專案所屬工作階段。每個指令不必都啟動新工作階段。

選擇工作階段

小技巧

設定 OPENSHOT_SESSION 一次，之後正常執行指令。 您的終端機會記住所選工作階段，因此不必每次指令都帶 --session。請參考以下 PowerShell 或 Bash 範例。

將下方的 SESSION_ID 替換為 session start 或 session list 回傳的 session_id。

Windows PowerShell:

$env:OPENSHOT_SESSION = "SESSION_ID"
& .\openshot-qt-cmd.exe --cli timeline view
& .\openshot-qt-cmd.exe --cli export start "C:\path\test.mp4" --wait

Linux Bash:

export OPENSHOT_SESSION="SESSION_ID"
./OpenShot.AppImage --cli timeline view
./OpenShot.AppImage --cli export start "/path/test.mp4" --wait

在 macOS 上，使用相同的 export 語法。對於 macOS 或 Snap 指令，請替換為您安裝的執行檔（參考入門說明）。此選擇會持續於此終端機及其啟動的指令。於新終端機重新設定，或切換工作階段時更新。

以下編輯與匯出範例假設已設定 OPENSHOT_SESSION。 下一小節示範如何自動擷取 ID 以供腳本使用。

若只想針對單一指令指定不同工作階段，請使用 --session。此參數會覆蓋 OPENSHOT_SESSION，但不會改變終端機的選擇:

openshot-cli --session OTHER_SESSION_ID project get

使用封裝執行檔時，將此覆蓋參數置於 --cli 之後、指令群組之前：--cli --session OTHER_SESSION_ID project get。

自動選擇僅在存在且可連線的工作階段唯一時有效。若看到 session_required，請執行 session list 並明確選擇目標工作階段。若不再列出，請重新啟動並使用新 ID。說明、intro 與工作階段發現不需選擇工作階段。

自動擷取工作階段 ID

腳本可直接從 session start 回傳的 JSON 中讀取 result.session_id，並設定 OPENSHOT_SESSION 以供後續指令使用。無需手動複製 ID 或讀取日誌檔。使用回傳 ID 前請確認啟動成功。

Windows PowerShell（設定您安裝的執行檔路徑）:

$openshot = "C:\Program Files\OpenShot Video Editor\openshot-qt-cmd.exe"
$reply = & $openshot --cli session start
if ($LASTEXITCODE -ne 0) { throw "OpenShot session startup failed" }
$session = $reply | ConvertFrom-Json
if (-not $session.ok -or -not $session.result.session_id) {
    throw "OpenShot did not return a session ID"
}
$env:OPENSHOT_SESSION = $session.result.session_id
& $openshot --cli timeline view

Linux Bash（需安裝 jq 以讀取 JSON）:

openshot="/full/path/to/OpenShot.AppImage"
export APPIMAGELAUNCHER_DISABLE=1
if reply=$("$openshot" --cli session start) &&
   session_id=$(printf '%s' "$reply" | jq -er 'select(.ok == true) | .result.session_id | strings | select(length > 0)'); then
    export OPENSHOT_SESSION="$session_id"
    "$openshot" --cli timeline view
else
    echo "OpenShot session startup failed" >&2
fi

此環境變數會為從此終端機啟動的指令選擇工作階段；不會更改系統範圍設定。啟動工作階段不會自動設定此變數。停止工作階段後，請在 PowerShell 使用 Remove-Item Env:OPENSHOT_SESSION 或在 Bash 使用 unset OPENSHOT_SESSION 清除選擇。

顯示與停止工作階段

在編輯器中顯示所選工作階段:

openshot-cli session show

在桌面環境中，session show 會在同一程序中建立編輯器，並保留即時專案、ID、歷史紀錄、匯出工作與連線。重複呼叫會喚起現有視窗。session start --show 會立即開啟。未帶顯示或使用 QT_QPA_PLATFORM=offscreen/minimal 啟動的工作階段，無法後續顯示桌面視窗。此類工作階段請儲存並在新的桌面工作階段中開啟專案。顯示後，請透過編輯器視窗關閉工作階段。

全域選項（--session、--timeout）置於指令之前。session serve 會在前景執行以供監控；session start 在背景主機註冊後返回。session stop 拒絕有未儲存變更或進行中匯出的請求。僅在確定要捨棄未儲存編輯時使用 --discard。

指令輸出

結果以 JSON 格式輸出至標準輸出，預設文字時間軸檢視除外。錯誤以 JSON 格式輸出至標準錯誤，退出狀態為 1；參數解析錯誤退出狀態為 2。變更操作會以 inspect 指令回傳簡潔摘要。get 回傳原生物件 JSON。專案回應包含修訂版本；效果目錄回應不需工作階段。無頭工作階段的日誌存放於其註冊紀錄旁。OPENSHOT_SESSION_DIR 可覆蓋預設的 ~/.openshot_qt/sessions 目錄。

工作階段在您的電腦本地接受指令。請保持工作階段登錄資訊的私密性，因為它包含用於存取您的編輯工作階段的憑證。匯出是基於快照進行，因此您可以在工作進行時繼續編輯。

開啟與儲存專案

OpenShot 專案（.osp）儲存您的可編輯時間軸。匯出會產生完成的影片；儲存專案則讓您日後能回到剪輯、特效和關鍵影格。即使您同時匯出影片，也請分別儲存專案。

開啟專案

使用現有專案啟動工作階段:

openshot-cli session start --project "/home/me/Videos/My Project.osp"

加入 --show 以同時開啟其編輯器視窗。若要使用已在執行的編輯器，請用 session list 找出它。將 OPENSHOT_SESSION 設為回傳的工作階段 ID，然後開啟或檢視專案:

openshot-cli project open "/home/me/Videos/My Project.osp"
openshot-cli project get

將範例路徑替換為您自己的路徑，並對包含空格的路徑加上引號。project open 會取代所選工作階段的當前專案。除非您明確加入 --discard，否則不會捨棄未儲存的編輯；若想保留，請先儲存這些編輯。透過 CLI 開啟不會顯示互動式缺少媒體對話框，因此請保持專案的原始媒體可用。

若要建立新的空白專案，請使用不帶 --project 的 session start，然後依照「編輯」部分說明匯入媒體並新增剪輯。

儲存專案或其副本

儲存為新檔案，或在進行更多更改前建立獨立版本:

openshot-cli project save "/home/me/Videos/My Project v2.osp"

若要更新現有檔案，請明確允許覆寫:

openshot-cli project save "/home/me/Videos/My Project v2.osp" --overwrite

請務必提供目標路徑。儲存 .osp 不會將所有原始素材封裝進該檔案；移動或重新開啟專案時，請保持參考的媒體可用。

匯出影片

可從腳本或 AI 代理自動化渲染與匯出，使用專案設定或為每次渲染選擇不同的輸出設定檔。匯出工作可在背景執行，或等待完成後再繼續腳本。以下示範使用專案解析度與幀率渲染 MP4:

openshot-cli export start "/home/me/Videos/video.mp4" --wait

預設情況下，OpenShot 使用 H.264 視訊與 AAC 音訊。請將範例路徑替換為您的目的地，使用現有資料夾與新檔名。現有輸出檔案不會被覆寫。匯出不會儲存您的可編輯 .osp 專案；請另行使用 project save 以保存您的編輯工作。

--wait 選項會讓指令持續執行直到匯出完成或失敗。請在分享前檢視完成的影片。

檢查匯出進度

不加 --wait 可在背景啟動匯出。回應會包含工作 ID，您可用來檢查進度:

openshot-cli export start "/home/me/Videos/video.mp4"
openshot-cli export status JOB_ID
openshot-cli export status JOB_ID --wait
openshot-cli export list

將 JOB_ID 替換為回傳的 ID。若等待逾時，匯出仍會繼續執行；請檢查相同工作，而非啟動另一個匯出。若要停止工作，請使用 export cancel JOB_ID。每個工作啟動時會擷取時間軸，因此後續編輯不會影響已進行中的匯出。

等待預設為 600 秒；可用 --wait-timeout 調整。此設定與全域每次請求的 --timeout 分開。匯出失敗、取消及等待逾時會以狀態碼 1 結束，並包含工作詳細資訊。

以多個設定檔匯出

透過為每個輸出選擇匯出設定檔，可在不同解析度或長寬比下匯出相同時間軸。匯出設定檔僅適用於該工作；不會更改編輯專案的設定檔。設定檔定義尺寸、幀率與長寬比；匯出預設則選擇編碼設定，如 MP4/H.264。

尋找可用的設定檔並檢視其設定:

openshot-cli profile list --search 720
openshot-cli profile list --search 1080
openshot-cli profile get builtin:01280x0720p0030_16-09

例如，匯出 720p 和 1080p 的橫向版本，然後匯出 1080x1080 的方形版本。這些設定檔皆使用 30 fps:

openshot-cli export start "/home/me/Videos/video-720p.mp4" --profile builtin:01280x0720p0030_16-09 --wait
openshot-cli export start "/home/me/Videos/video-1080p.mp4" --profile builtin:01920x1080p0030_16-09 --wait
openshot-cli export start "/home/me/Videos/video-square.mp4" --profile builtin:01080x1080p0030_01-01 --wait

為每個版本使用不同的輸出檔名。若想要匹配的版本，請保持工作間的編輯不變。改變長寬比可能會影響構圖：請檢視每個輸出，特別是標題和動畫主體。若要另行製作方形或直向版本，請先儲存專案副本，變更其專案設定檔，並調整剪輯後再匯出。請參閱下方的設定檔與匯出設定，了解自訂設定檔與編碼選項。

批次匯出多個專案

重複使用一個無頭工作階段，依序渲染多個已儲存的專案。開啟專案，使用 --wait 匯出，然後開啟下一個專案。以下範例使用各專案自己的解析度與幀率，並在 .osp 檔旁建立 MP4 檔案。於匯出指令中加入 --profile PROFILE_ID，即可為每個專案使用相同的輸出設定檔。

請先在相同終端機中成功執行上述匹配的自動 session-ID 範例。它會定義 openshot 並選擇新的會話。請將下方的專案路徑替換為您自己的路徑。使用尚不存在的不同輸出名稱；範例會在開始批次前檢查所有目的地。

Windows PowerShell:

$projects = @(
    "C:\VideoProjects\First.osp",
    "C:\VideoProjects\Second.osp"
)
foreach ($project in $projects) {
    if (-not (Test-Path -LiteralPath $project -PathType Leaf)) {
        throw "Project not found: $project"
    }
    $output = [System.IO.Path]::ChangeExtension($project, ".mp4")
    if (Test-Path -LiteralPath $output) { throw "Output already exists: $output" }
}
foreach ($project in $projects) {
    $output = [System.IO.Path]::ChangeExtension($project, ".mp4")
    & $openshot --cli project open $project
    if ($LASTEXITCODE -ne 0) { throw "Could not open: $project" }
    & $openshot --cli export start $output --wait --wait-timeout 86400
    if ($LASTEXITCODE -ne 0) { throw "Export needs attention: $output" }
}
& $openshot --cli session stop
if ($LASTEXITCODE -ne 0) { throw "Could not stop the session" }
Remove-Item Env:OPENSHOT_SESSION

Linux Bash（括號使錯誤處理限制在批次內）:

(
    set -e
    : "${OPENSHOT_SESSION:?Run the session startup example first}"
    projects=(
        "/home/me/VideoProjects/First.osp"
        "/home/me/VideoProjects/Second.osp"
    )
    for project in "${projects[@]}"; do
        test -f "$project" || { echo "Project not found: $project" >&2; exit 1; }
        output="${project%.osp}.mp4"
        test ! -e "$output" || { echo "Output already exists: $output" >&2; exit 1; }
    done
    for project in "${projects[@]}"; do
        "$openshot" --cli project open "$project"
        "$openshot" --cli export start "${project%.osp}.mp4" --wait --wait-timeout 86400
    done
    "$openshot" --cli session stop
) && unset OPENSHOT_SESSION

兩種方法在命令失敗時會停止批次並保留會話以供檢查。此處的等待限制為每次匯出 24 小時。等待逾時會讓渲染繼續執行：請在重試前使用 export list 和 export status JOB_ID --wait。完成的影片會保留在磁碟中；恢復前請從批次中移除已完成的專案。解決失敗後，請停止會話並在完成時清除其環境變數。

選擇預設值與編碼設定

探索已安裝的匯出預設與支援的設定:

openshot-cli export preset list
openshot-cli export preset get builtin:format_mp4_x264
openshot-cli export capabilities
openshot-cli export start /tmp/reel.mp4 --preset builtin:format_mp4_x264 --quality med --wait

匯出也接受 --from-file FILE_ID 及可選的 --create-custom。設定依序解析：專案預設、預設值、高級 JSON、明確的配置檔/品質/範圍標誌。高級 JSON 可設定視訊/音訊編碼器與位元率、音訊配置/取樣率/聲道、本地編碼器選項、硬體裝置設定及執行緒數量。

例如，透過高級 JSON 選擇編碼器選項:

openshot-cli export start /tmp/small.mp4 --profile builtin:00640x0360p0030_16-09 --json '{"video_options":{"preset":"fast"}}' --wait

驗證匯出設定

在開始渲染前檢查設定:

openshot-cli export validate /tmp/reel.mp4 --preset builtin:format_mp4_x264

功能報告編譯後的編碼器可用性，而非實體 GPU 可用性。驗證更進一步：它會在獨立程序中以精確設定開啟編碼器（包含硬體編碼器）與容器，且不寫入檔案。容器無法容納的組合會以 incompatible_export 失敗，並附帶 FFmpeg 的說明及需更改的設定（details.cause.path）:

openshot-cli export validate /tmp/song.mp3 --json '{"mode":"audio","format":"mp3","audio_codec":"aac"}'

匯出工作者在渲染前會執行相同的檢查。

渲染影格範圍

使用 --start-frame 和 --end-frame 來渲染時間軸的一部分。範圍包含端點且以 匯出配置檔的 FPS 為基準，從 1 開始。例如，以 30 fps 渲染前 90 幀（三秒）:

openshot-cli export start /tmp/excerpt.mp4 --profile builtin:01280x0720p0030_16-09 --start-frame 1 --end-frame 90 --wait

僅音訊匯出與影像序列

使用高級 JSON 選擇輸出模式:

openshot-cli export start /tmp/music.wav --json '{"mode":"audio","format":"wav","audio_codec":"pcm_s16le"}' --wait
openshot-cli export start /tmp/frames --json '{"mode":"image_sequence","format":"png"}' --end-frame 3 --wait

影像序列需要新的輸出目錄。現有輸出絕不會被覆寫。

編輯

新增剪輯與效果

使用 import/add/list 回傳的 ID，並透過 project get 查詢圖層編號:

openshot-cli file import /absolute/path/video.mp4
openshot-cli clip add FILE_ID --layer 2000000 --position 3 --start 10 --end 17 --volume 0
openshot-cli clip set CLIP_ID --json '{"volume":0.5}'
openshot-cli clip keyframe set CLIP_ID --property volume --frame 301 --value 0
openshot-cli clip keyframe set CLIP_ID --property volume --frame 331 --value 1
openshot-cli effects add CLIP_ID saturation
openshot-cli effects set EFFECT_ID --json '{"saturation":1.2}'
openshot-cli project save /absolute/path/edit.osp

盡早選擇專案配置檔；已填充的專案也支援透過現有的 FPS 轉換與復原系統變更配置檔。剪輯建立時使用 --audio-only 會抑制影片，包括音樂檔案中嵌入的封面。若要將該剪輯用於音訊視覺化，請啟用其影片與音訊，並依效果說明設定透明疊加與圖層位置。

理解剪輯時間

範例關鍵影格假設 30fps 專案及在來源 10 秒處修剪的剪輯。位置以時間軸秒為單位；開始/結束為來源秒，結束為不包含。影格從 1 開始。檔案縮圖影格使用來源 FPS。時間軸影格使用專案 FPS。剪輯關鍵影格使用專案 FPS 的來源座標，因此修剪剪輯不會將其第一個可見關鍵影格移至影格 1。

變更屬性

set 會合併頂層屬性。純量會將有關鍵影格的屬性轉為常數。提供的巢狀曲線會取代該曲線；若只變更一點，請使用 keyframe set。JSON 參數接受內嵌 JSON、@file.json 或標準輸入 -。在編輯專案前會驗證屬性名稱、類型、列舉、關鍵影格、參考與時間。錯誤會指出欄位、預期值、收到值及可能的修正。當引擎支援超出範圍值時，GUI 滑桿範圍僅供參考。

新增淡入淡出

clip fade ID --in 0.5 --out 0.5 會自動計算來源修剪的關鍵影格座標。它會取代 alpha 曲線；改用 --property volume --value 0.25 則會建立峰值為 0.25 的音訊淡出。持續時間必須介於第一與最後可見影格間；淡出在最後一幀達到零。

分割剪輯

clip split ID --at 6.5 使用時間軸秒，會貼齊至最近的專案影格，並保留兩半。它保留來源座標曲線並在右半部複製效果並賦予新 ID，符合編輯器的切割行為。左半部保留其 ID。回應會報告請求/實際分割時間及兩者摘要；命名批次結果支援 {"$ref":"cut.right.id"}。分割會拒絕端點與鎖定軌道。復原會在一次交易中還原原始剪輯。

剪輯選單預設

編輯器的剪輯選單預設使用與命令列相同的程式碼。每個命令在其說明中列出其預設，且每個預設都是單一的復原步驟：

openshot-cli clip motion CLIP_ID --preset slide-in-left
openshot-cli clip motion CLIP_ID --preset pulse --at 4.5
openshot-cli clip look CLIP_ID --effect ColorGrade --preset warm_up
openshot-cli clip look CLIP_ID --effect all --preset none
openshot-cli clip speed CLIP_ID --mode forward --factor 2
openshot-cli clip speed CLIP_ID --mode freeze --at 3 --duration 2
openshot-cli clip repeat CLIP_ID --passes 3 --pattern pingpong
openshot-cli clip waveform CLIP_ID

動作預設是相對於剪輯當前的變換。外觀預設會新增或替換一個效果，而 none 則會移除它。速度和重複會重新定時每個關鍵影格並改變剪輯長度；clip speed --mode reset 可恢復正常速度。其他選單操作是純粹的編輯：使用 clip set 旋轉和佈局，使用 effects add Crop 裁剪。這些命令也適用於 edit apply 和 edit bulk。

新增與樣式設定文字

text add 建立文字並將其放置為剪輯，使用與編輯器文字工具相同的文字。您未指定的選項將使用編輯器的預設樣式：

openshot-cli text add --text "Opening Night" --layer 5000000 --position 2 --duration 4 \
    --place lower-third --font "Noto Sans" --size 72 --bold --color "#ffffff" \
    --background "#80000000" --background-padding 16 --background-corner 12
openshot-cli text get CLIP_ID
openshot-cli text set CLIP_ID --stroke black --stroke-width 3
openshot-cli text set CLIP_ID --text $'Two\nlines' --line-spacing 1.4
openshot-cli text fonts --search noto
openshot-cli text list --search opening

文字內容、字型、大小、對齊方式、框寬和預設顏色屬於專案檔案中的文字，並由所有使用該文字的剪輯共用，就像在編輯器中一樣。對某個剪輯使用 text set 會更改所有剪輯並在 changed_clip_ids 中列出；--this-clip-only 則先給該剪輯自己的複本。clip add FILE_ID 會從 text list 放置另一個文字剪輯。大小以專案解析度的像素為單位，顏色可為 #RRGGBB、#AARRGGBB（含透明度）、CSS 名稱或 transparent。--place 將框置於中央、邊緣或角落，或下三分之一。--line-spacing 是行間距的倍數（1 為正常），--background-corner 會將背景和邊框角落圓角化指定像素數。

文字剪輯是普通剪輯。位置、縮放、旋轉、不透明度、時間、淡入淡出、動作預設和效果皆使用一般的 clip 命令。字型大小、內距、框寬以及字距和行距設定文字框大小，因此無法設定關鍵影格；若要動畫化文字大小，請設定剪輯的縮放關鍵影格。每個剪輯都可以使用與其他屬性相同的關鍵影格命令來動畫化其文字顏色、描邊和邊框寬度：

openshot-cli clip keyframe list CLIP_ID
openshot-cli clip keyframe set CLIP_ID --property text_color.alpha --space clip --unit seconds --at 0 --value 0
openshot-cli clip keyframe set CLIP_ID --property text_color.alpha --space clip --unit seconds --at 1 --value 255

可動畫化的屬性包括 text_color、text_background、text_stroke 和 text_border（顏色，含 .red、.green、.blue 和從 0 到 255 的 .alpha），以及 text_stroke_width、text_border_width 和 text_background_corner。剪輯自身的動畫會優先於共用樣式，text get 會列出剪輯動畫化的樣式。text reset CLIP_ID 會將剪輯恢復為預設樣式，如同 文字 → 重設樣式；--keyframes-only 僅移除剪輯自身的動畫。要一次設定多個文字的樣式，請使用 {"text":true} 選取它們：

openshot-cli edit bulk --select '{"text":true}' --json '[{"method":"text.set","params":{"font_family":"Noto Sans","stroke_width":2}}]'

套用一批編輯

edit apply --json @edits.json --expect-revision 12 接受最多 256 個有序的變更命令，使用點分命令名稱，如 clip.set 和 effects.add（舊寫法 effect.add 也可用）:

[
  {"method":"project.profile.set","params":{"id":"builtin:01280x0720p0024_16-09"}},
  {"method":"file.import","as":"media","params":{"path":"/tmp/video.mp4"}},
  {"method":"clip.add","as":"shot","params":{"file_id":{"$ref":"media.id"},"layer":1000000,"start":10,"end":15}},
  {"method":"clip.fade","params":{"id":{"$ref":"shot.id"},"fade_in":0.5,"fade_out":0.5}}
]

可選的 as 用於綁定結果，以供同一批次中的後續命令使用。{"$ref":"shot.id"} 物件會替換該結果的欄位。參照僅解析先前名稱；拼寫錯誤、前向參照和重複名稱會在即時更新前失敗。回應包含有序的簡潔結果和實際 ID 的 refs 映射。成功批次中的所有變更形成一個復原/重做步驟。project.profile.set 也支援已填充的時間軸。開啟、儲存、匯出和檢查命令不包含在編輯批次中。每個命令的說明列出其 JSON 參數名稱，包括 shell 標誌的底線拼寫（例如，--fps-num 變成 fps_num）。

驗證批次與錯誤處理

編輯批次中的所有命令會在任何即時更新前，先對一個分離的專案進行預檢。無效輸入不會改變即時專案和版本。有效批次形成一個復原群組。意外的執行時失敗仍可能產生部分變更；錯誤會報告已完成的操作。逾時不代表取消，因此在重試變更前請檢查狀態。

精確的關鍵影格編輯

clip、transition 和 effects 支援 keyframe list、set、remove、clear、transform、copy 和 paste。屬性路徑可指定巢狀曲線，例如色度鍵效果的 color.red。編輯巢狀曲線會保留同層頻道。執行 keyframe list ID 不帶屬性可發現曲線路徑和點數。發現和點列表包含裁剪/位置時間上下文；點列表還會報告原生影格座標。get 和 properties 顯示完整的原生物件和屬性元資料。錯誤會指出無效欄位、建議相近屬性名稱，並解釋座標修正。

請使用 --space native|clip|timeline 和 --unit frames|seconds 明確選擇座標。所有影格使用專案 FPS 且從 1 開始；秒數從零開始並會對齊至最近的影格。Native 是現有引擎的關鍵影格座標（包含來源裁剪）。剪輯座標從可見剪輯的入點開始；時間軸座標從專案時間零開始。附加效果使用其父剪輯的時間。這些座標指的是動畫時間，而非時間重映射曲線選擇的媒體影格。

對於一個定位於 5 秒、修剪於 2 秒、在 30 fps 專案中的剪輯，剪輯幀 1、時間軸幀 151 和原生幀 61 指向相同的點。位置和修剪獨立地對齊專案幀網格。列出整條曲線可能包含具有非正剪輯/時間軸座標的隱藏點。舊版 --frame 仍表示原生幀，且不能與 --at 結合使用。

範例:

openshot-cli clip keyframe set CLIP --property location_x --space clip --unit seconds --at 0 --value -1
openshot-cli clip keyframe set CLIP --property location_x --space clip --unit seconds --at 1 --value 0 --interpolation bezier --handles '{"handle_left":{"X":0.2,"Y":0.9}}'
openshot-cli effects keyframe set EFFECT --property color.red --space clip --at 31 --value 200
openshot-cli clip keyframe list CLIP --property location_x --space clip --unit seconds
openshot-cli clip keyframe transform CLIP --property location_x --space clip --start 1 --end 31 --scale 2 --offset 15
openshot-cli clip keyframe copy TARGET --property location_x --source-id SOURCE --space clip --start 1 --end 31 --at 1 --mode merge
openshot-cli clip keyframe remove CLIP --property location_x --space clip --at 31
openshot-cli clip keyframe clear CLIP --property location_x --value 0

插值、緩動與預覽

插值描述進入目標點的區段。線性插值在點之間提供穩定速率。常數插值保持前一值直到目標點，然後跳變。原生預設的貝茲爾曲線在每個區段的兩端處理緩動。因此，新增中間點可能會引入非預期的減速；若要實現單一緩動移動，請從兩個端點開始。通常保持控制柄不變，並選擇命名的預設以獲得特定風格。

探索編輯器選單中使用的相同緩動預設，無需啟動工作階段:

openshot-cli clip keyframe presets

透過設定目標點，將預設套用到進入的區段:

openshot-cli clip keyframe set CLIP --property scale_x --space clip --unit seconds --at 0 --value 1
openshot-cli clip keyframe set CLIP --property scale_x --space clip --unit seconds --at 4 --value 1.2 --easing ease-in-out

緩動選項暗示使用貝茲爾曲線。它同時設定前一點的外出控制柄與目標點的進入控制柄，並保留其他控制柄與點值。必須存在較早的點。請勿與自訂控制柄或不同插值方式結合使用。預設可用於批次與大量範本。GUI 預設 ease（"Ease (Default)"）與純貝茲爾插值使用的原生控制柄不同。反向預設可能會超出端點值。

使用原生曲線評估器在渲染前檢視動作:

openshot-cli clip keyframe preview CLIP --property scale_x --space clip --unit seconds --start 0 --end 4
openshot-cli clip keyframe preview CLIP --property scale_x --space clip --unit seconds --at 2

預覽為唯讀，且對效果與轉場的運作相同。它回傳值以及以屬性單位每秒計算的帶符號進入速率/離開速率，這些速率是從相鄰幀計算的有限差分，而非解析導數。在原生幀 1 處，進入速率為零。相鄰幀速率可檢查請求範圍外的區域。內部點附近接近零的速率表示暫停；不同速率表示速度變化。常數插值在目標點顯示跳變。

若無指定範圍，預覽涵蓋曲線的第一與最後點。範圍為包含式，預設有 17 個均勻分布的取樣點（--count：2–256）。範圍內的關鍵幀及其鄰近點也會包含，因此稀疏的取樣數不會隱藏關鍵幀停頓。最大取樣數為 1024；較大請求需縮小範圍。--at 取樣一幀。預覽報告請求空間座標與實際原生幀；秒數會像編輯時一樣對齊專案幀。

對於進階自訂控制柄，X 與 Y 均正規化至區段：X 是其幀跨度的分數；Y 是其值變化的分數。第一個控制點來自前一點的 handle_right，第二個來自目標點的 handle_left。原生預設為 right=(0.5, 0)、left=(0.5, 1)，端點切線為平坦。僅更改 handle_type 不會重新計算穿過周圍點的連續切線。移動點時會保留現有控制柄。

關鍵幀範圍為包含式，不同於剪輯選取的時間範圍。列表輸出 points，其 co.X 值使用請求的座標空間/單位。將該陣列傳遞給 keyframe paste --json @points.json，使用相同空間/單位，並選擇 --mode merge（替換匹配幀，保留其他）或 --mode replace（替換整條曲線）。copy 接受相同物件類型的來源，可選擇 --source-property，並將第一個選取的來源點錨定於目標的 --at。其他曲線與來源物件保持不變。

transform 會在第一個選取點或 --pivot 周圍套用正向時間縮放，接著是以選擇單位表示的帶符號 --offset。會拒絕產生重複座標的幀對齊，包括與選取範圍外點的碰撞。原生座標必須至少為 1。原生正規化貝茲爾控制柄與插值會隨每個點移動；控制柄非絕對幀座標。set --handles 僅更改提供的控制柄。插值屬於目標點。

clear 保留原生幀 1 的恆定基準點：指定 --value 或使用 --at 取樣現有曲線（預設為原生幀 1）。移除最後一點也會保留恆定基準，因此後續新增關鍵幀仍有效。

選取與編輯多個剪輯

使用 edit apply --dry-run 驗證批次而不更改專案。使用 edit bulk 對每個選取剪輯重複執行小型指令範本，所有變更會合併為一次復原步驟。

首先預覽選取項目:

openshot-cli edit select --json '{"layer":1000000,"start":5,"end":20,"effect":"Saturation"}'

選擇器支援 ids（唯一剪輯 ID 陣列）、layer、start/end（時間軸秒數）、file_id、effect（類別名稱或別名）及 text（true 選擇文字剪輯）。篩選條件以 AND 結合。時間範圍選擇重疊 [start, end) 的剪輯；不會裁剪這些剪輯。結果依位置、圖層及 ID 排序，並包含 ID、摘要、鎖定狀態及當前修訂版。未知 ID 為錯誤。空選擇器會被拒絕；請明確使用 {"all":true} 選擇所有剪輯。選擇限制為 256 個剪輯，且不會被靜默截斷。

例如，將此陣列儲存為 templates.json:

[
  {"method":"clip.adjust","params":{"values":{"position":{"add":2},"volume":{"multiply":0.5}}}},
  {"method":"effects.add","as":"look","params":{"type":"Saturation"}},
  {"method":"effects.keyframe.set","params":{"id":{"$ref":"look.id"},"property":"saturation","space":"clip","at":1,"value":0}},
  {"method":"effects.keyframe.set","params":{"id":{"$ref":"look.id"},"property":"saturation","space":"clip","at":31,"value":1.2}}
]

驗證後，對選擇返回的修訂版套用:

openshot-cli edit bulk --select '{"ids":["CLIP_A","CLIP_B"]}' --json @templates.json --dry-run
openshot-cli edit bulk --select '{"ids":["CLIP_A","CLIP_B"]}' --json @templates.json --expect-revision 42

現有剪輯指令繼承 id；effects.add 繼承 clip_id。在範本中省略這些目標參數。效果編輯必須參考先前命名的結果。名稱對每個選擇的剪輯都是本地的，因此 look.id 對每個剪輯指向不同的效果。若要透過明確 ID 變更現有效果實例，請繼續使用 edit apply。選擇的 ID 集合在展開前固定；位置或效果的變更不會改變剩餘目標。

clip set 套用絕對屬性；clip adjust 對數值屬性或曲線中的每個值先套用 multiply 再套用 add，同時保留點的時間、插值及標準化控制柄。它會驗證結果值，包括非負位置和音量。結構欄位保持受保護狀態。

批次操作會拒絕空選擇、鎖定的目標軌道，以及超過 256 個展開指令。每個展開操作在任何即時編輯前都會通過獨立的預檢。模擬執行不會保留產生的 ID。使用 --expect-revision 拒絕過期選擇。成功的批次為一個復原步驟，包括儲存/重新開啟後。GUI 更新會批次處理。意外的執行時/監聽器錯誤仍可能留下部分交易；錯誤會報告已完成的操作，復原會還原該組，如同 edit apply。

設定檔

發現設定檔並匹配匯入影片，無需猜測 ID:

openshot-cli profile list --search 720
openshot-cli profile get builtin:01280x0720p0024_16-09
openshot-cli profile match --file FILE_ID
openshot-cli project profile get
openshot-cli project profile set --from-file FILE_ID
openshot-cli project profile set builtin:01280x0720p0024_16-09
openshot-cli project profile set --json '{"width":640,"height":352,"display_ratio":{"num":20,"den":11},"fps":{"num":24000,"den":1001}}'

目錄條目包含穩定的 ID、描述、尺寸、有理 FPS、寬高比及掃描設定。列表/搜尋分頁顯示。來源匹配返回精確 ID 及帶有明確差異的排名替代方案。從檔案設定需精確匹配，除非指定 --create-custom；不會靜默選擇鄰近設定檔。靜態影像及純音訊來源無法定義影片設定檔。匹配使用宣告的來源 FPS。

自訂設定嵌入已儲存的專案中，包括有理速率，因此重新開啟不需安裝獨立設定檔。專案設定檔變更使用現有的幀率轉換及一次復原交易。復原/重做會還原剪輯時間及關鍵影格，包括對四捨五入敏感的位置。匯出可獨立選擇設定檔而不更改專案。

已儲存的復原歷史遵循編輯器的歷史限制偏好。該限制為軟性操作預算：所有屬於保留交易的紀錄都會保留，因此儲存不會將大型批次截斷為部分復原動作。設為零則停用已儲存歷史。獨立的 256 指令批次請求限制仍然適用。

檢視媒體與時間軸

以文字或 JSON 檢視剪輯時間與軌道佈局，或渲染影像以在匯出前檢查構圖與取景。

時間軸摘要

使用文字檢視快速概覽，或結構化 JSON 用於腳本與代理:

openshot-cli timeline view --start 5 --end 12
openshot-cli timeline view --start 5 --end 12 --format json
openshot-cli timeline overview --start 5 --end 12

timeline view 預設為簡潔文字，包含使用的軌道、物件 ID、時間軸/來源區間、串流狀態、增益及間隙/重疊。使用 --detail summary|clips|full 選擇細節，--format json 取得結構化內容，並用 --start/--end、--layer 及分頁聚焦結果。

timeline overview 提供簡潔的結構化內容，不含影像位元組：排序的 ID、每軌序列、時間軸/來源區間、可見裁剪範圍、影格座標、音訊/視訊狀態、效果及鄰近間隙或重疊。區間與影格範圍為結尾排除；影格編號從 1 起算。來源影格使用來源 FPS；時間軸與關鍵影格座標使用專案 FPS。使用 --layer 與 --start/--end 聚焦，並用 --limit/--offset 分頁（預設 100，最大 500 項）。時間重映射剪輯明確隱藏推斷的來源映射。使用返回的修訂版搭配 edit apply --expect-revision。

影格預覽與聯絡表

使用 thumbnail 渲染單一影格，或用 strip 取樣一段範圍。使用 file 檢視來源媒體，使用 timeline 檢視合成影片，包括效果與分層剪輯:

openshot-cli file thumbnail FILE_ID --frame 301 --output /tmp/source.png
openshot-cli file strip FILE_ID --start 10 --end 20 --count 12 --output /tmp/source-strip.png
openshot-cli timeline thumbnail --frame 91 --output /tmp/timeline-frame.png
openshot-cli timeline strip --start 0 --end 20 --count 12 --output /tmp/timeline-strip.png

影格影像預設為 320x180 像素；聯絡表每格預設為 160x90 像素，並附時間碼標籤。使用 --width 和 --height 選擇輸出像素。回應包含精確的取樣/影格元資料。聯絡表有助於檢視序列中的構圖；使用關鍵影格預覽與渲染影片評估取樣間的動態。

時間軸影像

擷取編輯器的軌道佈局，包括標尺、縮圖、效果、轉場和波形:

openshot-cli timeline view --start 0 --end 20 --pixels-per-second 80 --output /tmp/tracks.png

指定 --output 可選擇影像格式；--format image 也會明確選擇格式。擷取不會改變編輯器的視窗或專案。回應包含剪輯 ID、時間以及像素範圍。

影像預設寬度為 1280 像素，高度依使用的軌道調整。使用 --width、--height 或 --all-tracks 來調整佈局，使用 --track-size 或 --track-label-width 來調整軌道和標籤。起始/結束範圍決定縮放；--pixels-per-second 則根據時間範圍推算寬度。

音訊波形檢視

選擇 --mode waveforms 以檢視時間軸上的音訊包絡線:

openshot-cli timeline view --start 5 --end 12 --mode waveforms --output /tmp/waves.png

--mode auto 使用現有快取的波形顯示；--mode thumbnails 則顯示縮圖。波形表示來源的峰值/RMS 水準，並包含剪輯音量與時間調整，位於音效或混音之前。

未快取的波形擷取會解碼整個來源，限制為每個來源最多 600 秒，每次請求最多 1200 秒來源時間。縮小可見範圍不會減少解碼工作。對於較長的來源，請先在編輯器中產生波形或使用縮圖模式。後續請求可重複使用快取的波形。

影像輸出與限制

影像路徑必須是存在目錄中的新 PNG 檔案。影像限制為每軸最多 4096 像素、總像素數不超過 8,388,608 以及最多 64 張聯絡表樣本。超出這些限制的請求會在渲染前失敗。

影像會寫入檔案；JSON 回應包含其路徑與 image_bytes 大小。檢視會等待影像完成，大型請求可能會短暫佔用編輯器。

處理指令逾時

請求逾時不代表變更失敗。請先使用錯誤中的操作 ID 搭配 operation get ID 指令再重試。operation list 可查詢近期變更及其狀態、版本與結果。完成的操作若結果較小，會保留結果，包括回傳的物件 ID。儲存限制為 100 筆操作與 4 MiB，單一結果體積超過 256 KiB 則不保留。這些紀錄僅存在於當前執行階段，不會在崩潰後還原專案，也無法防止重複指令再次套用相同編輯。匯出工作有自己的狀態與列表指令。