CLI-Anything/kdenlive/agent-harness/KDENLIVE.md

Kdenlive CLI - Standard Operating Procedure

Overview

The Kdenlive CLI harness provides a stateful command-line interface for non-linear video editing. It manipulates project state in JSON format and generates valid Kdenlive/MLT XML for rendering.

Setup

cd /root/cli-anything/kdenlive/agent-harness
pip install click

No Kdenlive or melt installation is required for project editing and XML generation.

Core Workflow

1. Create a Project

python3 -m cli.kdenlive_cli project new --name "MyProject" --profile hd1080p30 -o project.json

Available profiles: hd1080p30, hd1080p25, hd1080p24, hd1080p60, hd720p30, hd720p25, hd720p60, 4k30, 4k60, sd_ntsc, sd_pal

2. Import Media

python3 -m cli.kdenlive_cli --project project.json bin import /path/to/video.mp4 --name "Main" -d 120.0
python3 -m cli.kdenlive_cli --project project.json bin import /path/to/audio.wav --name "Music" -d 180.0 --type audio

Clip types: video, audio, image, color, title

3. Build Timeline

# Add tracks
python3 -m cli.kdenlive_cli --project project.json timeline add-track --type video
python3 -m cli.kdenlive_cli --project project.json timeline add-track --type audio

# Place clips
python3 -m cli.kdenlive_cli --project project.json timeline add-clip 0 clip0 --position 0 --out 30.0

# Trim, split, move
python3 -m cli.kdenlive_cli --project project.json timeline trim 0 0 --in 5.0 --out 25.0
python3 -m cli.kdenlive_cli --project project.json timeline split 0 0 10.0
python3 -m cli.kdenlive_cli --project project.json timeline move 0 0 5.0

4. Apply Effects

# Available: brightness, contrast, saturation, blur, fade_in_video, fade_out_video,
# fade_in_audio, fade_out_audio, volume, crop, rotate, speed, chroma_key
python3 -m cli.kdenlive_cli --project project.json filter add 0 0 brightness -p level=1.3
python3 -m cli.kdenlive_cli --project project.json filter add 0 0 blur -p hblur=5 -p vblur=5

5. Add Transitions

# Available: dissolve, wipe, slide, composite, affine
python3 -m cli.kdenlive_cli --project project.json transition add dissolve 0 1 -p 5.0 -d 2.0

6. Add Guides

python3 -m cli.kdenlive_cli --project project.json guide add 30.0 --label "Scene 2"

7. Export

# Generate MLT XML for Kdenlive
python3 -m cli.kdenlive_cli --project project.json export xml -o output.kdenlive

# Open in Kdenlive (if installed)
kdenlive output.kdenlive

Session Management

The CLI supports undo/redo for all mutations:

python3 -m cli.kdenlive_cli --project project.json session undo
python3 -m cli.kdenlive_cli --project project.json session redo
python3 -m cli.kdenlive_cli --project project.json session history
python3 -m cli.kdenlive_cli --project project.json session status

JSON Output

All commands support --json flag for machine-readable output:

python3 -m cli.kdenlive_cli --json --project project.json bin list
python3 -m cli.kdenlive_cli --json --project project.json timeline list

Interactive REPL

python3 -m cli.kdenlive_cli repl --project project.json

Testing

cd /root/cli-anything/kdenlive/agent-harness

# Run all tests
python3 -m pytest cli/tests/ -v

# Unit tests (60+ tests)
python3 -m pytest cli/tests/test_core.py -v

# E2E tests (40+ tests)
python3 -m pytest cli/tests/test_full_e2e.py -v

Architecture

• JSON project format: All state is stored as JSON, easily inspectable and diffable
• MLT XML export: Generates valid MLT XML with Kdenlive metadata
• No binary dependencies: Only Python stdlib + click required
• Undo/redo: Full session history with deep-copy snapshots
• Timecode support: Accepts both seconds (float) and HH:MM:SS.mmm format

Key Files

cli/kdenlive_cli.py       - Main CLI entry point
cli/core/project.py       - Project management
cli/core/bin.py           - Media bin
cli/core/timeline.py      - Timeline tracks and clips
cli/core/filters.py       - Filter/effect registry
cli/core/transitions.py   - Transition management
cli/core/guides.py        - Guide/marker management
cli/core/export.py        - XML generation
cli/core/session.py       - Session undo/redo
cli/utils/mlt_xml.py      - MLT XML helpers