Skip to content

Pythonpa/video-edit-skill

BranchesTags

Repository files navigation

video-edit-skill

English | 中文

小语种听写视频自动剪辑工具 —— 可作为 AI Agent 的 Skill 使用。

两种剪辑模式：

  • video_editor.py：整段统一倍速，将几分钟视频压缩到数十秒（适合快速预览）
  • segment_editor.py：分段变速剪辑，发音保持原速、写字适当加速，每段 12-15 秒（适合学习打卡）

支持平台：Windows / macOS / Linux | Agent：Claude Code / OpenCode / Hermes

AI Agent 自动部署指南（LLM 可执行）

以下指令按顺序执行即可完成部署。每步都是幂等的，失败可重试。

Step 0：确认前置条件

python3 --version   # 需要 3.10+
ffmpeg -version     # 需要已安装
git --version       # 需要已安装

如果缺少依赖，按平台安装：

依赖 Windows macOS Linux
Python 3.10+ winget install Python.Python.3.12 或 python.org brew install python@3.12 sudo apt install python3.12 python3.12-venv -y
FFmpeg winget install FFmpeg brew install ffmpeg sudo apt install ffmpeg -y
Git winget install Git.Git brew install git sudo apt install git -y

Step 1：克隆仓库

git clone https://github.com/Pythonpa/video-edit-skill.git
cd video-edit-skill

Step 2：一键安装

# Windows / macOS / Linux 通用
python3 setup.py install --agent opencode

此命令自动完成：

  1. 创建 .venv 虚拟环境
  2. 安装 pip 依赖（auto-editor, audio-separator, onnxruntime）
  3. 检查 FFmpeg 可用性
  4. 生成 SKILL.md 并注册到 Agent 的 skills 目录

首次运行约需 2-5 分钟（下载 PyTorch 等依赖约 300MB）。

Step 3：验证安装

python3 setup.py doctor

预期全部 [ OK ]。如果有 [FAIL]，按提示修复后重试。

Step 4：测试运行

# Windows
veditor.bat test_video.mp4 --target-duration 10-20

# macOS / Linux
.venv/bin/python video_editor.py test_video.mp4 --target-duration 10-20

Agent 重启后会自动发现此 Skill。

macOS 部署详细说明

Apple Silicon (M1/M2/M3/M4) 注意事项

Apple Silicon Mac 上安装 audio-separator 时需要确保使用 ARM 原生 Python：

# 确认 Python 是 ARM 原生（非 Rosetta）
python3 -c "import platform; print(platform.machine())"
# 输出应为 arm64

# 如果不是 arm64，用 Homebrew 安装原生 Python
brew install python@3.12
/opt/homebrew/bin/python3.12 setup.py install --agent opencode

创建 macOS 快捷入口

# 在项目根目录创建 veditor.sh（macOS/Linux 版快捷入口）
cat > veditor.sh << 'EOF'
#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
"$SCRIPT_DIR/.venv/bin/python" "$SCRIPT_DIR/video_editor.py" "$@"
EOF
chmod +x veditor.sh

# 之后可直接使用
./veditor.sh input.mp4 --target-duration 10-20

macOS 常见问题

问题 解决
python3 走 Rosetta (x86_64) brew install python@3.12 后使用 /opt/homebrew/bin/python3.12
ffmpeg 未签名无法打开 xattr -d com.apple.quarantine $(which ffmpeg) 或从系统设置中允许
.venv/bin/python 不存在 检查 .venv 是否创建成功：ls -la .venv/bin/，如失败重跑 python3 setup.py install
auto-editor 下载超时 设置代理：export HTTPS_PROXY=http://127.0.0.1:7890 后重试

使用方法

模式 1：统一倍速剪辑（video_editor.py）

适合将整段听写视频快速压缩。

# 自动倍速命中目标时长
.venv/bin/python video_editor.py input.mp4 --target-duration 10-20

# 手动指定倍速
.venv/bin/python video_editor.py input.mp4 --speed 1.4 -o output.mp4

# 批量处理
.venv/bin/python video_editor.py --batch ./raw_videos --output-dir ./processed --target-duration 10-20

模式 2：分段变速剪辑（segment_editor.py）

适合生成学习打卡短视频。韩语发音保持原速（1x），默写写字过程加速（1.2-1.4x），全程扩音器 + 响度最大化。自动按目标时长（12-15 秒）分组，每段包含若干韩语词。

# 基础用法（每段 12-15 秒，写字 1.3x）
.venv/bin/python segment_editor.py input.mp4 -o ./clips --target-duration 12-15

# 自定义写字倍速
.venv/bin/python segment_editor.py input.mp4 -o ./clips --write-speed 1.4 --target-duration 10-15

# 调整静音检测灵敏度（笔触声更轻时降低阈值）
.venv/bin/python segment_editor.py input.mp4 -o ./clips --silence-db -40

在 Agent 中自然语言触发

"帮我剪辑这个韩语听写视频，每段12-15秒，发音不要加速，写字1.3倍速"
"把 videos 目录下的听写录像全部处理一遍"

参数参考

video_editor.py（统一倍速）

参数 默认值 说明
--target-duration - 目标时长，如 15 或 10-20（自动计算倍速）
--speed 1.2 手动倍速（与 target-duration 二选一）
--max-speed 3.0 自动倍速上限
--silence-db -40 静音阈值 (dB)，越小越保守（保留更多内容）
--min-silence 1.0 最短静音时长 (秒)，短于此的不裁剪
--margin 0.1 裁剪边距 (秒)，在声音前后多保留的缓冲
--loudness -8 目标响度 (LUFS)，-8 适合短视频平台
--no-megaphone - 禁用扩音器音效
--separate-audio - 启用音频分离（听写视频不要开启）
--fps 30 输出帧率
--codec libx264 编码器，可选 libx265 / h264_nvenc / h264_amf
--crf 18 质量 (0-51)，越小越好
--preset medium 编码速度预设

segment_editor.py（分段变速）

参数 默认值 说明
--target-duration 12-15 目标每段时长范围，如 12-15
--write-speed 1.3 写字过程倍速（发音始终 1x）
--silence-db -30 静音阈值 dB，越小越敏感
--merge-gap 0.5 相邻有声段合并间隔/秒
--min-pron 0.3 最小发音段时长/秒（小于此为笔触噪音）
--loudness -8 目标响度 LUFS
--no-megaphone - 禁用扩音器音效

配置文件

所有参数都可以写在 JSON 配置文件中：

.venv/bin/python video_editor.py input.mp4 --config config.example.json

参见 config.example.json 获取完整模板。

处理流程

video_editor.py（统一倍速管线）

输入视频 (3-5分钟)
  │
  ▼
[1] 静音检测 + 裁剪 (auto-editor / FFmpeg)
  │  识别有声片段：发音、写字声、点击声
  │  删除无声间隔
  │
  ▼
[2] 自动倍速计算 (如指定 --target-duration)
  │  裁剪后时长 ÷ 目标时长 = 所需倍速
  │
  ▼
[3] FFmpeg 后处理
  │  ├─ 视频加速 (setpts) + 音频加速 (atempo)
  │  ├─ 扩音器特效 (带通滤波 + 压缩 + 中频增强)
  │  ├─ 音量最大化 (loudnorm)
  │  └─ 编码导出 (H.264, 30fps)
  │
  ▼
输出视频

segment_editor.py（分段变速管线）

输入视频 (3-5分钟)
  │
  ▼
[1] FFmpeg silencedetect 检测有声/无声段
  │
  ▼
[2] 分类：有声段 → 发音(>0.3s) vs 笔触噪音(≤0.3s)
  │  合并相邻段，构建「发音→写字→发音→写字」时间线
  │
  ▼
[3] 分组：按目标时长贪心组合单词单元
  │  每段 = N 个词（发音 1x + 写字 1.3x）
  │
  ▼
[4] 分段提取 + 变速 + 拼接
  │  每个子段独立用 FFmpeg -ss/-t 提取
  │  发音段: setpts=PTS/1 + atempo=1     (原速)
  │  写字段: setpts=PTS/1.3 + atempo=1.3  (加速)
  │  全程: 扩音器 + loudnorm → 拼接
  │
  ▼
多个短视频 (每段 12-15秒)

调参指南

输出太短（内容被切掉了）

# 降低静音阈值，让更多轻微声音被保留
--silence-db -35

# 增大边距，在声音前后多保留缓冲
--margin 0.15

# 两者组合
--silence-db -35 --margin 0.15

输出太长（间隔没切干净）

# 提高静音阈值
--silence-db -22

# 缩短最小静音时长，让更短的间隔也被删除
--min-silence 0.2

写字声音被切掉了

写字的沙沙声通常比较轻。降低阈值：

--silence-db -40 --margin 0.15

不要用音频分离

--separate-audio 会把网站 TTS 发音归类为"人声"并去除。听写视频场景下不要使用此选项。

项目结构

video-edit-skill/
├── video_editor.py          # 统一倍速剪辑脚本
├── segment_editor.py        # 分段变速剪辑脚本（发音1x + 写字1.3x）
├── setup.py                 # 通用安装器 (venv + deps + skill 注册)
├── veditor.bat              # Windows 快捷入口
├── veditor.sh               # macOS/Linux 快捷入口
├── install.bat              # Windows 一键安装（备用）
├── config.example.json      # 参数配置模板
├── requirements.txt         # pip 依赖清单
├── README.md                # 本文档
├── .gitignore
│
├── .venv/                   # Python 虚拟环境（自动创建，不入 Git）
│   └── Scripts/ (Windows) 或 bin/ (macOS/Linux)
│       ├── python
│       ├── auto-editor
│       └── audio-separator
│
└── .claude/skills/          # Claude Code Skill 定义
    └── video-edit/
        └── SKILL.md

迁移到新机器 SOP

场景：把这个 Skill 部署到一台新电脑上

Step 0：确认前置条件

  • 新机器有 Python 3.10+
  • 新机器有 FFmpeg（ffmpeg -version 能正常输出）
  • 新机器有目标 Agent（Claude Code / OpenCode / Hermes 至少一个）

Step 1：获取项目文件

git clone https://github.com/Pythonpa/video-edit-skill.git
cd video-edit-skill

Step 2：运行安装

python setup.py install --agent opencode

首次运行约需 2-5 分钟（下载 PyTorch 等依赖约 300MB）

Step 3：验证安装

python setup.py doctor

确认所有项显示 [ OK ]

Step 4：测试

# 统一倍速模式
veditor.bat test_video.mp4 --target-duration 10-20        # Windows
./veditor.sh test_video.mp4 --target-duration 10-20       # macOS/Linux
.venv/bin/python video_editor.py test_video.mp4 --target-duration 10-20  # 通用

# 分段变速模式
.venv/bin/python segment_editor.py test_video.mp4 -o ./clips --target-duration 12-15

完成。 Agent 下次启动时会自动发现 Skill。

常见问题

问题 原因 解决
python 命令找不到 Python 不在 PATH Windows: 重新安装 Python 并勾选 "Add to PATH"；macOS/Linux: 用 python3 代替 python
FFmpeg 不在 PATH 未安装或未加环境变量 Windows: winget install FFmpeg；macOS: brew install ffmpeg；Linux: sudo apt install ffmpeg，装完重开终端
auto-editor 下载失败 GitHub 连接超时 挂代理或手动下载 release 放到 .venv/Scripts/
audio-separator 安装慢 PyTorch 包较大 (~300MB) 耐心等待，或用 --no-cache-dir 重试
输出视频没有声音 使用了 --separate-audio 去掉这个参数，听写视频不需要音频分离
segment_editor.py 分段有重复 -t 参数在旧版放在 -i 之后 确保使用最新版（v1.2+），-t 已修正为输入选项
macOS 提示 "无法打开" macOS Gatekeeper 拦截 xattr -d com.apple.quarantine /path/to/ffmpeg 或在「系统设置→隐私与安全性」中放行

技术栈

组件 用途 许可证
auto-editor 静音检测 + 裁剪 MIT
python-audio-separator 音频分离（可选） MIT
FFmpeg 后处理 + 编码导出 LGPL/GPL

致谢

感谢以下开源项目：

声明

本项目仅供学习研究使用，严禁商业用途。使用者需遵守当地法律法规，使用风险自负。

License

MIT

联系方式

飞书文档

About

小语种听写视频自动剪辑工具 - AI Agent Skill (Claude Code / OpenCode / Hermes)

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages