cli-anything-shotcut

cli-anything-shotcut

一个基于 MLT XML 格式构建的有状态视频编辑命令行界面。专为需要在无 GUI 环境下创建和编辑 Shotcut 项目的 AI Agent 和高级用户设计。

安装

此 CLI 作为 cli-anything-shotcut 包的一部分安装：

pip install cli-anything-shotcut

前置条件：

• Python 3.10+
• melt（MLT CLI）—— 渲染和播放所必需
• ffmpeg / ffprobe —— 媒体探测所必需
• 系统中必须安装 shotcut

用法

基本命令

# Show help
cli-anything-shotcut --help

# Start interactive REPL mode
cli-anything-shotcut

# Create a new project
cli-anything-shotcut project new -o project.json

# Run with JSON output (for agent consumption)
cli-anything-shotcut --json project info -p project.json

REPL 模式

在不带子命令调用时，CLI 会进入支持撤销/重做的交互式 REPL 会话：

cli-anything-shotcut
# or with a project:
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，使 Agent 能够低成本地了解最近几次发布的内容。

查看器命令：

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
# Or with JSON output for programmatic use
cli-anything-shotcut --json project new -o myproject.json

交互式 REPL 会话

启动一个支持撤销/重做的交互式会话。

cli-anything-shotcut
# Enter commands interactively
# Use 'help' to see available commands
# Use 'undo' and 'redo' for history navigation

导出项目

将项目导出为最终输出格式。

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 会自动插入空白。
• 命令行会拒绝与现有剪辑重叠。
• 优先使用显式的 --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 标志）：供 Agent 使用的结构化 JSON

# Human output
cli-anything-shotcut project info -p project.json

# JSON output for agents
cli-anything-shotcut --json project info -p project.json

面向 AI Agent

以编程方式使用此 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 ... 检查/打开现有 bundle 或实时会话

更多信息

• 完整文档：参见包中的 README.md
• 测试覆盖率：参见包中的 TEST.md
• 方法论：参见 cli-anything-plugin 中的 HARNESS.md

版本

1.0.0