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