cli-anything-kdenlive 实战基于 JSON 项目模型与 MLT XML 生成的有状态 Kdenlive 命令行剪辑工具【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本篇文章围绕 CLI-Anything 仓库中cli-anything-kdenlive技能文档展开讲解如何通过命令行完成 Kdenlive 工程全流程操作从创建工程、导入素材、搭建时间线、叠加滤镜与转场到最终导出可被 Kdenlive 与melt直接消费的 MLT XML。读者读完将掌握cli-anything-kdenlive的完整命令体系、JSON 工程文件结构与状态管理机制并能像操作 GUI 一样用脚本化、可回滚、面向 Agent 的方式驱动视频剪辑。工具定位有状态的命令行剪辑引擎skills/SKILL.md 开篇即定义了这个工具的本质A stateful command-line interface for video editing, following the same patterns as the Blender CLI harness. Uses a JSON project format with MLT XML generation for Kdenlive/melt.它不是一个简单的一次性封装脚本而是一套有状态stateful的剪辑会话系统内部维护一份 JSON 工程模型bin素材箱、tracks轨道、transitions转场、guides标记并在每次修改前对工程打快照从而提供最多 50 层的撤销/重做能力最后通过export xml将 JSON 模型序列化为带 Kdenlive 元数据的MLT XML文档实现JSON 可读、XML 可播、Kdenlive 可编辑三态互通。在仓库中的实际目录结构为kdenlive/agent-harness/cli_anything/kdenlive/ ├── kdenlive_cli.py # Click 入口 REPL 主循环 ├── __main__.py # python -m 模块入口 ├── core/ │ ├── project.py # 工程 create/open/save/info/profiles │ ├── bin.py # 素材箱管理 │ ├── timeline.py # 轨道与片段摆放 │ ├── filters.py # 滤镜注册表与参数校验 │ ├── transitions.py # 转场管理 │ ├── guides.py # 标记管理 │ ├── export.py # XML 生成与渲染预设 │ └── session.py # 带 undo/redo 的会话 ├── utils/ │ ├── mlt_xml.py # MLT XML 构建、时间码换算 │ └── repl_skin.py # REPL 交互皮肤提示符/补全/帮助 ├── skills/SKILL.md # Agent 技能描述 └── tests/ ├── TEST.md ├── test_core.py # 118 个单元测试 └── test_full_e2e.py # 33 个端到端测试入口实现见 kdenlive_cli.py各功能模块在core/下按领域拆分utils/mlt_xml.py提供 MLT XML 构建器与时间码工具结构清晰、可独立测试。安装与前置条件依据 SKILL.md 的安装说明该 CLI 随cli-anything-kdenlive包一同安装pip install cli-anything-kdenlive前置条件Python 3.10系统需要安装Kdenlive若要在 Kdenlive 中打开生成的工程仅做 JSON 工程编辑与校验则不需要 Kdenlive/melt需要特别说明的是工程编辑本身不依赖 Kdenlive 运行时这在包内 README.md 中有明确提示——No Kdenlive or melt installation required for project editing. Kdenlive is only needed to open the generated .kdenlive XML files. 也就是说素材的组织、时间线的排版、滤镜/转场/标记的配置全部可以在无 GUI 环境下完成只有最后把导出的.kdenliveXML 交给 Kdenlive 或melt渲染时才需要相应软件。在源码目录内直接开发运行的方式来自 README 的 Quick Start 模式pip install click python3 -m cli_anything.kdenlive.kdenlive_cli project new --name MyVideo --profile hd1080p30 -o project.json基础命令一览# 查看帮助 cli-anything-kdenlive --help # 进入交互式 REPL 模式 cli-anything-kdenlive # 新建工程 cli-anything-kdenlive project new -o project.json # 以 JSON 输出工程信息供 Agent 程序消费 cli-anything-kdenlive --json project info -p project.jsonCLI 全局参数见 kdenlive_cli.py 的 Click 定义全局选项含义--json所有输出切换为结构化 JSON--project path指定.kdenlive-cli.json工程文件一次性命令自动加载--dry-run只执行不落盘配合--project使用当--project缺省且未调用子命令时CLI 自动进入 REPL一次性命令执行完毕若工程有改动且未指定--dry-runresult_callbackauto_save_on_exit会将其自动写回磁盘。REPL 交互模式SKILL.md 说明不带子命令直接启动即进入交互式 REPL 会话cli-anything-kdenlive # 进入命令交互支持 tab 补全与历史记录实现上REPL 主循环位于 kdenlive_cli.py 的repl()命令基于ReplSkin见 utils/repl_skin.py构造交互体验启动打印版本 banner输入行通过shlex.split拆分为参数后复用同一个 Click 命令树执行因此 REPL 内可用的命令与一次性命令行完全一致。REPL 内的关键交互能力输入help查看所有命令组的速查帮助输入undo/redo进行历史导航有状态会话的核心能力输入quit/exit/q退出提示符会显示当前工程名与未保存修改状态*标记。启动时也可直接挂载已有工程cli-anything-kdenlive repl --project project.json命令组全解SKILL.md 将全部功能划分为 8 个命令组。以下逐组展开命令参数细节以源码为准。Project工程管理命令说明new创建新工程open打开已有工程文件save保存当前工程info显示工程信息profiles列出可用视频 Profilejson打印原始工程 JSONproject new支持参数--name/-n默认untitled、--profile/-p命名 profile、--width/--height、--fps-num/--fps-den、--output/-o。核心校验逻辑位于 core/project.py若指定了命名 profile 则整体覆盖分辨率/帧率/宽高比参数宽度、高度、FPS 分子分母必须为正数否则抛ValueError。project info的统计输出来自get_project_info()core/project.py返回 profile 摘要分辨率、fps、逐行/隔行、宽高比以及各对象计数bin_clips、tracks、clips_on_timeline、transitions、guides方便 Agent 快速核对工程规模。Bin素材箱命令说明import导入素材到素材箱remove从素材箱移除素材list列出素材箱全部素材get获取素材详细信息# 导入视频与音频素材 cli-anything-kdenlive --project project.json bin import /path/to/video.mp4 --name Interview -d 120.5 cli-anything-kdenlive --project project.json bin import /path/to/music.mp3 --name BGM -d 180.0 --type audiobin import参数source必填路径、--name/-n、--duration/-d秒、--typevideo|audio|image|color|title默认video。素材被分配全局唯一的id如clip0、clip1时间线片段通过该 id 引用素材与真实 NLE 的 bin/时间线引用关系一致。Timeline时间线命令说明add-track添加轨道remove-track移除轨道add-clip将素材放到轨道remove-clip从轨道移除片段trim调整片段入/出点split在指定时间点分割片段move移动片段到新位置list列出全部轨道cli-anything-kdenlive --project project.json timeline add-track --type video cli-anything-kdenlive --project project.json timeline add-track --type audio cli-anything-kdenlive --project project.json timeline add-clip 0 clip0 --position 0 --out 30.0参数语义见 core/timeline.py 与入口命令add-track--name、--type video|audio默认 video、--mute/--hide/--locked未命名时自动生成V1/V2…或A1/A2…序号名timeline.pyadd-cliptrack_id整数、clip_idbin 内 id、--position/-p放置位置秒、--in素材内入点、--out出点缺省时按素材时长推算向locked轨道添加会抛错trim--in/--out修改片段在素材内的使用区间split在split_at相对片段的秒偏移处一分为二move把片段移到new_position秒——实现层会保证同轨片段按位置排序。Filter滤镜/效果命令说明add给轨道上的片段添加滤镜remove移除滤镜set设置滤镜参数list列出片段上的滤镜available列出全部可用滤镜# 给轨道0第0个片段加亮度滤镜并设置 level1.3 cli-anything-kdenlive --project project.json filter add 0 0 brightness -p level1.3filter add的位置参数是track_id与clip_index片段在轨道内的序号非 bin id--param/-p可多次传入keyvalue入口会按含小数点→float否则→int失败→str做类型推断见 kdenlive_cli.py 的filter_add。参数在底层还会经过_validate_filter_params的二次校验未知参数名直接报错数值类型会检查上下限范围core/filters.py。Transition转场命令说明add在轨道间添加转场remove移除转场set设置转场参数list列出全部转场cli-anything-kdenlive --project project.json transition add dissolve 0 1 -d 2.0transition add位置参数依次为transition_type、track_a、track_b选项--position/-p默认 0.0 秒、--duration/-d默认 1.0 秒、--paramkeyvalue可重复。由 core/transitions.py 定义的内置转场注册表类型MLT service可调参数dissolvelumaduration(0.01–60s)、softness(0–1)wipelumaduration、resource(擦除图案)、softnessslideaffineduration、direction(如left)compositecompositefill(0/1)、aligned(0/1)affineaffinedistort(0/1)约束上同一轨道的自转场会被拒绝无效轨道索引也会报错。Guide标记命令说明add在指定位置秒添加标记remove移除标记list列出全部标记cli-anything-kdenlive --project project.json guide add 30.0 --label Scene 2guide add支持--label/-l、--typedefault|chapter|segment默认default与--comment/-c可作为章节点或分镜标记。Guide 在导出 XML 时会写入序列的kdenlive:sequenceproperties.guides属性JSON 数组含pos/comment/type。Export导出命令说明xml生成 Kdenlive/MLT XMLpresets列出可用渲染预设cli-anything-kdenlive --project project.json export xml -o output.kdenlive注意SKILL.md 的 Examples 一节保留了一条cli-anything-kdenlive --project myproject.json export render output.pdf --overwrite的示意命令从当前源码的命令注册表看实际落地实现的是export xml与export presets两个子命令见 kdenlive_cli.py 的 export 组因此自动化脚本请以export xml作为导出入口并将输出文件交给 Kdenlive/melt处理渲染。Session会话命令说明status显示会话状态undo撤销上一次操作redo重做被撤销的操作history显示撤销历史状态管理快照式撤销/重做与会话持久化SKILL.md 明确本工具维护三种状态能力Undo/Redo最多50 层历史Project persistence工程以 JSON 保存/加载Session tracking跟踪修改状态。源码层面由 core/session.py 的Session类实现关键机制如下快照时机每次会变更工程的命令导入、建轨、放片段、修剪、分割、滤镜、转场、标记等在执行前都会调用sess.snapshot(description)将当前工程deepcopy压入_undo_stacksession.py容量上限Session.MAX_UNDO 50超出时弹出最旧的快照先进先出执行新操作会清空 redo 栈撤销/重做undo()把当前工程压入 redo 栈再从 undo 栈弹出恢复redo()反向操作session.py修改跟踪status()返回modified、undo_count、redo_count、project_path等Agent 可在长时间会话前查询是否有未保存修改持久化save_session()通过_locked_save_json使用fcntl文件锁进行原子写入不可用时优雅降级避免多进程并发写坏工程文件session.py。JSON 工程模型一切状态的中枢SKILL.md 反复强调JSON project format工程文件是整条链路的枢纽。一个典型工程的 JSON 结构如下来自包内 README 的完整示例{ version: 1.0, name: my_video, profile: { name: hd1080p30, width: 1920, height: 1080, fps_num: 30, fps_den: 1, progressive: true, dar_num: 16, dar_den: 9 }, bin: [ {id: clip0, name: Interview, source: /path/to/video.mp4, duration: 120.5, type: video} ], tracks: [ {id: 0, name: V1, type: video, mute: false, hide: false, locked: false, clips: [ {clip_id: clip0, in: 0.0, out: 30.0, position: 0.0, filters: []} ]} ], transitions: [], guides: [], metadata: {} }各字段语义与代码实现一一对应core/project.py字段含义备注version工程格式版本固定1.0open_project校验必需name工程名project new --nameprofile工程 Profile含name/width/height/fps_num/fps_den/progressive/dar_num/dar_denbin[]素材箱素材全局唯一时间线通过clip_id引用tracks[]时间线轨道轨道自带mute/hide/locked/clipstracks[].clips[]轨道上的片段clip_id/in/out/position/filterstransitions[]转场引用两个轨道 idguides[]标记position/label/typemetadata元数据created/modified/softwareopen_project()只要求version与profile存在即可恢复工程数据往返保存→重新加载在 E2E 测试中保证无损。预置 Profile从 SD 到 4Kproject new的--profile选项来自 core/project.py 的PROFILES注册表。内置 Profile 汇总Profile分辨率帧率扫描方式宽高比hd1080p301920×108030 fps逐行16:9hd1080p251920×108025 fps逐行16:9hd1080p241920×108024 fps逐行16:9hd1080p601920×108060 fps逐行16:9hd720p301280×72030 fps逐行16:9hd720p251280×72025 fps逐行16:9hd720p601280×72060 fps逐行16:94k303840×216030 fps逐行16:94k603840×216060 fps逐行16:9sd_ntsc720×48030000/1001 fps隔行4:3sd_pal720×57625 fps隔行4:3注意 NTSC 的帧率用分数fps_num/fps_den 30000/1001表达避免小数误差自定义工程也可绕过 profile直接用--width/--height/--fps-num/--fps-den指定任意参数此时 profile 名记为custom。可用滤镜注册表内置滤镜清单来自 core/filters.py 的FILTER_REGISTRYSKILL.md 未逐个列出这里补全滤镜MLT service主要参数范围分类brightnessbrightnesslevel(0–5, 默认1.0)colorcontrastbrightnesslevel(0–5, 默认1.0)colorsaturationavfilter.eqsaturation(0–3, 默认1.0)colorblurboxblurhblur/vblur(int 0–100, 默认2)effectfade_in_videobrightnessduration(0.01–60s)transitionfade_out_videobrightnessduration(0.01–60s)transitionfade_in_audiovolumeduration(0.01–60s)transitionfade_out_audiovolumeduration(0.01–60s)transitionvolumevolumegain(0–10, 默认1.0)audiocropcropleft/right/top/bottom(int 0–9999)effectrotateaffineangle(-360–360)effectspeedtimewarpspeed(0.01–100, 默认1.0)effectchroma_keyfrei0r.select0rcolor(默认#00ff00)、variance(0–1, 默认0.15)keying几点值得注意的实现细节每个滤镜带mlt_service导出时直接写入 XML 的mlt_service属性部分滤镜如淡入淡出、speed还映射了 Kdenlive 侧的kdenlive_namefade_from_black、fadein、fadeout等保证在 Kdenlive 界面中显示正确语义filter available --category color可按分类过滤参数规格在注册表内声明type/default/min/max_validate_filter_params负责补默认值并拒绝越界值——这意味着传坏参数会被前置拦截而不是等 XML 生成后才失败。MLT XML 生成原理JSON → Kdenlive 文档的桥梁export xml的实现核心位于 utils/mlt_xml.py 的build_mlt_xml()。它基于 Python 标准库xml.etree.ElementTree生成Kdenlive Gen 5文档版本 1.1兼容的 MLT XML具备以下结构要点mlt根元素LC_NUMERICC保证浮点序列化与 locale 无关、version7.0.0、title取工程名、producermain_binprofile写入分辨率、逐行/隔行、sample_aspect_num/den由显示宽高比与分辨率推导、frame_rate_num/den、colorspace709素材链chain每个素材生成一条chain按素材类型映射 MLT service——普通媒体走avformat-novalidate并按audio/image类型设置audio_index/video_index见_set_producer_props与_avformat_indexescolor类走colorservice轨道结构音频轨在前、视频轨在后排序每条轨道生成chain 双 playlist 包裹 tractor的结构轨道间留空以blank填充方便后续 Kdenlive 内二次编辑序列 tractor使用 UUID 标识写入kdenlive:uuid、kdenlive:sequenceproperties.*hasAudio/hasVideo/activeTrack/tracksCount/duration/maxduration/zoom/guides等Kdenlive 私有属性guides 以 JSON 数组序列化到kdenlive:sequenceproperties.guides内部混合转场为音频轨自动附加mix、为视频轨自动附加qtblend内部转场标记internal_added237再追加用户自定义转场luma/affine/composite换算 a_track/b_track 与 in/out 帧区间main_bin playlist最后生成main_bin播放列表写入kdenlive:docproperties.*文档属性并把序列与全部素材入口挂入工程 tractortractor_project作为最后一个元素、标有kdenlive:projectTractor1——这正是melt播放时所消费的顶层输出。导出的 XML 属性对超长文件名/特殊字符做了转义xml_escape会处理 mlt_xml.py。因此生成的产物可安全用于直接在 Kdenlive 打开、交给melt命令行处理、或嵌入更上层的自动化渲染流水线。时间码与帧换算工具JSON 模型里时间均以秒float存储而 MLT 世界以帧为单位。utils/mlt_xml.py提供换算函数作为桥梁seconds_to_timecode(seconds)→HH:MM:SS.mmm字符串负数抛错timecode_to_seconds(tc)→ 秒接受纯数字字符串或HH:MM:SS.mmm含小时位最多两位seconds_to_frames(seconds, fps_num, fps_den)/frames_to_seconds(...)→ 与工程 profile 帧率互转。REPL 与命令行的parse_time也复用了timecode_to_seconds意味着时间参数既可以直接写秒30.0也可以写时间码00:00:30.000。输出格式双通道人类可读 / Agent 可解析SKILL.md 规定所有命令支持双模式输出人类可读默认格式化文本/表格多层 dict 与 list 会被缩进打印机器可读--json输出结构化 JSON供 Agent 直接解析。# 人类输出 cli-anything-kdenlive project info -p project.json # Agent 使用的 JSON 输出 cli-anything-kdenlive --json project info -p project.json实现上入口层维护_json_output全局开关统一的output(data, message)在 JSON 模式下json.dumps(data, indent2, defaultstr)输出完整对象错误处理装饰器handle_error在 JSON 模式下把异常编码为{error: ..., type: file_not_found | file_exists | ...}的结构化错误kdenlive_cli.py。面向 AI Agent 的 5 条操作规范SKILL.md For AI Agents 一节给出了程序化调用时的硬性纪律始终使用--json标志以获得可解析输出检查返回码——0 表示成功非零表示失败解析 stderr获取失败时的错误信息人类模式下错误打到errTrue所有文件操作使用绝对路径导出后验证产物存在export xml成功会回传{path: ..., size: ...}。实战示例串讲示例一新建工程cli-anything-kdenlive project new -o myproject.json # 或输出 JSON 供程序化使用 cli-anything-kdenlive --json project new -o myproject.json示例二一条完整的导素材→排轨→加效果→导出链路# 1) 建工程1080p30 cli-anything-kdenlive --project project.json project new --name MyVideo --profile hd1080p30 -o project.json # 2) 素材进 bin cli-anything-kdenlive --project project.json bin import /path/to/video.mp4 --name Interview -d 120.5 cli-anything-kdenlive --project project.json bin import /path/to/music.mp3 --name BGM -d 180.0 --type audio # 3) 建轨道并摆放片段 cli-anything-kdenlive --project project.json timeline add-track --type video cli-anything-kdenlive --project project.json timeline add-track --type audio cli-anything-kdenlive --project project.json timeline add-clip 0 clip0 --position 0 --out 30.0 cli-anything-kdenlive --project project.json timeline add-clip 1 clip1 --position 0 --out 60.0 # 4) 加滤镜与转场 cli-anything-kdenlive --project project.json filter add 0 0 brightness -p level1.3 cli-anything-kdenlive --project project.json transition add dissolve 0 1 -d 2.0 # 5) 加标记章节点 cli-anything-kdenlive --project project.json guide add 30.0 --label Scene 2 # 6) 导出 MLT XML 并保存工程 cli-anything-kdenlive --project project.json export xml -o output.kdenlive cli-anything-kdenlive --project project.json project save示例三REPL 交互会话cli-anything-kdenlive # 输入 help 查看命令 # 输入 project new --name demo -o demo.json 建工程 # 输入 undo / redo 做历史导航 # 输入 quit 退出测试覆盖与质量基线工程附带了两套测试详见 tests/TEST.mdtests/test_core.py118 个纯内存单元测试覆盖 Project17、Bin12、Timeline18、Filters16、Transitions11、Guides8、TimecodeUtils13、Session12无需安装 Kdenlivetests/test_full_e2e.py33 个 E2E 测试验证 MLT XML 结构与格式TestXMLGeneration 13 个、JSON/XML 格式往返TestFormatValidation 8 个以及多机位、音视频分离、trim/split、滤镜链、转场、undo/redo 等真实剪辑工作流TestWorkflowE2E 18 个。E2E 测试对 XML 的断言根元素mlt、每个 bin 素材生成producer/chain、每条轨道生成playlist、滤镜含mlt_service、特殊字符正确转义、SD PAL profile 得到正确 XML 值等从侧面印证了前述生成逻辑的契约也是自行扩展渲染流水线时的参考蓝本。更多资源技能文档本文依据skills/SKILL.md包内完整 READMEQuick Start / JSON 格式 / MLT XML 说明README.md测试文档与测试源码tests/TEST.md、tests/test_full_e2e.py方法论参考CLI-Anything 插件的 HARNESS.md以及仓库内其他同类 harness如 blender的模式说明总体而言cli-anything-kdenlive把传统 GUI 剪辑的高频操作收敛为一套可编程、可撤销、可 JSON 化的命令原语天然适合接入自动化渲染流水线、批量素材整理与 AI Agent 工具调用场景若你的目标是让模型或脚本在无人值守下完成一次可交付的视频粗剪本工具提供了一条端到端可验证的路径。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
