yrns-video-studio · 免费视频剪辑 + AI 配音 + AI 合成（零积分优先）

> ## 这个工具给你什么（拿到就能用）
> 装好依赖，立刻得到一个完全免费的「视频剪辑 + 中文 AI 配音」工具：
> - 剪辑 / 加字幕 / 加BGM / 转场 / 调速 / 水印去水印 → 本地 ffmpeg，离线、免费
> - 中文 AI 配音（晓晓/云扬等神经语音） → 本地 edge-tts（微软免费，无需任何密钥，仅联网）
> - 图片变视频（缓慢运镜 + 交叉淡化） → 本地 ffmpeg，离线、免费
> - 「AI 凭空生成视频」 → 调 Agnes 云端（需要你自己的 API Key + 显式 --allow-credit，会消耗你的积分；不在此范围也能做上面所有事）

一、核心原则：默认零积分、绝不偷偷扣费

本技能默认 100% 不消耗任何积分/额度，只调用两样本地免费工具：ffmpeg（剪辑/图片转视频）+ edge-tts（配音）。

唯一会消耗积分的是「Agnes 生视频」，且被硬闸锁死：除非命令里同时显式加 --allow-credit，否则脚本直接拒绝调用 Agnes、打印 🚫 已拒绝，并继续用本地免费素材出片。不加开关 = 永远不扣费。

二、决策树：什么时候免费 / 什么时候需要自己的 Key

> 记住一句话：不碰 Agnes，就一分钱不花、一个积分不扣。

三、三步上手（完全免费，无需任何密钥）

> 下面 PY 指本技能运行脚本用的 Python。请先准备一个 Python 3.10+ 环境并装好依赖：
> 1) 建虚拟环境：python -m venv .venv，激活后 .\.venv\Scripts\python -m pip install -r requirements.txt
> 2) 之后所有命令里的 PY 都换成 .venv\Scripts\python（或你自己的 python）
> 技能脚本目录：scripts\（相对于本技能根目录，请改成你解压后的实际路径）
> 网页版剪辑器需要 Flask（已含在 requirements.txt），启动见「网页版」小节。

第 1 步 · 装一次依赖（一次性）

PY -m pip install -r "requirements.txt"

> ffmpeg 二进制由 imageio-ffmpeg 随依赖提供，无需单独下载；Flask 也在此步一并装好。换机把上面的 PY / 脚本目录改成你自己的 venv / 技能目录即可。

第 2 步 · 准备素材
随便放几段视频（clip1.mp4、clip2.mp4）、几张图（p1.jpg、p2.jpg）、一个逐行台词 script.txt、一段 BGM（bgm.mp3）。

第 3 步 · 跑出片（免费）

PY "…\scripts\compose.py" ^
  --inputs "C:\clip1.mp4" "C:\clip2.mp4" ^
  --dub-script "C:\script.txt" --voice xiaoxiao ^
  --bgm "C:\bgm.mp3" --output "C:\final.mp4"

或纯图片做视频：

PY "…\scripts\compose.py" ^
  --images "C:\p1.jpg" "C:\p2.jpg" ^
  --dub-script "C:\script.txt" --voice xiaoxiao --output "C:\final.mp4"

成片 final.mp4 就生成了——全程没用到任何 API Key。

四、场景详解

场景 A：一站式成片（最常用，零积分）

PY "…\scripts\compose.py" ^
  --inputs "C:\clip1.mp4" "C:\clip2.mp4" ^
  --dub-script "C:\script.txt" --voice xiaoxiao ^
  --bgm "C:\bgm.mp3" --output "C:\final.mp4"

• --dub-script：每行一句台词，自动生成「配音 mp3 + 同步字幕」并烧进视频；不想配音就去掉它。

场景 A2：图片直接变视频（零积分的「AI 合成」）

PY "…\scripts\compose.py" ^
  --images "C:\p1.jpg" "C:\p2.jpg" "C:\p3.jpg" ^
  --dub-script "C:\script.txt" --voice xiaoxiao --output "C:\final.mp4"

• 单独跑：PY "...\scripts\edit_video.py" photos --images p1.jpg p2.jpg --output slide.mp4
• 关运镜：--no-kenburns；调规格：--w 1920 --h 1080 --fps 30 --dur 4

场景 B：单步剪辑（ffmpeg，离线）

PY "...\scripts\edit_video.py" trim   --input a.mp4 --start 5 --end 20 --output cut.mp4
PY "...\scripts\edit_video.py" concat --inputs a.mp4 b.mp4 --output all.mp4 --transition crossfade
PY "...\scripts\edit_video.py" speed  --input a.mp4 --rate 1.5 --output fast.mp4
PY "...\scripts\edit_video.py" add-bgm --input a.mp4 --bgm bgm.mp3 --vol 0.3 --output bgm.mp4
PY "...\scripts\edit_video.py" mix-audio --input a.mp4 --audio dub.mp3 --output out.mp4
PY "...\scripts\edit_video.py" watermark --input a.mp4 --logo logo.png --pos bottomright --output wm.mp4
PY "...\scripts\edit_video.py" watermark --input a.mp4 --delogo "x:y:w:h" --output nowm.mp4
PY "...\scripts\edit_video.py" add-subs --input a.mp4 --srt sub.srt --output sub.mp4
PY "...\scripts\edit_video.py" photos  --images p1.jpg p2.jpg --output slide.mp4

场景 C：AI 配音（edge-tts，免费）

PY "...\scripts\dub_video.py" say   --text "大家好，今天讲三角形" --voice xiaoxiao --output say.mp3
PY "...\scripts\dub_video.py" script --text-file script.txt --voice xiaoxiao --out-dir "C:\dub"

• 音色：xiaoxiao(晓晓女)、yunyang(云扬男)、xiaoyi(晓伊女)、yunxi(云希男)，或 zh-CN-* 全名。
• 调语气：--rate "+20%" / --volume "-10%" / --pitch "+5Hz"；直接混进视频加 --mix-video a.mp4。
• 需要联网（连微软免费接口），但不需要任何密钥、不扣积分。

场景 D：Agnes 云端生视频（【消耗积分】，需你自己的 Key，默认禁用）

只有你明确想花 Agnes 积分、且已配置好自己的 Agnes Key 时才用，必须加 --allow-credit：

PY "...\scripts\generate_video.py" --prompt "一只猫在夕阳下的海滩散步" ^
  --node auto --download --allow-credit --output "C:\agnes_clip.mp4"

或在 compose 里：

PY "...\scripts\compose.py" --agnes-prompt "一只猫在夕阳海滩散步" ^
  --allow-credit --dub-script script.txt --output final.mp4

• 不加 --allow-credit 一律拒绝，打印 🚫 已拒绝...，不会扣费。
• 没有自己的 Agnes Key 时，这条直接报错退出，不影响上面所有免费功能。
• 图生视频加 --image <公开图片URL>；视频为异步任务，脚本自动轮询（最长 900s）。

场景 E：网页版剪辑器（客户自助，零积分）

适合不懂命令行的用户：本地起一个网页，拖入视频即可自助剪辑。

PY web/app.py            # 默认 http://127.0.0.1:5000
PY web/app.py --port 8080

打开网页后的操作：
1. 上传视频：拖入或点击选择（作为“当前片段”）。
2. AI 解说配音 + 自动字幕（核心）：在「🎙️ AI 解说配音」面板粘贴逐行解说文案 → 选音色（云扬/晓晓/云希/晓伊）→ 勾选「加片头+片尾」→ 点「生成 AI 配音成片」。原声会被解说配音替换，字幕按配音语速自动对齐烧入。
3. 其余手动操作：裁剪 / 调速 / 加BGM / 手动烧字幕 / 多段拼接+转场 / 去水印 / 图片转视频。
4. 每步基于“当前片段”，可链式编辑；右下角「下载当前成片」导出。
- 全程本地 ffmpeg，不联网不扣费；仅 AI 配音需联网调用微软免费接口（仍不消耗积分/密钥）。
- 处理在本地 web/uploads、web/outputs 目录进行，单用户本地工具。

五、故障排查

六、安全说明（给别人用时也放心）

• 本技能不含任何硬编码密钥；密钥只在用户自己配置 ~/.workbuddy/.apikeys.env 后、且显式 --allow-credit 时才发送给 Agnes 官方域名。
• 默认免费流程根本不打开密钥文件、不发送任何带密钥的请求。
• 技能包（zip）里不含密钥文件，可安全分享。

Resources

• README.md — 给最终用户的纯人话使用说明（安装/免费用法/何时需 Key）。
• scripts/common.py — 读密钥、定位 ffmpeg、运行命令、解析时长。
• scripts/generate_video.py — Agnes 文生/图生视频（双节点，默认拒绝，需 --allow-credit）。
• scripts/edit_video.py — ffmpeg 剪辑 + 图片转视频（零积分）。
• scripts/dub_video.py — edge-tts AI 配音（免费）。
• scripts/compose.py — 拼接+（可选图片转视频）+配音+字幕+BGM 一站式流水线（零积分默认）。
• requirements.txt — 依赖清单。
• web/app.py + web/index.html — 网页版剪辑器（Flask 本地服务 + 实时预览前端）。
• references/api_reference.md — 接口与要点参考。