"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.mdindex 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 exportOptional (for interactive REPL):- `prompt_toolkit`-Optional (for rendering/media probing):-- `ffmpeg` / `ffprobe`-- `melt` (MLT CLI)-## Install Dependencies```bashpip 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 RunAll 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 projectpython3 -m cli.shotcut_cli repl++# Or open an existing projectpython3 -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 narrationpython3 -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 timelinepython3 -m cli.shotcut_cli --project edit.mlt timeline showdiff --git a/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py b/shotcut/agent-harness/cli_anything/shotcut/core/timeline.pyindex 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+ continuereturn len(children), max(0, target - timeline_cursor), 0diff --git a/shotcut/agent-harness/cli_anything/shotcut/skills/SKILL.md b/shotcut/agent-harness/cli_anything/shotcut/skills/SKILL.mdindex 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:```bashcli-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 Groupsdiff --git a/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py b/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.pyindex 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.mdindex 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:```bashcli-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