Back to Details

cli-anything-shotcut

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cli-anything-shotcut

cli-anything-shotcut

A stateful command-line interface for video editing, built on the MLT XML format. Designed for AI agents and power users who need to create and edit Shotcut projects without a GUI.
一款基于MLT XML格式的有状态视频编辑命令行界面，专为AI代理和无需GUI即可创建、编辑Shotcut项目的高级用户设计。

Installation

安装

This CLI is installed as part of the cli-anything-shotcut package:
bash
pip install cli-anything-shotcut
Prerequisites:
  • Python 3.10+
  • shotcut must be installed on your system
该CLI作为cli-anything-shotcut包的一部分进行安装：
bash
pip install cli-anything-shotcut
前置要求：
  • Python 3.10+
  • 系统中必须安装Shotcut

Usage

使用

Basic Commands

基础命令

bash
undefined
bash
undefined

Show help

显示帮助信息

cli-anything-shotcut --help
cli-anything-shotcut --help

Start interactive REPL mode

启动交互式REPL模式

cli-anything-shotcut
cli-anything-shotcut

Create a new project

创建新项目

cli-anything-shotcut project new -o project.json
cli-anything-shotcut project new -o project.json

Run with JSON output (for agent consumption)

以JSON格式输出（供代理使用）

cli-anything-shotcut --json project info -p project.json
undefined
cli-anything-shotcut --json project info -p project.json
undefined

REPL Mode

REPL模式

When invoked without a subcommand, the CLI enters an interactive REPL session:
bash
cli-anything-shotcut
当不指定子命令调用时，CLI会进入交互式REPL会话：
bash
cli-anything-shotcut

Enter commands interactively with tab-completion and history

交互式输入命令，支持自动补全和历史记录


The REPL exposes the same practical helpers as command mode, including
`add-clip ... --at`, `volume-envelope`, and `duck`.

REPL提供与命令模式相同的实用辅助功能，包括`add-clip ... --at`、`volume-envelope`和`duck`。

Command Groups

命令组

Project

项目管理

Project management: new, open, save, info.
CommandDescription
new
Create a new blank project
open
Open an existing .mlt project file
save
Save the current project
info
Show detailed project information
profiles
List available video profiles
xml
Print the raw MLT XML of the current project
项目管理命令：新建、打开、保存、信息查看。
命令描述
new
创建新的空白项目
open
打开现有的.mlt项目文件
save
保存当前项目
info
显示详细的项目信息
profiles
列出可用的视频配置文件
xml
打印当前项目的原始MLT XML内容

Timeline

时间轴

Timeline operations: tracks, clips, trimming.
CommandDescription
show
Show the timeline overview
tracks
List all tracks
add-track
Add a new track to the timeline
remove-track
Remove a track by index
add-clip
Add a media clip to a track; supports 
--at
for absolute timeline placement
remove-clip
Remove a clip from a track
move-clip
Move a clip between tracks or positions
trim
Trim a clip's in/out points
split
Split a clip into two at the given timecode
clips
List all clips on a track
add-blank
Add a blank gap to a track
set-name
Set a track's display name
mute
Mute or unmute a track
hide
Hide or unhide a video track
时间轴操作命令：轨道、剪辑、修剪。
命令描述
show
显示时间轴概览
tracks
列出所有轨道
add-track
向时间轴添加新轨道
remove-track
通过索引删除轨道
add-clip
向轨道添加媒体剪辑；支持
--at
参数指定时间轴上的绝对位置
remove-clip
从轨道删除剪辑
move-clip
在轨道间或不同位置移动剪辑
trim
修剪剪辑的入点/出点
split
在指定时间码处将剪辑分割为两段
clips
列出轨道上的所有剪辑
add-blank
向轨道添加空白间隙
set-name
设置轨道的显示名称
mute
静音或取消静音轨道
hide
隐藏或取消隐藏视频轨道

Filter Group

滤镜组

Filter operations: add, remove, configure effects.
CommandDescription
list-available
List all available filters
info
Show detailed info about a filter and its parameters
add
Add a filter to a clip, track, or globally
remove
Remove a filter by index
set
Set a parameter on a filter
volume-envelope
Create or replace a keyframed volume envelope on a track or clip
duck
Build a practical ducking envelope over one or more time windows
list
List active filters on a target
滤镜操作命令：添加、删除、配置效果。
命令描述
list-available
列出所有可用滤镜
info
显示滤镜及其参数的详细信息
add
向剪辑、轨道或全局添加滤镜
remove
通过索引删除滤镜
set
设置滤镜的参数
volume-envelope
为轨道或剪辑创建或替换关键帧音量包络
duck
在一个或多个时间窗口上构建实用的闪避包络
list
列出目标上的所有激活滤镜

Media

媒体

Media operations: probe, list, check files.
CommandDescription
probe
Analyze a media file's properties
list
List all media clips in the current project
check
Check all media files for existence
thumbnail
Generate a thumbnail from a video file
媒体操作命令：探测、列出、检查文件。
命令描述
probe
分析媒体文件的属性
list
列出当前项目中的所有媒体剪辑
check
检查所有媒体文件是否存在
thumbnail
从视频文件生成缩略图

Export

导出

Export/render operations.
CommandDescription
presets
List available export presets
preset-info
Show details of an export preset
render
Render the project to a video file
导出/渲染操作命令。
命令描述
presets
列出可用的导出预设
preset-info
显示导出预设的详细信息
render
将项目渲染为视频文件

Transition Group

转场组

Transition operations: dissolve, wipe, and other transitions.
CommandDescription
list-available
List all available transition types
info
Show detailed info about a transition type
add
Add a transition between two tracks
remove
Remove a transition by index
set
Set a parameter on a transition
list
List all transitions on the timeline
转场操作命令：溶解、擦除及其他转场效果。
命令描述
list-available
列出所有可用的转场类型
info
显示转场类型的详细信息
add
在两个轨道间添加转场
remove
通过索引删除转场
set
设置转场的参数
list
列出时间轴上的所有转场

Composite Group

合成组

Compositing: blend modes, PIP, opacity.
CommandDescription
blend-modes
List all available blend modes
set-blend
Set the blend mode for a track
get-blend
Get the current blend mode for a track
set-opacity
Set the opacity of a track (0.0-1.0)
pip
Set picture-in-picture position for a clip
合成操作命令：混合模式、画中画、透明度。
命令描述
blend-modes
列出所有可用的混合模式
set-blend
设置轨道的混合模式
get-blend
获取轨道当前的混合模式
set-opacity
设置轨道的透明度（0.0-1.0）
pip
设置剪辑的画中画位置

Session

会话

Session management: status, undo, redo.
CommandDescription
status
Show current session status
undo
Undo the last operation
redo
Redo the last undone operation
save
Save session state to disk
list
List all saved sessions
会话管理命令：状态、撤销、重做。
命令描述
status
显示当前会话状态
undo
撤销上一次操作
redo
重做上一次撤销的操作
save
将会话状态保存到磁盘
list
列出所有已保存的会话

Examples

示例

Create a New Project

创建新项目

Create a new shotcut project file.
bash
cli-anything-shotcut project new -o myproject.json
创建新的Shotcut项目文件。
bash
cli-anything-shotcut project new -o myproject.json

Or with JSON output for programmatic use

或以JSON格式输出供程序化使用

cli-anything-shotcut --json project new -o myproject.json
undefined
cli-anything-shotcut --json project new -o myproject.json
undefined

Interactive REPL Session

交互式REPL会话

Start an interactive session with undo/redo support.
bash
cli-anything-shotcut
启动支持撤销/重做功能的交互式会话。
bash
cli-anything-shotcut

Enter commands interactively

交互式输入命令

Use 'help' to see available commands

使用'help'查看可用命令

Use 'undo' and 'redo' for history navigation

使用'undo'和'redo'导航历史操作

undefined
undefined

Export Project

导出项目

Export the project to a final output format.
bash
cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite
将项目导出为最终输出格式。
bash
cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite

Deterministic Timeline Reconstruction

确定性时间轴重建

For rebuilds, prefer absolute placement over append-only clip insertion:
bash
cli-anything-shotcut --project myproject.json -s timeline add-clip intro.mp4 \
  --track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000

cli-anything-shotcut --project myproject.json -s timeline add-clip broll.mp4 \
  --track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000
Notes:
  • --at
    inserts blanks automatically when the target time lands in empty space.
  • The CLI rejects overlap with an existing clip instead of silently changing the timeline.
  • For agent-built timelines, prefer explicit 
    --in
    and 
    --out
    values so later absolute placement remains unambiguous.
重建时，优先使用绝对位置而非仅追加插入剪辑：
bash
cli-anything-shotcut --project myproject.json -s timeline add-clip intro.mp4 \
  --track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000

cli-anything-shotcut --project myproject.json -s timeline add-clip broll.mp4 \
  --track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000
注意：
  • --at
    参数会在目标时间处于空白区域时自动插入空白片段。
  • CLI会拒绝与现有剪辑重叠的操作，而非静默修改时间轴。
  • 对于AI代理构建的时间轴，优先使用明确的
    --in
    和
    --out
    值，以便后续的绝对位置操作保持明确。

Audio Automation

音频自动化

The released CLI now includes higher-level audio automation helpers:
bash
cli-anything-shotcut --project myproject.json -s 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.json -s 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 \
  --attack 00:00:00.150 --release 00:00:00.250
Keyframed 
volume
filters now export as ffmpeg 
volume=
expressions instead of collapsing to a simple fade. This is materially better, but you should still review final renders when automation is editorially important.
发布的CLI现在包含更高级的音频自动化辅助功能：
bash
cli-anything-shotcut --project myproject.json -s 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.json -s 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 \
  --attack 00:00:00.150 --release 00:00:00.250
关键帧
volume
滤镜现在会导出为ffmpeg的
volume=
表达式，而非简化为简单的淡入淡出。这一改进效果显著，但当自动化对编辑至关重要时，仍需检查最终渲染结果。

State Management

状态管理

The CLI maintains session state with:
  • Undo/Redo: Up to 50 levels of history
  • Project persistence: Save/load project state as JSON
  • Session tracking: Track modifications and changes
CLI通过以下方式维护会话状态：
  • 撤销/重做：最多支持50级历史记录
  • 项目持久化：以JSON格式保存/加载项目状态
  • 会话跟踪：跟踪修改和变更

Output Formats

输出格式

All commands support dual output modes:
  • Human-readable (default): Tables, colors, formatted text
  • Machine-readable (
    --json
    flag): Structured JSON for agent consumption
bash
undefined
所有命令支持两种输出模式：
  • 人类可读格式（默认）：表格、颜色、格式化文本
  • 机器可读格式（
    --json
    标志）：结构化JSON，供代理使用
bash
undefined

Human output

人类可读输出

cli-anything-shotcut project info -p project.json
cli-anything-shotcut project info -p project.json

JSON output for agents

供代理使用的JSON输出

cli-anything-shotcut --json project info -p project.json
undefined
cli-anything-shotcut --json project info -p project.json
undefined

For AI Agents

面向AI代理

When using this CLI programmatically:
  1. Always use 
    --json
    flag     for parseable output
  2. Check return codes - 0 for success, non-zero for errors
  3. Parse stderr for error messages on failure
  4. Use absolute paths for all file operations
  5. Verify outputs exist after export operations
  6. Prefer 
    timeline add-clip --at
     when recreating a known edit
  7. Review final renders after keyframed volume or ducking changes
程序化使用本CLI时：
  1. 始终使用
    --json
    标志    以获得可解析的输出
  2. 检查返回码——0表示成功，非0表示错误
  3. 解析stderr以获取失败时的错误信息
  4. 使用绝对路径进行所有文件操作
  5. 导出操作后验证输出是否存在
  6. 重建已知编辑时优先使用
    timeline add-clip --at
  7. 关键帧音量或闪避变更后检查最终渲染结果

More Information

更多信息

  • Full documentation: See README.md in the package
  • Test coverage: See TEST.md in the package
  • Methodology: See HARNESS.md in the cli-anything-plugin
  • 完整文档：查看包中的README.md
  • 测试覆盖率：查看包中的TEST.md
  • 方法学：查看cli-anything-plugin中的HARNESS.md

Version

版本

1.0.0
1.0.0