openclaw-video-editor

v6.1.0

一个轻量、诚实的视频编辑技能，基于 ffmpeg、ffprobe 和 python3 构建。所有操作均在本地机器上运行，不依赖外部服务，无 AI 分割，无语音转录模型。

功能范围

此技能提供以下功能：

• scripts/check_deps.sh — 在任何工作流执行前检查 ffmpeg、ffprobe、python3 是否已安装。
• scripts/generate_srt.py — 将 Whisper / Deepgram / AssemblyAI / 通用词时序 JSON 文件转换为 .srt、.vtt 或 .ass 字幕文件。
• scripts/highlight_reel.py — 通过 ffmpeg 检测场景变化，并生成一段简短的精彩片段合集。
• scripts/apply_lut.py — 应用真实的 .cube 3D LUT（使用 lut3d），或使用命名滤镜预设（warm、cool、bw、high-contrast、faded）。
• scripts/loudnorm_two_pass.py — 自动完成两阶段 loudnorm 音频标准化流程。
• scripts/make_vertical.py — 将横向视频转为 9:16 纵向视频，支持黑边填充（letterbox）、居中裁剪（crop）或模糊填充（blur-fill）。
• scripts/extract_audio.py（v5.1.0 新增）— 提取干净的音频轨道，适用于语音转录、播客编辑或音乐分析。自动根据输出扩展名选择编码格式（mp3、m4a、aac、wav、flac、opus、ogg）。支持裁剪、重采样、声道强制设置和单次通过音量归一化。
• scripts/extract_clip.py（v6.1.0 新增）— 根据起始/结束时间戳从视频中提取片段。快速路径使用 ffmpeg 流复制（无需重新编码，无损，速度超过实时，会自动对齐到最近的关键帧之前 --start 时间点）。添加 --accurate 参数可启用重新编码实现帧级精确切割。支持普通秒数、MM:SS、MM:SS.mmm、HH:MM:SS、HH:MM:SS.mmm 格式。

此技能不包含以下功能：

• AI 背景移除或主体分割
• 语音克隆或生成式视频
• 语音转录（仅将词时序数据格式化为字幕文件；需搭配独立的 STT 工具）
• 任何远程 API 调用

必需二进制文件

bash scripts/check_deps.sh

若缺少 ffmpeg、ffprobe 或 python3，将返回非零状态码。

工作流

1. 从转录文本生成字幕

python3 scripts/generate_srt.py transcript.json subtitles.srt
python3 scripts/generate_srt.py transcript.json subtitles.vtt
python3 scripts/generate_srt.py transcript.json subtitles.ass --font Helvetica --fontsize 28

可调参数：--max-chars、--max-words、--max-duration，用于非英语语言的排版优化。

在 v5.1.0 版本中，脚本现在会明确拒绝不支持的输出扩展名（例如 .xml 原先会静默生成类似 SRT 的假数据，现改为退出码 2 并列出允许的扩展名），并以简洁的一行错误提示代替 Python 堆栈跟踪，报告格式错误的转录 JSON 数据（如 start/end 字段非数值类型）。

2. 将字幕烧录到视频中

ffmpeg -i input.mp4 \
  -vf "subtitles=subtitles.srt:force_style='Alignment=2,MarginV=30,Outline=2,Shadow=1'" \
  -c:a copy output.mp4

Alignment=2 表示底部居中。使用 Alignment=8 可实现顶部居中。

3. 背景模糊（隐私保护滤镜，非主体分割）

真正的浅景深效果需要 AI 分割，本技能不包含该功能。以下为全画面模糊处理：

ffmpeg -i input.mp4 -vf "boxblur=20:1" -c:a copy blurred.mp4

若已有二值透明蒙版（mask.mp4，主体为白色，背景为黑色，帧对齐），可将模糊背景合成在原始主体之后：

ffmpeg -i input.mp4 -i mask.mp4 \
  -filter_complex "[0:v]boxblur=20:1[bg];[0:v][1:v]alphamerge[fg];[bg][fg]overlay=format=auto" \
  -c:a copy composited.mp4

生成蒙版的过程不在本技能范围内。

4. 色彩调色

使用滤镜预设（无需 LUT 文件）：

python3 scripts/apply_lut.py input.mp4 - graded.mp4 --preset warm
python3 scripts/apply_lut.py input.mp4 - graded.mp4 --preset bw

使用真实 .cube LUT 文件：

python3 scripts/apply_lut.py input.mp4 lut.cube graded.mp4 --strength 0.8

5. 音频归一化（两阶段 loudnorm）

# 广播标准（-23 LUFS，EBU R128）
python3 scripts/loudnorm_two_pass.py input.mp4 normalized.mp4

# 流媒体平台（-14 LUFS）
python3 scripts/loudnorm_two_pass.py input.mp4 normalized.mp4 --target-lufs -14

该脚本执行第一阶段，解析 ffmpeg 标准错误输出中的测量结果，再运行第二阶段并应用测量所得偏移量。视频流直接复制，不重新编码。

在 v5.1.0 版本中，脚本现在会在开始前使用 ffprobe 检查输入文件是否包含音频流，若无则提前拒绝，避免在第一阶段内部因“无法找到测量 JSON”而出现模糊错误。

6. 通过场景检测生成精彩片段合集

python3 scripts/highlight_reel.py input.mp4 highlight.mp4 --duration 30 --threshold 0.4

7. 添加水印

# 右下角文字水印
ffmpeg -i input.mp4 \
  -vf "drawtext=text='@yourhandle':x=w-tw-20:y=h-th-20:fontsize=24:fontcolor=white@0.7:box=1:boxcolor=black@0.4:boxborderw=8" \
  -c:a copy watermarked.mp4

# 图像叠加（Logo）
ffmpeg -i input.mp4 -i logo.png \
  -filter_complex "[0:v][1:v]overlay=W-w-20:20" \
  -c:a copy watermarked.mp4

8. 制作 9:16 纵向短视频（适合短内容发布）

make_vertical.py 提供三种模式：

# 黑边填充：保持原比例，在 1080x1920 黑色画布中居中显示
python3 scripts/make_vertical.py input.mp4 vertical.mp4 --mode letterbox

# 裁剪：居中裁剪至 9:16 比例
python3 scripts/make_vertical.py input.mp4 vertical.mp4 --mode crop

# 模糊填充：原画面居中，四周用模糊副本填充
python3 scripts/make_vertical.py input.mp4 vertical.mp4 --mode blur-fill

blur-fill 是将横屏内容改编为短视频最常用的视觉风格。

9. 提取干净音频轨道（v5.1.0 新增）

视频编辑中最常见的需求：“只给我音频，以便转录 / 重新混音 / 播客使用”。

快速提取 MP3 音频

python3 scripts/extract_audio.py input.mp4 podcast.mp3

16 kHz 单声道 WAV - ASR / Whisper / Vosk 的标准输入格式

python3 scripts/extract_audio.py input.mp4 transcribe.wav \
  --sample-rate 16000 --channels 1

无损 FLAC 格式，用于归档保存

python3 scripts/extract_audio.py input.mp4 archive.flac

小体积 Opus 文件，适用于消息传递或网页使用

python3 scripts/extract_audio.py input.mp4 web.opus --bitrate 64k

截取从 1:15 开始的 30 秒片段

python3 scripts/extract_audio.py input.mp4 clip.mp3 --start 75 --duration 30

自动音量均衡输出，适用于播客音频输入（单次响度标准化至 -16 LUFS）

python3 scripts/extract_audio.py input.mp4 leveled.mp3 --normalize

输出编码格式由文件扩展名自动识别：

所有路径均通过与其它辅助工具相同的 shell 元字符白名单进行验证。脚本在处理前使用 ffprobe 检查输入文件，当源文件无音频流、输出扩展名不支持或 --bitrate 格式错误时会提前拒绝并退出。

10. 格式转换

# 1080p H.264 视频，质量合理
ffmpeg -i input.mp4 -vf "scale=-2:1080" \
  -c:v libx264 -preset medium -crf 20 \
  -c:a aac -b:a 160k output_1080p.mp4

退出码

安全特性

• 所有工作流均在本地运行，不调用远程 API。
• Python 辅助脚本使用 subprocess.run 以参数列表形式执行（从不使用 shell=True），并通过严格正则表达式白名单拒绝包含 shell 元字符的路径。
• 该技能不会修改系统配置、环境变量或其他插件。
• 该技能仅读取用户提供的输入文件，并将输出写入用户指定的路径。

已知限制

• 输入文件必须是可访问本地文件系统的有效音视频文件。
• 模糊合成路径需要预先存在的逐帧透明蒙版。生成蒙版不在本功能范围内。
• make_vertical.py --mode blur-fill 会进行完整重新编码；其他模式同样会重新编码视频流。音频流尽可能直接复制。

v6.1.0 版本更新

• 新增 scripts/extract_clip.py：根据 --start 和 (--end 或 --duration) 提取子片段。默认使用快速流拷贝路径（无需重新编码、无损、速度超过实时；自动对齐到最近的关键帧前）。使用 --accurate 可切换为 libx264 CRF 重新编码以实现帧级精确剪辑。--no-audio 可移除音频轨道。时间戳支持秒数、MM:SS[.mmm] 和 HH:MM:SS[.mmm] 格式。处理前通过 ffprobe 检查输入，拒绝无视频流的源文件，验证 --end > --start，对超出源文件时长的范围进行截断，并采用与其他脚本一致的安全路径策略。
• 退出码保持统一：0 表示成功，1 表示 ffmpeg 运行时错误，2 表示参数/路径/格式错误。其余脚本无变化。

v6.0.0 版本更新

主版本号升级，强制触发注册表摘要刷新。

此前 ClawHub 上的公开列表仍显示 v4.0.0 的宣传文案（“Pro-Studio v4.0.0 AI 背景移除……”），尽管 SKILL.md 自 v4.1.0 起已如实描述。类似 v5.0.0 时的摘要刷新机制在 v5.1.0 时部分失效，v5.2.0 的补丁发布也未能修复。v6.0.0 通过主版本号升级重新发布，确保注册表、SKILL.md 与实际代码内容一致。本次发布无代码变更，与 v5.1.0 / v5.2.0 相同：共 7 个脚本，CLI 参数不变，退出码一致。

v5.1.0 版本更新

新增工具

• scripts/extract_audio.py —— 支持自动编码格式选择（mp3、m4a、aac、wav、flac、opus、ogg）的干净音频提取，支持可选参数 --sample-rate、--channels、--start、--duration 和 --normalize。处理前通过 ffprobe 检查输入，验证输出扩展名，拒绝不安全路径。16 kHz 单声道 WAV 是语音识别管道的标准输入格式，此工具填补了视频文件与转录之间的空白。

错误修复

• generate_srt.py 现在不再在 start 或 end 字段非数字时泄露 Python 的 ValueError 调用栈。改为抛出 TranscriptFormatError 并返回一行提示信息（如：“transcript field 'start' must be a number, got 'not-a-number'”），并退出码 2。
• generate_srt.py 现在显式拒绝不支持的输出扩展名。此前 .xml 等未知扩展名会静默生成带有假后缀的 SRT 格式数据。当前支持的扩展名：.srt、.vtt、.ass。
• loudnorm_two_pass.py 现在在处理前通过 ffprobe -select_streams a 检查输入，若源文件无音频流则提前拒绝，避免在 loudnorm 第一阶段内部因“无法在 ffmpeg stderr 中找到测量 JSON”而出现模糊错误。

无破坏性变更：保留 v4.2.0 / v5.0.0 的所有 CLI 参数、输出文件名和行为。v5.1.0 仅新增使用模式，移除潜在陷阱。

许可证

MIT。详见 LICENSE。