コマンドラインインターフェース

OpenShot をコマンドラインのワークフローに取り入れましょう。映像をインポートし、クリップをトリミング・配置し、エフェクトを適用し、キーフレームでプロパティをアニメーション化し、ターミナルから動画をエクスポートできます。いくつかのコマンドを使って繰り返しの編集を自動化したり、定期的なプロジェクトのスクリプトを書いたり、AIエージェントに動画の組み立てや調整を手伝わせたりできます。

コマンドラインはエディターと同じプロジェクトで動作します。開いているエディターを操作して変更を確認しながら作業することも、ウィンドウを開かずにヘッドレスセッションで作業することも可能です。セッションはコマンド間でプロジェクトを開いたままにし、編集内容、元に戻す履歴、エクスポートジョブを保持します。後で編集を続けたいときは、いつでも .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

スクリプトや繰り返しコマンドの場合は、現在のシェルで一度だけ設定してください:

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 はカーブをサンプリングして、エクスポート前に停止やジャンプを見つけることができます。レンダリングされた動きも確認してください。コンタクトシートだけではアニメーションの感覚を示すことはできません。

  • エクスポートを保存して追跡します。 プロジェクトを明示的に保存し、出力を完了と見なす前にエクスポートジョブの状態を確認してください。リクエストがタイムアウトした場合は、編集を繰り返す前にその状態を確認してください。

以下のセクションでは、これらのワークフローとそのタイミング規則について説明します。

セッションと出力

セッションの開始または検索

ヘッドレスセッションを1つ開始する(エディタウィンドウなし):

openshot-cli session start

起動時に既存のプロジェクトを開くには、--project "/path/project.osp" を追加します。成功したJSONレスポンスには result.session_id が含まれます。その値をコピーしてください。OpenShotがすでに実行中の場合やIDを忘れた場合は、利用可能なセッションを次のコマンドで探します:

openshot-cli session list

編集するプロジェクトのセッションを選択してください。各コマンドごとに新しいセッションを開始する必要はありません。

セッションの選択

Tip

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コマンドの場合は、Getting started からインストールした実行ファイルに置き換えてください。この選択はこのターミナルとそこから起動されたコマンドに有効です。新しいターミナルで再設定するか、別のセッションに切り替えるときに更新してください。

残りの編集およびエクスポートの例は OPENSHOT_SESSION が設定されていることを前提としています。 次の小節では、スクリプト用にIDを自動的に取得する方法を示します。

1つのコマンドだけ別のセッションを指定するには、--session を使用します。これはターミナルの選択を変更せずに OPENSHOT_SESSION を上書きします:

openshot-cli --session OTHER_SESSION_ID project get

パッケージ化された実行ファイルの場合、このオーバーライドを --cli の後、コマンドグループの前に置きます: --cli --session OTHER_SESSION_ID project get。

自動選択は、到達可能なセッションが正確に1つ存在する場合にのみ機能します。session_required が表示されたら、session list を実行して意図したセッションを明示的に選択してください。リストにない場合は再度開始し、新しいIDを使用してください。Help、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(JSONを読むために jq が必要):

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 で見つけてください。返されたセッションIDを OPENSHOT_SESSION に設定し、プロジェクトを開くか検査します:

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の横長バージョンをエクスポートし、次に1080×1080の正方形バージョンをエクスポートします。これらのプロファイルはすべて30fpsを使用します:

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

各バージョンに異なる出力ファイル名を使用してください。バージョンを一致させたい場合はジョブ間で編集を変更しないでください。アスペクト比の変更はフレーミングを変えることがあるため、特にタイトルやアニメーション対象を含めて各出力を確認してください。別途作成した正方形または縦長バージョンの場合は、プロジェクトのコピーを保存し、プロジェクトプロファイルを変更し、エクスポート前にクリップを調整してください。カスタムプロファイルやエンコードオプションについては以下のプロファイルとエクスポート設定を参照してください。

複数プロジェクトの一括エクスポート

ヘッドレスセッションを1つ再利用して複数の保存済みプロジェクトを順番にレンダリングします。プロジェクトを開き、--wait 付きでエクスポートし、次のプロジェクトを開きます。以下の例は各プロジェクトの解像度とフレームレートを使用し、.osp ファイルの隣にMP4ファイルを作成します。すべてのプロジェクトで同じ出力プロファイルを使うにはエクスポートコマンドに --profile PROFILE_ID を追加してください。

まず、上記の自動セッション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

Export は --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

Capabilities はコンパイル済みコーデックの利用可能性を報告し、物理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始まりです。例えば、30fpsで最初の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 はトップレベルのプロパティをマージします。スカラーはキーフレーム付きプロパティを定数に変えます。指定されたネストされたカーブはそのカーブを置き換えます;1点だけ変更するには keyframe set を使います。JSON引数はインラインJSON、@file.json、または標準入力用の - を受け付けます。プロパティ名、型、列挙、キーフレーム、参照、タイミングはプロジェクト編集前に検証されます。エラーはフィールド、期待値、受け取った値、可能な修正を示します。GUIスライダーの範囲はエンジンがそれを超える値をサポートする場合は参考値です。

フェードの追加

clip fade ID --in 0.5 --out 0.5 はソーストリムのキーフレーム座標を自動計算します。アルファカーブを置き換えます;代わりに --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

モーションプリセットはクリップの現在の変換に対して相対的です。ルックプリセットは1つのエフェクトを追加または置換し、none はそれを削除します。速度とリピートはすべてのキーフレームを再タイミングし、クリップの長さを変更します。clip speed --mode reset は通常速度に戻します。他のメニュー操作は単純な編集です:clip set で回転とレイアウト、effects add Crop でクロップ。これらのコマンドは edit apply と edit bulk でも動作します。

テキストの追加とスタイリング

text add はテキストを作成し、エディターの Text ツールと同じテキストを使ってクリップとして配置します。省略したオプションはエディターのデフォルトスタイルを使用します:

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

単語、フォント、サイズ、配置、ボックス幅、デフォルトカラーはプロジェクトファイル内のテキストに属し、エディターと同様にそれを使用するすべてのクリップで共有されます。1つのクリップでの 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、.alpha は0から255)、および text_stroke_width、text_border_width、text_background_corner です。クリップ固有のアニメーションは共有スタイルより優先され、text get はクリップがアニメーションするスタイルを一覧表示します。text reset CLIP_ID はクリップをデフォルトスタイルに戻します(Text → Reset Style と同様)。--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 マップが含まれます。成功したバッチ内のすべての変更は1つのアンドゥ/リドゥステップを形成します。project.profile.set はポピュレートされたタイムラインもサポートします。開く、保存、エクスポート、検査コマンドは編集バッチの外にあります。各コマンドのヘルプにはJSONパラメータ名が一覧表示され、シェルフラグのアンダースコア表記(例:--fps-num は fps_num)も含まれます。

バッチの検証とエラー処理

編集バッチ内のすべてのコマンドはライブ更新前に切り離されたプロジェクトで事前検証されます。無効な入力はライブプロジェクトとリビジョンを変更しません。有効なバッチは1つのアンドゥグループを形成します。予期しない実行時エラーでも部分的な変更が発生することがあり、エラーは完了した操作を報告します。タイムアウトはキャンセルを意味しないため、再試行前に状態を確認してください。

正確なキーフレーム編集

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 は既存のエンジンキーフレーム座標(ソーストリムを含む)です。クリップ座標は表示されているクリップのインポイントから始まり、タイムライン座標はプロジェクト時間のゼロから始まります。アタッチされたエフェクトは親クリップのタイミングを使用します。これらの座標はアニメーション時間を示し、タイムリマッピングカーブで選択されたメディアフレームではありません。

30fpsのプロジェクトで、5秒に位置し2秒でトリミングされたクリップの場合、クリップフレーム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

補間、イージング、およびプレビュー

補間は目的地のポイントへのセグメントを表します。線形はポイント間で一定の速度を提供します。定数は目的地まで前の値を保持し、その後ジャンプします。ネイティブのデフォルトBezierは各セグメントの両端でイーズを処理します。中間ポイントを追加すると意図しない減速が発生する可能性があるため、イーズされた動きは2つの端点から始めます。通常はハンドルをそのままにして、特定のスタイルの名前付きプリセットを選択します。

セッションなしでエディターのメニューで使用される同じイージングプリセットを確認する:

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

イージングオプションはBezierを意味します。前のポイントのアウトゴーイングハンドルと目的地のインカミングハンドルを一緒に設定し、他のハンドルやポイント値を保持します。前のポイントが存在する必要があります。カスタムハンドルや異なる補間と組み合わせないでください。プリセットはバッチや一括テンプレートで機能します。GUIプリセットのease(「Ease (Default)」)は、単純なBezier補間で使用されるネイティブハンドルとは異なります。バックプリセットは端点の値をオーバーシュートすることがあります。

ネイティブカーブ評価器を使用してレンダリング前に動きを検査する:

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

プレビューは読み取り専用で、エフェクトとトランジションで同様に機能します。隣接するフレームから計算された、プロパティ単位毎秒の値と符号付きのincoming_rate / outgoing_rateを返します。これらは有限差分であり、解析的微分ではありません。ネイティブフレーム1ではincoming_rateはゼロです。隣接フレームのレートは要求範囲外も検査できます。内部ポイント付近のほぼゼロのレートは一時停止を示し、異なるレートは速度変化を示します。定数補間は目的地でのジャンプを示します。

範囲指定がない場合、プレビューは曲線の最初と最後のポイントをカバーします。範囲は包含的で、デフォルトで17の均等間隔サンプルがあります(--count: 2–256)。範囲内のキーフレームとその隣接ポイントも含まれるため、サンプル数が少なくてもキーフレームの停止は隠れません。最大は1024サンプルで、それ以上は狭い範囲が必要です。--atは1フレームをサンプリングします。プレビューは要求された空間座標と実際のネイティブフレームを報告します。秒は編集時と同様にプロジェクトフレームにスナップします。

高度なカスタムハンドルでは、XとYの両方がセグメントに正規化されます:Xはフレーム範囲の割合、Yは値の変化の割合です。最初のコントロールは前のポイントのhandle_rightから、2番目は目的地のhandle_leftから来ます。ネイティブのデフォルトはright=(0.5, 0)、left=(0.5, 1)で、端点の接線は平坦です。handle_typeを変更するだけでは周囲のポイントを通る連続接線は再計算されません。ポイントを移動すると既存のハンドルは保持されます。

キーフレーム範囲はクリップ選択の時間範囲とは異なり包含的です。リストは要求された座標空間/単位を使用するco.X値を持つpointsを出力します。その配列を同じ空間/単位で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を使用します。選択した各クリップに小さなコマンドテンプレートを繰り返し適用し、すべての変更を1つの元に戻すステップにまとめるには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 を使用してください。成功したバッチは保存/再開後も含めて1つのアンドゥステップです。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を使用します。

カスタム設定は有理レートを含めて保存されたプロジェクトに埋め込まれているため、再度開く際に別のプロファイルファイルをインストールする必要はありません。プロジェクトのプロファイル変更は既存のフレームレート変換と1つのアンドゥトランザクションを使用します。アンドゥ/リドゥは丸めに敏感な位置を含むクリップのタイミングとキーフレームを復元します。エクスポートはプロジェクトを変更せずに独立してプロファイルを選択できます。

保存されたアンドゥ履歴はエディターの履歴制限設定に従います。この制限はソフトなアクション予算であり、保持されたトランザクションに属するすべての記録が保持されるため、保存時に大きなバッチが部分的なアンドゥアクションに切り詰められることはありません。ゼロは保存履歴を無効にします。別の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レベルを、クリップの音量とタイミング調整と共に表します。

キャッシュされていない波形抽出はソース全体をデコードし、1ソースあたり600秒、リクエストあたり1200ソース秒に制限されます。表示範囲を狭めてもデコード作業は減りません。より長いソースの場合は、先にエディターで波形を生成するかサムネイルモードを使用してください。後続のリクエストはキャッシュされた波形を再利用できます。

画像出力と制限

画像パスは既存のディレクトリ内の新しいPNGファイルでなければなりません。画像は軸ごとに4096ピクセル、合計8,388,608ピクセル、コンタクトシートサンプルは64までに制限されます。これらの制限を超えるリクエストはレンダリング前に失敗します。

画像はファイルに書き込まれ、JSONレスポンスにはパスと image_bytes サイズが含まれます。検査は画像の完了を待ち、大きなリクエストは一時的にエディターを占有することがあります。

コマンドタイムアウトの処理

リクエストのタイムアウトは変更が失敗したことを意味しません。再試行前にエラーの操作IDを使って operation get ID を実行してください。operation list は最近の変更とその状態、リビジョン、結果を検出します。完了した操作は小さい場合に結果を保持し、返されたオブジェクトIDも含みます。ストレージは100操作と4MiBに制限され、256KiBを超える個別の結果本文は省略されます。これらの記録は実行中のセッションのみ有効で、クラッシュ後のプロジェクト復元や同じ編集の再適用防止にはなりません。エクスポートジョブは独自のステータス/リストコマンドを持ちます