mk-video-editing

mk-video-editing 是做什么的？

将提供的素材剪辑成可观看、一致的成片：正确的词以正确的顺序排列，能够很好构图拍摄主体的摄像机，一致的画面，干净且电平合适的音频，以及有品位的标题。结构来自素材本身及其中的内容。

技能能做什么

需求	工具	成本	参考
文字转录、填充词/错误起始/停顿检测	edit:transcribe (mlx-whisper)，speech:flow	免费，本地	footage-editing.md
稳定、跟踪拍摄主体、重新构图4K宽幅（推进、推入、平移）、HDR→SDR、去闪烁、色彩匹配、叠化、跳切	edit:analyze，edit:track，EDL + medit (edit:render)	免费，本地	footage-editing.md
对话降噪、混音、闪避、响度	speech:clean (ISOLATE=1 Demucs)，speech:mix，speech:measure	免费，本地	footage-editing.md
旁白解说	voice:tts (ElevenLabs via Fal)	付费，已授权	credentials.md
标题、下方字幕、片尾卡（ProRes 4444 alpha）	mgraphics JSON场景，graphics:render，scripts/tools/graphics/examples/中的模板	免费，本地	graphics README
配乐背景	EDL music (闪避)，music:score (ElevenLabs Music via Fal)，audio:analyze获取节拍时间	仅生成时付费	finishing.md
标题/转场音效	SoundSynth (synth: 呼呼声、上升声、冲击声、滴答声…)，sfx:gen/sfx:mix 或 EDL sounds	免费 (Stable Audio prompt: 付费)	finishing.md
画面特效（闪光、淡出、冲击、辉光、镜头光晕、条纹…）	mvfx 提示表，vfx:stills/vfx:render	免费，本地	finishing.md
交付编码	media:twitter，media:youtube，media:faststart	免费，本地	tasks.md
独立任务上的并行子代理	work:next/work:accept/work:log/work:watch	免费	tasks.md

每个任务及其参数和选项都在 tasks.md 中。测试配置在 testing.md 中。

执行契约

专为 macOS 14+ 上的 Apple Silicon (Swift 5.9+，Ruby 3.2+，Bundler，FFmpeg，ImageMagick，用于本地 Whisper 的 uv) 上的 Claude Code 设计。当任务因缺少工具而失败时，首先运行 doctor；setup 构建 Swift 工具。Ruby 是唯一的执行入口层：运行 ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'task[args]'。任务委托给驱动原生 Swift 工具 medit (scripts/tools/edit)、mgraphics (scripts/tools/graphics) 和 mvfx (scripts/tools/vfx) 的 Ruby 服务 (lib/media/edit.rb、speech.rb、guard.rb，…)。当缺少某个功能时，添加一个 Ruby 方法和一个薄任务层。一个项目运行其自身副本的 lib/ 和 tools/：在修改技能后，将更改的文件 rsync 到项目中。

内存安全（强制要求）

4K/HDR 硬件解码将帧保留在 VTDecoderXPCService 中，位于作业自身内存占用之外。在 16 GB 无交换空间的机器上，内存耗尽会冻结计算机而不是减慢速度。因此：

• 一次只运行一个重型作业（medit analyze/render/stills、mgraphics 编码、Demucs、大型 ffmpeg 编码）。切勿并行或在后台同时启动多个；如果需要，按顺序将它们链接到一个后台命令中。除非 RAM ≥ 32 GB，否则 JOBS 保持为 1。
• 每次 medit/mgraphics/mvfx 渲染调用都通过 Media::Guard（Ruby 服务中自动执行）：它每 0.3 秒采样一次作业 + 解码器内存占用和内核空闲百分比，并在达到 MEDIT_MAX_FOOTPRINT_MB（默认 3500）之前或低于 MEDIT_MIN_FREE_PCT（默认 30）时发送 SIGKILL。当可用内存已经很低时，它会拒绝启动。三个渲染器默认 JOBS=1；并行块需要显式设置 JOBS。
• 在任何新的解码/渲染代码路径上，首先使用短范围和紧限制进行验证（TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/path/log），检查日志是否平稳，然后运行完整长度。
• 在 Swift 媒体循环中，将每个 copyNextSampleBuffer 和 Core Image 渲染包裹在 autoreleasepool 中（异步代码永远不会清空默认池：帧以约 1.5 GB/秒的速度泄漏）。

测量稳态：每个 4K HLG 源的分析 ≈ 1.0 GB（作业 + 解码器）；带叠化的渲染会打开两个源。

1. 导入

只询问缺失的内容：素材路径、剪辑是什么（演讲片段、回顾…）、标题/演职员表文字、目标时长、旁白需求。使用媒体进行初始化（符号链接，从不复制或修改）：

ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" init --project /abs/project --media /abs/clip1.MOV --media /abs/clip2.MOV --prompt-file /abs/brief.md
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project setup

探测每个源（ffprobe：尺寸、帧率、时长、HDR 传输）。提取音频（audio/raw/*.wav，48 kHz）并在本地转录：edit:transcribe[analysis/transcripts,source/...]（mlx-whisper large-v3-turbo，字时间戳；免费）。阅读每份转录稿，将每个片段的内容及时间戳写入 docs/BRIEF.md。网络搜索标题中使用的事件事实并记录来源。

2. 分析（顺序执行）

REGION=0,0,1,0.62 DETECT_REGION=0.15,0.3,0.85,0.8 mv 'edit:analyze[source/A.MOV,analysis/A.json]'   # 一次一个
mv 'edit:track[analysis/A.json,analysis/A.track.json]'      # 当早期找不到说话者时 SEED=x,y；对于稳定化 SPACE=frame: 0
mv 'edit:stats[analysis/A.json,from,to]'

• REGION 将稳定化（相位相关）限制在静态场景（舞台、屏幕），排除观众。
• DETECT_REGION 裁剪舞台区域用于 Vision 人物检测，分辨率约提高 2 倍——对于远处的说话者至关重要（检测率从 2% 提高到 40–90% 的样本）。
• 跟踪是世界锁定的（移除了稳定化），连续性挑选，并通过 max_aspect 丢弃宽的背景框（头部）。
• 手机素材（iPhone 等）在相机中已经稳定：使用 stabilize: 0 和 SPACE=frame 跟踪进行渲染。 我们的稳定器可能将移动的幻灯片内容误认为是相机运动并添加突然的水平跳跃。检查：计算分析中 |Δshift| > 8 px 的帧数；在 iPhone 4K 上测得的残留抖动约为 0.9 px RMS，不值得校正。

语音流（填充词、错误起始、重复、不自然的停顿）

VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]'   # 使 Whisper 写出 um/uh
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]'   # 阅读 analysis/flow/A.txt

检测器声学测量停顿（能量 + 发声，而非 Whisper 字时间戳），对其进行分类（句子/逗号/短语），并标记填充词、未转录的哼声、重复和可能的错误起始，每个都带有建议的 cut。根据含义逐一决定，然后在生成器中使用 Media::Cuts 应用剪辑（第 4 步）。通过阅读 .txt 查找自我纠正和未完成的句子（“为了成——”等，在掌声前未完成的最后一句话）；检测器仅提出候选。

• 整帧颜色统计受到投影屏幕主导；在说话者区域（跟踪周围的瓦片）匹配曝光，并在静态帧上判断白平衡。

3. 规划与审批

编写 docs/PLAN.md：选择表（源、句子边界处的入/出点、内容、连接方式：叠化/跳切）、标题、旁白文本、镜头语言、画面和音频处理。在聊天中总结；使用 NOTE='...' plan:approve 记录批准（在付费调用前也需要，例如通过 voice:tts 进行的 ElevenLabs 旁白；参见 credentials.md——在插件会话中，付费任务通过 mk-video-editing MCP 服务器运行）。

4. 用生成器脚本构建 EDL

编写 edit/build_edl.rb（完整 EDL 模式和工作示例见 footage-editing.md）。定义镜头词汇表（WIDE zoom≈1.2–1.4，MWIDE fit≈0.4，MED fit≈0.56，PUNCH fit≈0.72，由 max_zoom 3.6 限制），并根据转录稿以源秒编写镜头节拍：在 6–12 秒内缓慢推进，在强调句上切入推近镜头，在主题/幻灯片变化时切入宽景，在每个跳切处重新构图。每个片段：safe 区域（避免干扰的前景）、deflicker、grade 匹配；一个共享的 look。叠加层是 ProRes 4444 alpha 标题（参见下面的标题部分）。

使用 lib/media/cuts.rb 移除选择内的单词和停顿：Media::Cuts.pause_cuts（自动缩短不自然的停顿）、Media::Cuts.segments（将选择分割成跳切片段，将边界对齐到单词之间的最安静点，在每个片段上打开对比构图，确保每个变焦持续 ≥ 4.5 秒）、Media::Cuts.text（记录每个剪辑移除了什么到 edit/cuts.txt）。在静默中开始和结束每个选择，并远离相机处理（检查边界附近的移动速度）。工作示例见 footage-editing.md。

5. 音频

speech:clean[audio/raw/A.wav,audio/clean/A.wav]（PRESET=room：低沉切除、FFT 降噪、浑浊切除、临场感、去咝声、温和扩展器、电平器；ISOLATE=1 用于本地 Demucs 人声提取）。根据要求使用 voice:tts 添加旁白（MODEL=v4 用于 Eleven v4）。仅当简报要求时添加配乐：提供的曲目或 music:score，作为 EDL music 放置（finishing.md）。然后运行 speech:mix[edit/edl.json,audio/mix.wav]。它将片段音频与叠化处的交叉淡入淡出混合（audio_xfade: 0.15 在 0.6 秒叠化前保留最后一个单词），在旁白下进行 audio_duck，以及 sounds 和带有侧链闪避的 music，然后应用两遍 loudnorm 到 −16 LUFS / −1.5 dBTP。

6. 检查、渲染、交付

• DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...]——每张静态帧加上带有裁剪（红色）、主体（绿色）和安全区域（黄色）的完整源帧。检查构图、头部空间、前景干扰、各剪辑间的曝光/白平衡连续性。
• edit:sheet 接触页；edit:preview[edl,out.mp4,from,to] 更改范围的半分辨率草稿。
• edit:render[edit/edl.json,output/final.mp4]（JOBS=1）。切勿覆盖已交付的母版。
• 渲染视频前的 QA：speech:mix，然后 edit:transcribe 混音并阅读每个片段 at 周围的文字（便宜；能捕捉到被截断的单词和瞬间闪过的画面）。渲染后，重新转录最终版本；在 docs/REVIEW.md 中记录版本和问题。

交付视频、计划/简报/检查文档，以及关于选择策略和已知问题的简短摘要。在更改工具包后运行 testing.md 中的 RSpec 配置文件，并在渲染器更改后在 tools/graphics 中运行 swift test。

标题

从 scripts/tools/graphics/examples/ 中的模板开始：opening_title.json、lower_third.json 和 end_card.json（1920×1080，AvenirNext，一种强调色）。将它们复制到 edit/titles/，更改文本和时间，或者在需要多个时从 edit/make_titles.rb 生成。网络检查名称、角色和活动事实。

1. 使用 ONLY= 在某个镜头的帧上（PLATE=）渲染静态帧，检查可读性、安全边距和强调色。
2. 以剪辑的帧率渲染 CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,frames,1920,1080,fps]。
3. 将其作为 EDL overlays 条目放置，在开场卡下方使用相机 dim/blur 使背景变暗或模糊。

场景格式（节点、轨道、缓动、辉光、字体）见 graphics README。渲染器更改后，在 scripts/tools/graphics 中运行 swift test，并逐字节比较新旧标题渲染结果。

收尾工作（可选）

配乐、音效和画面特效是可选的通道，在 finishing.md 中描述：

• 配乐在渲染前进入 speech:mix；
• SFX（sfx.yml）和 VFX（cues.yml）在渲染后的母版上运行，并且始终写入新文件。

当简报要求有宣传片或回顾感觉时使用它们。干净的演讲剪辑很少需要它们。

并行工作

对于长剪辑，将独立的作业（每个部分的标题、旁白行、检查静态帧、QA 转录）及其 depends 拆分到 config/production.json 中。通过 work:next 将它们交给子代理，让他们使用 work:log 报告，并在检查后接受每个（work:accept）。子代理可以并行编写场景、脚本和文档。重型媒体作业（medit、mgraphics/mvfx 编码、Demucs）仍然一次运行一个（内存安全见上文）。