Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

fix(shotcut): fix --at regression on non-empty tracks, update docs

Feng Yuf6e6a899dc03
diff --git a/shotcut/agent-harness/cli_anything/shotcut/README.md b/shotcut/agent-harness/cli_anything/shotcut/README.md
index ddfc134ad..b9d8cb401 100644
--- a/shotcut/agent-harness/cli_anything/shotcut/README.md
+++ b/shotcut/agent-harness/cli_anything/shotcut/README.md
@@ -8,20 +8,30 @@ without a GUI.
- Python 3.10+
- `click` (CLI framework)
+- `melt` (MLT CLI) — **required** for rendering and playback
+- `ffmpeg` / `ffprobe` — required for media probing and export
Optional (for interactive REPL):
- `prompt_toolkit`
-Optional (for rendering/media probing):
-- `ffmpeg` / `ffprobe`
-- `melt` (MLT CLI)
-
## Install Dependencies
```bash
pip install click prompt_toolkit
```
+System tools (required for full functionality):
+```bash
+# Arch Linux
+pacman -S melt ffmpeg
+
+# Ubuntu/Debian
+apt install melt ffmpeg
+
+# macOS
+brew install mlt ffmpeg
+```
+
## How to Run
All commands are run from the `agent-harness/` directory.
@@ -45,12 +55,88 @@ python3 -m cli.shotcut_cli --json --project my_project.mlt project info
### Interactive REPL
```bash
+# Start with a new project
python3 -m cli.shotcut_cli repl
+
+# Or open an existing project
python3 -m cli.shotcut_cli repl --project my_project.mlt
```
Inside the REPL, type `help` for all available commands.
+#### REPL Command Reference
+
+**Project & Session:**
+
+| Command | Description |
+|---------|-------------|
+| `new [profile]` | Create new project (default: `hd1080p30`) |
+| `open <path>` | Open an existing `.mlt` project file |
+| `save [path]` | Save the project |
+| `info` | Show project info |
+| `xml` | Print raw MLT XML |
+| `status` | Show session status |
+| `undo` | Undo last operation |
+| `redo` | Redo last undone operation |
+
+**Media:**
+
+| Command | Description |
+|---------|-------------|
+| `media import <file> [--caption name]` | Import media file, returns `clip_id` |
+| `media` | List all imported media |
+| `probe <file>` | Analyze a media file |
+
+**Timeline:**
+
+| Command | Description |
+|---------|-------------|
+| `add-track <video\|audio> [name]` | Add a track |
+| `tracks` | List all tracks |
+| `show` | Show timeline overview |
+| `add-clip <clip_id> <track> [in] [out] [--at time]` | Add clip to track |
+| `clips <track>` | List clips on a track |
+| `remove-clip <track> <clip>` | Remove a clip |
+| `trim <track> <clip> [--in tc] [--out tc]` | Trim clip in/out points |
+| `split <track> <clip> <at>` | Split clip at timecode |
+
+**Filters:**
+
+| Command | Description |
+|---------|-------------|
+| `list-filters [video\|audio]` | Browse available filters |
+| `filter-info <name>` | Show filter details and params |
+| `add-filter <name> [--track n] [--clip n] [p=v ...]` | Add filter |
+| `filters [--track n] [--clip n]` | List active filters |
+| `remove-filter <idx> [--track n] [--clip n]` | Remove filter |
+| `set-filter <idx> <param> <value> [--track n] [--clip n]` | Set filter param |
+| `volume-envelope [--track n] [--clip n] TIME=LEVEL ...` | Set volume envelope |
+| `duck [--track n] [--clip n] START..END ...` | Apply ducking envelope |
+
+**Export:**
+
+| Command | Description |
+|---------|-------------|
+| `presets` | List export presets |
+| `render <output> [--preset name]` | Render project |
+
+#### REPL Example Session
+
+```
+> new hd1080p30
+> add-track video Main
+> media import intro.mp4
+ Imported intro.mp4 as clip0
+> media import main.mp4
+ Imported main.mp4 as clip1
+> add-clip clip0 1 00:00:00.000 00:00:05.000
+> add-clip clip1 1 00:00:00.000 00:00:10.000 --at 00:00:05.000
+> add-filter brightness --track 1 --clip 0 level=1.3
+> show
+> save
+> render output.mp4 --preset h264-high
+```
+
## Command Reference
### Project
@@ -205,7 +291,7 @@ python3 -m cli.shotcut_cli --project edit.mlt filter add brightness --track 1 --
# Duck the music during narration
python3 -m cli.shotcut_cli --project edit.mlt filter duck --track 2 \
- --window 00:00:00.000:00:00:05.000 --duck 0.2
+ --window 00:00:00.000..00:00:05.000 --duck 0.2
# View the timeline
python3 -m cli.shotcut_cli --project edit.mlt timeline show
diff --git a/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py b/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py
index e82f3615b..3bb2081e5 100644
--- a/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py
+++ b/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py
@@ -164,28 +164,41 @@ def _absolute_insertion_point(
raise ValueError(f"Timeline position must be non-negative, got {at_time!r}")
children = list(playlist)
- entries = mlt_xml.get_playlist_entries(playlist)
timeline_cursor = 0
- for idx, entry in enumerate(entries):
- duration = _entry_duration_frames(session, entry)
- start = timeline_cursor
- end = start + duration
- prop_offset = sum(1 for c in children[:sum(1 for e in entries[:idx]
- if e is entry)]
- if c.tag == "property")
- if target == start:
- return idx + prop_offset, 0, 0
- if entry["type"] == "blank" and start < target < end:
- leading = target - start
- trailing = end - target
- return idx + prop_offset, leading, trailing
- if entry["type"] == "entry" and start < target < end:
- raise RuntimeError(
- f"Timeline position {at_time} overlaps an existing clip on track; "
- "split or move clips before placing another clip there"
- )
- timeline_cursor = end
+ for phys_idx, child in enumerate(children):
+ if child.tag == "property":
+ continue
+
+ if child.tag == "blank":
+ duration = parse_time_input(child.get("length", "00:00:00.000"), fps_num, fps_den)
+ start = timeline_cursor
+ end = start + duration
+ if target == start:
+ return phys_idx, 0, 0
+ if start < target < end:
+ return phys_idx, target - start, end - target
+ timeline_cursor = end
+ continue
+
+ if child.tag == "entry":
+ in_tc = child.get("in", "00:00:00.000")
+ out_tc = child.get("out")
+ if out_tc is None:
+ prod = mlt_xml.find_element_by_id(session.root, child.get("producer", ""))
+ out_tc = prod.get("out", "00:00:00.000") if prod is not None else "00:00:00.000"
+ duration = parse_time_input(out_tc, fps_num, fps_den) - parse_time_input(in_tc, fps_num, fps_den)
+ start = timeline_cursor
+ end = start + duration
+ if target == start:
+ return phys_idx, 0, 0
+ if start < target < end:
+ raise RuntimeError(
+ f"Timeline position {at_time} overlaps an existing clip on track; "
+ "split or move clips before placing another clip there"
+ )
+ timeline_cursor = end
+ continue
return len(children), max(0, target - timeline_cursor), 0
diff --git a/shotcut/agent-harness/cli_anything/shotcut/skills/SKILL.md b/shotcut/agent-harness/cli_anything/shotcut/skills/SKILL.md
index 5a5721b75..74f20ed60 100644
--- a/shotcut/agent-harness/cli_anything/shotcut/skills/SKILL.md
+++ b/shotcut/agent-harness/cli_anything/shotcut/skills/SKILL.md
@@ -1,6 +1,5 @@
---
-name: >-
- cli-anything-shotcut
+name: "cli-anything-shotcut"
description: >-
Command-line interface for Shotcut - A stateful command-line interface for video editing, built on the MLT XML format. Designed for AI ag...
---
@@ -19,7 +18,9 @@ pip install cli-anything-shotcut
**Prerequisites:**
- Python 3.10+
-- shotcut must be installed on your system
+- `melt` (MLT CLI) — required for rendering and playback
+- `ffmpeg` / `ffprobe` — required for media probing
+- `shotcut` must be installed on your system
## Usage
@@ -42,13 +43,56 @@ cli-anything-shotcut --json project info -p project.json
### REPL Mode
-When invoked without a subcommand, the CLI enters an interactive REPL session:
+When invoked without a subcommand, the CLI enters an interactive REPL session with undo/redo support:
```bash
cli-anything-shotcut
-# Enter commands interactively with tab-completion and history
+# or with a project:
+cli-anything-shotcut --project my_project.mlt
```
+#### REPL Commands
+
+**Workflow:** Always `media import` first to get a `clip_id`, then use `add-clip` to place it on the timeline.
+
+**Project & Session:**
+- `new [profile]` — Create new project (default: `hd1080p30`)
+- `open <path>` — Open `.mlt` file
+- `save [path]` — Save project
+- `info` — Show project info
+- `xml` — Print raw MLT XML
+- `status` — Show session status
+- `undo` / `redo` — Navigate operation history
+
+**Media (two-step model):**
+- `media import <file> [--caption name]` — Import file into project bin, returns `clip_id` (e.g., `clip0`)
+- `media` — List all imported media
+- `probe <file>` — Analyze a media file
+
+**Timeline:**
+- `add-track <video|audio> [name]` — Add a track
+- `tracks` — List all tracks
+- `show` — Visual timeline overview
+- `add-clip <clip_id> <track> [in] [out] [--at time]` — Place imported clip on track
+- `clips <track>` — List clips on a track
+- `remove-clip <track> <clip>` — Remove a clip
+- `trim <track> <clip> [--in tc] [--out tc]` — Trim clip
+- `split <track> <clip> <at>` — Split clip at timecode
+
+**Filters:**
+- `list-filters [video|audio]` — Browse available filters
+- `filter-info <name>` — Show filter details
+- `add-filter <name> [--track n] [--clip n] [key=val ...]` — Add filter to clip, track, or global
+- `filters [--track n] [--clip n]` — List active filters
+- `remove-filter <idx> [--track n] [--clip n]` — Remove filter by index
+- `set-filter <idx> <param> <value> [--track n] [--clip n]` — Set filter parameter
+- `volume-envelope [--track n] [--clip n] TIME=LEVEL ...` — Keyframed volume (e.g., `00:00:00.000=1.0 00:00:03.000=0.35`)
+- `duck [--track n] [--clip n] START..END ...` — Ducking envelope (e.g., `00:00:06.000..00:00:09.000`)
+
+**Export:**
+- `presets` — List export presets
+- `render <output> [--preset name]` — Render to video file
+
## Command Groups
diff --git a/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py b/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py
index 4e005e7ba..ce2c2cb7b 100644
--- a/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py
+++ b/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py
@@ -545,6 +545,38 @@ class TestTimeline:
at_time="00:00:02.000",
)
+ def test_add_clip_at_boundary_between_clips(self, session_with_track, dummy_file):
+ clip_id = media_mod.import_media(session_with_track, dummy_file)["clip_id"]
+ tl_mod.add_clip(session_with_track, clip_id, 1,
+ in_point="00:00:00.000", out_point="00:00:01.000")
+ tl_mod.add_clip(session_with_track, clip_id, 1,
+ in_point="00:00:00.000", out_point="00:00:01.000",
+ at_time="00:00:01.000")
+ tl_mod.add_clip(session_with_track, clip_id, 1,
+ in_point="00:00:00.000", out_point="00:00:01.000",
+ at_time="00:00:01.000")
+ clips = tl_mod.list_clips(session_with_track, 1)
+ real = [c for c in clips if c.get("clip_index") is not None]
+ assert len(real) == 3
+ playlist = session_with_track._track_playlists[1]
+ children = list(playlist)
+ entry_producers = [c.get("producer") for c in children if c.tag == "entry"]
+ assert entry_producers == ["tl_clip0", "tl_clip0", "tl_clip0"]
+
+ def test_add_clip_at_after_two_clips(self, session_with_track, dummy_file):
+ clip_id = media_mod.import_media(session_with_track, dummy_file)["clip_id"]
+ tl_mod.add_clip(session_with_track, clip_id, 1,
+ in_point="00:00:00.000", out_point="00:00:01.000")
+ tl_mod.add_clip(session_with_track, clip_id, 1,
+ in_point="00:00:00.000", out_point="00:00:01.000",
+ at_time="00:00:01.000")
+ tl_mod.add_clip(session_with_track, clip_id, 1,
+ in_point="00:00:00.000", out_point="00:00:01.000",
+ at_time="00:00:02.000")
+ clips = tl_mod.list_clips(session_with_track, 1)
+ real = [c for c in clips if c.get("clip_index") is not None]
+ assert len(real) == 3
+
def test_undo_add_track(self, session):
initial = len(tl_mod.list_tracks(session))
tl_mod.add_track(session, "video")
diff --git a/skills/cli-anything-shotcut/SKILL.md b/skills/cli-anything-shotcut/SKILL.md
index 87211cf4d..74f20ed60 100644
--- a/skills/cli-anything-shotcut/SKILL.md
+++ b/skills/cli-anything-shotcut/SKILL.md
@@ -18,7 +18,9 @@ pip install cli-anything-shotcut
**Prerequisites:**
- Python 3.10+
-- shotcut must be installed on your system
+- `melt` (MLT CLI) — required for rendering and playback
+- `ffmpeg` / `ffprobe` — required for media probing
+- `shotcut` must be installed on your system
## Usage
@@ -41,13 +43,56 @@ cli-anything-shotcut --json project info -p project.json
### REPL Mode
-When invoked without a subcommand, the CLI enters an interactive REPL session:
+When invoked without a subcommand, the CLI enters an interactive REPL session with undo/redo support:
```bash
cli-anything-shotcut
-# Enter commands interactively with tab-completion and history
+# or with a project:
+cli-anything-shotcut --project my_project.mlt
```
+#### REPL Commands
+
+**Workflow:** Always `media import` first to get a `clip_id`, then use `add-clip` to place it on the timeline.
+
+**Project & Session:**
+- `new [profile]` — Create new project (default: `hd1080p30`)
+- `open <path>` — Open `.mlt` file
+- `save [path]` — Save project
+- `info` — Show project info
+- `xml` — Print raw MLT XML
+- `status` — Show session status
+- `undo` / `redo` — Navigate operation history
+
+**Media (two-step model):**
+- `media import <file> [--caption name]` — Import file into project bin, returns `clip_id` (e.g., `clip0`)
+- `media` — List all imported media
+- `probe <file>` — Analyze a media file
+
+**Timeline:**
+- `add-track <video|audio> [name]` — Add a track
+- `tracks` — List all tracks
+- `show` — Visual timeline overview
+- `add-clip <clip_id> <track> [in] [out] [--at time]` — Place imported clip on track
+- `clips <track>` — List clips on a track
+- `remove-clip <track> <clip>` — Remove a clip
+- `trim <track> <clip> [--in tc] [--out tc]` — Trim clip
+- `split <track> <clip> <at>` — Split clip at timecode
+
+**Filters:**
+- `list-filters [video|audio]` — Browse available filters
+- `filter-info <name>` — Show filter details
+- `add-filter <name> [--track n] [--clip n] [key=val ...]` — Add filter to clip, track, or global
+- `filters [--track n] [--clip n]` — List active filters
+- `remove-filter <idx> [--track n] [--clip n]` — Remove filter by index
+- `set-filter <idx> <param> <value> [--track n] [--clip n]` — Set filter parameter
+- `volume-envelope [--track n] [--clip n] TIME=LEVEL ...` — Keyframed volume (e.g., `00:00:00.000=1.0 00:00:03.000=0.35`)
+- `duck [--track n] [--clip n] START..END ...` — Ducking envelope (e.g., `00:00:06.000..00:00:09.000`)
+
+**Export:**
+- `presets` — List export presets
+- `render <output> [--preset name]` — Render to video file
+
## Command Groups