editor

MakeMyClip Editor — Agent 技能

通过聊天操控本地视频编辑器。触发后，此技能会通过 npx 调用 clip CLI（首次使用时自动下载，之后会缓存）。无需配置 MCP，无需全局安装，也无需修改配置。

何时调用

当用户要求以下操作时，触发此技能：

• 编辑、修剪、剪切或拼接视频文件
• 缩放、平移或对视频片段的某一区域应用 Ken Burns 效果
• 为视频素材添加字幕、标题或下三分之一字幕条
• 将多个视频片段合并成一个（串接、蒙太奇）
• 将屏幕录制渲染为演示视频或社交媒体短片

以下情况不要调用：纯转录（使用语音转文本技能）、仅处理缩略图图像，或直播。

使用方法

探测媒体文件（已实现）

npx -y @makemyclip/editor ingest <input>

以 JSON 格式返回元数据，包括时长、视频流（编解码器、尺寸、fps）、音频流（编解码器、采样率、声道），以及根据绝对路径确定性生成的 mediaId：

{
  "mediaId": "m_a1b2c3d4e5f6",
  "ref": {
    "path": "/abs/path/screen.mp4",
    "durationSec": 83.5,
    "video": { "codec": "h264", "width": 1920, "height": 1080, "fps": 30 },
    "audio": { "codec": "aac", "sampleRate": 48000, "channels": "stereo" }
  }
}

首先调用此工具，了解源文件的实际内容，以便据此计算修剪时长、确定缩放／叠加层的位置，以及在建议使用 add_audio 前确认是否存在音频。相同的输入路径始终会返回相同的 mediaId。

在指定位置拆分视频片段（已实现）

npx -y @makemyclip/editor split <input> <atSec>

在 atSec 处将视频片段分成两部分。使用流复制（不重新编码），因此速度很快，且会并行生成两个部分。返回两个部分的路径：

{ "before": "/var/folders/.../split-before-abc.mp4", "after": "/var/folders/.../split-after-xyz.mp4", "atSec": 12.5, "durationMs": 38 }

拆分精确到关键帧（并非精确到帧），因为流复制无法在 GOP 中间解码并剪切。如果需要精确到帧地拆分，请先运行 render 重新编码，再运行 split。

修剪视频片段（已实现）

npx -y @makemyclip/editor trim <input> <start> <end>

时间码支持 HH:MM:SS[.ms]、MM:SS，或以数字表示的秒数。输出为 JSON：

{ "path": "/var/folders/.../makemyclip-editor/trim-abc123.mp4", "durationMs": 14 }

修剪使用流复制（不重新编码），因此速度快且无损。输出保存在 $MAKEMYCLIP_WORKSPACE 中（默认路径为 os.tmpdir()/makemyclip-editor）。

添加文本叠加层（已实现）

npx -y @makemyclip/editor add_text <input> <text> <position> <startSec> <endSec>

将文本叠加层烧录到视频副本中。

• <position> 可选值：top-left、top-center、top-right、center-left、center、center-right、bottom-left、bottom-center、bottom-right
• <startSec> / <endSec> 表示从输入文件起始处算起的秒数
• 默认设置：字体大小为 48，白色文字，并带有半透明黑色背景框以提高可读性

返回 JSON：

{ "path": "/var/folders/.../makemyclip-editor/add-text-abc123.mp4", "durationMs": 412 }

文本会先写入临时文件，再传给 ffmpeg，因此引号、冒号、逗号、方括号和大多数 Unicode 字符都无需手动转义即可正常使用。注意：文本中的字面量 %{...} 会被解释为 drawtext 表达式（真实字幕中很少遇到；请避免使用）。

拼接视频片段（已实现）

npx -y @makemyclip/editor concat <input1> <input2> [<input3> ...]

将两个或多个视频片段首尾相接，合并为一个输出文件；使用流复制（不重新编码），因此速度快且无损。

返回 JSON：

{ "path": "/var/folders/.../makemyclip-editor/concat-abc123.mp4", "durationMs": 95, "inputCount": 3 }

所有输入的编解码器和分辨率必须一致；如果不一致，ffmpeg 会返回清晰的错误信息，Agent 应先重新编码（例如通过不产生实际变化的文本调用 add_text，或使用未来的 render 调用），再进行拼接。组合使用 trim → concat 是制作精彩集锦的常用工作流：先修剪 N 个片段，再按顺序拼接。

提取预览帧（已实现）

npx -y @makemyclip/editor preview <input> <atSec>

在指定时间码处提取单帧 JPEG。每次执行编辑操作后，都应使用此工具验证输出，再继续下一步——确认文本叠加层位于预期位置、修剪点正确，以及拼接处衔接顺畅。返回 JSON：

{ "path": "/var/folders/.../makemyclip-editor/preview-abc123.jpg", "atSec": 1.5, "durationMs": 12 }

速度很快（约 10–50 ms），因为它使用 ffmpeg 的输入定位（在 -i 前使用 -ss）——精确到关键帧，而非精确到帧，这对缩略图来说已足够。用户可以打开 JPEG 进行确认；支持图像输入的 Agent 也可以读取图像并自行修正。

两个片段之间的转场（已实现）

npx -y @makemyclip/editor transition <inputA> <inputB> [<kind>] [<durationSec>]

在两个片段之间添加交叉淡化、滑动转场，或淡入黑场／白场。工具会自动探测片段 A，以计算正确的偏移量，因此 Agent 无需知道片段时长。

• <kind> 可选值包括：fade、fadeblack、fadewhite、dissolve、wipeleft、wiperight、wipeup、wipedown、slideleft、slideright、circleopen、circleclose。默认为 fade（最稳妥、最不显眼）。
• <durationSec> 默认为 1，最长为 10 秒。

返回 JSON：

{ "path": "/var/folders/.../makemyclip-editor/transition-abc.mp4", "durationMs": 320, "offsetSec": 4, "hasAudio": true }

音频：如果两个输入都有音频，工具会连接相同持续时间的 acrossfade。如果两者都没有音频，输出将静音。如果恰好只有一个有音频，工具会失败并给出明确提示——请先为无声片段重新编码并添加静音音轨。

结合 concat 和 add_text，这是让多片段输出显得连贯而非突兀的润色步骤。

重新编码以导出或规范化（已实现）

npx -y @makemyclip/editor render <input> [<format>] [<crf>] [<preset>] [<maxWidth>]

将视频重新编码为指定格式和质量。适用于最终导出、在 concat／transition 前统一编解码器不匹配的输入，或缩小尺寸以便在 Web 上交付。

• <format> 可选值包括：mp4（默认，h264+aac）、mov（h264+aac）、webm（vp9+opus）
• <crf> 是质量参数（0 = 无损，51 = 最差）。默认值 23 是不错的基准；数值越低，质量越高
• <preset> 控制 libx264 的速度／效率权衡：ultrafast … veryslow。默认为 medium。对 webm 无效
• <maxWidth>（可选）限制宽度（像素）。保持宽高比；不会放大

返回 JSON：

{ "path": "/var/folders/.../makemyclip-editor/render-abc.mp4", "format": "mp4", "durationMs": 412 }

添加音频——混音或替换（已实现）

npx -y @makemyclip/editor add_audio <input> <audio> [<mode>] [<audioVolume>] [<startSec>]

添加背景音乐、旁白，或完全替换原始音频。

• <mode> 可选值为 mix（默认——保留基础音频并叠加新音频）或 replace（丢弃基础音频，仅使用新音频）
• <audioVolume> 是叠加音量倍数（0–2，默认 0.5——合适的背景音乐音量；旁白请使用 1.0）
• <startSec> 是叠加音频的开始时间（默认为 0）

返回 JSON：

{ "path": "/var/folders/.../makemyclip-editor/add-audio-abc.mp4", "mode": "mix", "durationMs": 412 }

混音模式要求输入视频包含音轨（请先使用 ingest 确认）。输出时长与原始视频一致——叠加音频较长时会被截断，较短时会以静音补齐。

裁剪／旋转／翻转／缩放（已实现）

npx -y @makemyclip/editor transform crop   <input> <x> <y> <width> <height>
npx -y @makemyclip/editor transform rotate <input> <90|180|270>
npx -y @makemyclip/editor transform flip   <input> <horizontal|vertical>
npx -y @makemyclip/editor transform scale  <input> [<width>] [<height>]

对单个视频执行几何变换。transform scale 使用 -2 表示省略某个维度（自动适配并保持宽高比，同时满足 H.264 的偶数像素要求）。旋转仅支持 90° 的整数倍——如需任意角度，请使用带自定义滤镜图的 render。

调整颜色／亮度／对比度／饱和度／音量（已实现）

npx -y @makemyclip/editor adjust <input> --brightness N --contrast N --saturation N --volume N

统一调节面板。可设置任意一组参数，但至少需要设置一项。

参数	范围	无操作值
--brightness	-1（黑）… 1（白）	0
--contrast	0 … 4	1
--saturation	0（灰度）… 3（鲜艳）	1
--volume	0（静音）… 2（两倍）	1

对未调整的流使用流复制（例如，仅设置 --volume 时，视频流会被复制，速度很快）。

加速／减速／倒放（已实现）

npx -y @makemyclip/editor speed <input> [<factor>] [<reverse>]

倍速含义：factor=2 表示两倍速，factor=0.5 表示半速（慢动作）。reverse=true 表示倒放（音频也会倒放）。必须设置 factor != 1 或 reverse=true（不接受无操作请求）。

音频处理使用 atempo，其范围限制为 [0.5, 2.0]；对于超出范围的倍数，工具会在内部串联多个 atempo 环节，因此 factor=4 和 factor=0.125 均可正常工作。

画中画／图像叠加（已实现）

npx -y @makemyclip/editor overlay <base> <overlay> [<position>] [<scaleToWidth>] [<startSec>] [<endSec>]

将视频或图像叠加在基础视频上。支持与 add_text 相同的 9 个命名位置。可选使用 scaleToWidth 先调整叠加内容的尺寸（高度会自动适配为偶数像素）。可选设置时间范围 startSec + endSec，或仅设置 startSec，表示“从此时刻开始直到结束”。

肯·伯恩斯效果／焦点缩放（已实现）

npx -y @makemyclip/editor zoom_pan <input> [<fromZoom>] [<toZoom>] [<centerX>] [<centerY>]

在整个片段时长内，从 fromZoom 平滑缩放到 toZoom，中心位于归一化 [0, 1] 坐标中的 (centerX, centerY)。默认值：fromZoom=1、toZoom=1.5，中心为 (0.5, 0.5)。缩小时使用 fromZoom > toZoom。工具会探测输入，以匹配输出分辨率和帧率。

添加标题卡（已实现）

npx -y @makemyclip/editor add_title_card <input> <text> [<durationSec>] [<background>] [<fontSize>] [<fontColor>]

生成一张全屏彩色卡片（默认时长 2 s、黑色背景、白色文字），居中显示标题，然后将其拼接到输入视频之前。自动探测输入，以匹配尺寸、帧率和音频采样率，确保无缝衔接。

一次调用添加多个字幕（已实现）

npx -y @makemyclip/editor add_captions <input> <cuesJson>

cuesJson 是一个由 { text, startSec, endSec, position? } 组成的 JSON 数组。会循环调用 add_text 处理每条字幕。不会转录——由 Agent（或用户）提供字幕内容。组合优于耦合：需要时，可将此工具与单独的转录步骤搭配使用。

移除静音（已实现）

npx -y @makemyclip/editor silence_remove <input> [<noiseDb>] [<minSilenceSec>]

通过 ffmpeg 的 silencedetect 滤镜检测静音片段，然后裁剪出非静音片段并将其拼接起来。默认值：noiseDb=-30、minSilenceSec=0.5。纯 FFmpeg 实现，不依赖 Python auto-editor。

制作精彩集锦（已实现）

npx -y @makemyclip/editor highlight_reel <input> <segmentsJson> [<transitionKind>] [<transitionSec>]

segmentsJson 是一个由 { startSec, endSec } 组成的 JSON 数组。并行裁剪每个片段（流复制，速度快），然后直接拼接（未指定 transitionKind）或逐对调用转场工具，在片段之间进行交叉淡化。将经典的“从长视频中剪出精彩时刻”工作流封装为一个可由 Agent 调用的工具。

绿幕／色度键抠像（已实现）

npx -y @makemyclip/editor chroma_key <foreground> <background> [<color>] [<similarity>] [<blend>]

从前景视频中移除一种颜色，并将其合成到背景上。背景可以是视频或静态图像（自动检测，并循环播放以匹配前景时长）。

• <color> 默认值为 green。支持颜色名称、#RRGGBB 或 0xRRGGBB
• <similarity>（0..1，默认值为 0.3）——像素与键控颜色的接近程度达到多少时才会被视为该颜色
• <blend>（0..1，默认值为 0.1）——软边缘程度；0 = 硬切，值越大边缘越柔和

默认使用背景音频（即“场景”音频）。如果前景中有人声，可将 preferForegroundAudio=true 以改用前景音频。

稳定抖动的画面（已实现）

npx -y @makemyclip/editor stabilize <input> [<shakiness>] [<smoothing>] [<accuracy>] [<zoom>]

使用两遍 vidstab：第 1 遍（vidstabdetect）分析运动并写入变换文件；第 2 遍（vidstabtransform）扭曲每一帧，使其跟随平滑后的摄像机路径。默认值合理（5、10、9、5）——对于非常不稳定的输入，可增大 shakiness；若想要更具电影感，可增大 smoothing；可调整 zoom 以隐藏扭曲边缘。

需要启用了 vidstab 的 ffmpeg。捆绑的 ffmpeg-static 已包含此功能；否则，工具会显示明确的错误。

构建多片段合成——时间线（已实现）

以上单文件工具都会各自生成一个新的输出文件。若要将多个片段组装成一个剪辑（包含非破坏性修剪、转场和撤销／重做），请使用时间线：它是一份作为剪辑组装版真实来源的合成文档。CLI、浏览器界面和此技能都会修改同一份文档。

npx -y @makemyclip/editor timeline new                       # start an empty composition
npx -y @makemyclip/editor timeline add-media intro.mp4       # ingest + append a clip
npx -y @makemyclip/editor timeline add-media demo.mp4
npx -y @makemyclip/editor timeline transition <afterClipId> fade 0.5
npx -y @makemyclip/editor timeline show                      # read tracks, clips, timings
npx -y @makemyclip/editor timeline export final.mp4          # compile the document to a render

只要用户是在组装视频（多个片段、转场、最终渲染），就优先使用时间线，而不是串联单文件工具：编辑是非破坏性的且可撤销（timeline undo / redo、timeline log），timeline at <sec> / timeline frame <sec> 则可在更改前只读查看当前文档。运行 npx -y @makemyclip/editor timeline --help，查看完整子命令列表。

打开本地 UI（已实现）

npx -y @makemyclip/editor ui

启动一个位于 http://127.0.0.1:5573 的小型本地服务，并打开浏览器。该 UI 会呈现会话日志（Agent 运行过的每项操作），显示结果路径和时间戳，并允许用户点击某项操作来播放其输出。它是聊天驱动工作流的实用配套工具——用户可以实时查看会话进展，无需操作终端即可检查输出。

仅限本地使用。该 UI 是一个深色时间线编辑器：支持拖放导入、监视器（播放头所在位置的合成画面）、可编辑时间线（选择片段后可修剪／拆分／移动／添加转场／移除）、一键导出、时间线撤销／重做和快照——因此，Agent 偏离脚本时，用户可以随时接管并进行可视化操作。

会话安全——快照、撤销、检查、删除（已实现）

每次成功的工具调用都会记录到 $MAKEMYCLIP_WORKSPACE/session.json。Agent 可以检查日志、为当前状态创建快照、撤销操作或移除单项操作。

npx -y @makemyclip/editor snapshot [<label>]            # Save the current session as <label>.json (default: snap-<N>)
npx -y @makemyclip/editor undo [<snapshotLabel>]        # Pop the last op, OR restore a named snapshot
npx -y @makemyclip/editor inspect [<limit>]             # Show recent ops with one-line summaries
npx -y @makemyclip/editor delete <id> [<removeFile>]    # Remove an op (and optionally unlink its output file)

这些就是委员会指出的必备恢复流程。进行任何不确定的编辑前先创建快照；如果结果不理想就撤销；检查日志以记住已执行的操作。

安全

• FFmpeg 以参数数组的形式启动——不会进行 shell 插值，也不会发生注入。
• 默认情况下，所有文件路径都会基于工作区目录解析。
• 除了通过 npx 一次性下载软件包本身之外，该技能不会进行网络调用。

安装

npx skills add MakeMyClip/editor

就这样。

许可证

MIT。请参阅 LICENSE。