命令行界面

将 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 格式输出到 stdout,默认文本时间线视图除外。错误以 JSON 格式输出到 stderr,退出状态为 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,以对每个项目使用同一输出配置文件。

首先在同一终端成功运行上面的匹配自动会话 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

导出还接受带有可选 --create-custom 的 --from-file FILE_ID。设置按以下顺序解析:项目默认、预设、高级 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(颜色,带有从 0 到 255 的 .red、.green、.blue 和 .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秒、帧率为30fps的项目中的剪辑,剪辑帧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(“缓动(默认)”)不同于普通贝塞尔插值使用的原生手柄。回退预设可能会超出端点值。

使用原生曲线评估器在渲染前检查运动:

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。原生默认值为右=(0.5, 0),左=(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 会被省略。这些记录仅在当前会话中有效。它们不会在崩溃后恢复项目,也不会阻止重复命令再次应用相同编辑。导出任务有自己的状态/列表命令。