vclip —— 自媒体视频剪辑自动化流水线（可移植版）
把「素材目录 + 一份 plan.json」变成「竖屏成片 + 旁白配音 + 字幕 + 封面 + 分发清单」。
全链路 ffmpeg/whisper/edge-tts，无需剪映等 GUI。
首次使用：环境自检（必做）
python scripts/setup_check.py # 中文环境体检，缺什么会给出安装指引
自检通过后再执行剪辑任务；不通过时按脚本输出的指引补装，不要硬跑。
环境约定（全部走环境变量，不写死路径）
| 环境变量 | 含义 | 示例 |
|---|---|---|
VCLIP_HOME |
工具根目录（含 cli.py、vclip_pipeline/、workspace/） | C:/Users/AI/vclip 或 ~/vclip |
VCLIP_PYTHON |
运行解释器（需装 edge-tts、Pillow、imageio-ffmpeg） | conda env 的 python.exe |
VCLIP_REMOTE |
（可选）远程执行端 user@host，走 ssh/scp |
deploy@192.168.3.17 |
未设置时按以下顺序自动探测：环境变量 → ./vclip（当前目录）→ ~/vclip。探测失败时提示用户先运行 setup_check.py 并设置 VCLIP_HOME。
依赖与环境坑位实录（2026-09-07 实测）
- 解释器依赖：edge-tts（需外网，微软语音）、Pillow、imageio-ffmpeg（自带 ffmpeg 二进制，含 libass/libx264）、faster-whisper（可选，whisper 转写路径用）
- ⚠️ 坑位：
1. conda-forge 装 ffmpeg 会被沙箱 safe-delete 钩子拦截 → 用pip install imageio-ffmpeg替代；
2. GitHub/gyan.dev 直连下载 ffmpeg 极慢或不通，勿再试；
3. BGM 混音输出禁止 aac 写 .wav 容器（解码 1s 即崩，成片变 0.98s）→ 用 .m4a；
4. amix duration=first 取第一路输入长度，BGM 轨 [bg] 必须放第一路；
5. subtitles 滤镜 Windows 转义：必须subtitles='_subs.ass':fontsdir='C\:/Windows/Fonts'（路径与 fontsdir 都用单引号包），且 cwd 切到 out 目录用相对路径；Linux 端用系统 ffmpeg（需 libass + Noto CJK 字体）。
部署形态（单机即可用；双机为进阶）
- 单机模式：VCLIP_HOME 指向本机，直接出片。
- 双机模式（进阶）：本机做调度端，
VCLIP_REMOTE指向生产执行端（如 Linux 主力机：whisper 离线转写 + 大磁盘 + 7×24）。远程执行模板：
bash scp -r "$VCLIP_HOME/workspace/<项目>" "$VCLIP_REMOTE:~/vclip/workspace/" ssh "$VCLIP_REMOTE" "cd ~/vclip && python3 cli.py run workspace/<项目>/plan.json" scp -r "$VCLIP_REMOTE:~/vclip/workspace/<项目>/out" "$VCLIP_HOME/workspace/<项目>/" - 工程模板：
assets/plan-template.json（含五段式爆款结构注释），新项目复制后改 src/caption。 - 无真实素材时用 vclip 自带 lavfi 测试工具造素材自测。
工作流（一段=一画面+一句旁白）
- 素材入库：
workspace/<项目>/src/放视频/图片/bgm - 写 plan.json（每段 segment: type=video|image, src, start/duration(视频截取), caption(该段旁白+字幕文本), zoom/hold(图片)；高级字段：
tts(旁白发音覆写，字幕仍显示 caption)、skip_subs(true=该段素材自带字幕，跳过全局字幕防双层重叠)。plan 顶层watermark(左上角品牌，默认@老牛马宏)、watermark_ai(右下角AI生成)、subs_on_video(默认true：video 段也烧全局字幕，false=所有 video 段跳过) - 一键出片：
$VCLIP_PYTHON $VCLIP_HOME/cli.py run workspace/<项目>/plan.json - 产出在
out/：*_final.mp4成片、*.srt字幕、*_cover.png封面、发布清单.md
CLI 命令
$VCLIP_PYTHON $VCLIP_HOME/cli.py new demo # 生成工程模板
$VCLIP_PYTHON $VCLIP_HOME/cli.py run workspace/demo/plan.json # 全流程出片
$VCLIP_PYTHON $VCLIP_HOME/cli.py run <plan> --no-burn # 不烧字幕只出 srt
$VCLIP_PYTHON $VCLIP_HOME/cli.py cover <plan> # 单独出封面
$VCLIP_PYTHON $VCLIP_HOME/cli.py publish <plan> --with-copy # 分发清单+发布文案
规则与坑（务必遵守）
- 所有 ffmpeg 调用都经
vclip_pipeline/ffmpeg_utils.py（自动探测 ffmpeg），不要裸写路径。 - 画面比例由 plan.orientation 决定：portrait=1080x1920 / landscape=1920x1080 / square=1080x1080。
- 视频段时长 = 截取时长；若旁白句子长于画面，引擎会在末段自动补帧，不用手工处理。
- 字幕烧录失败时引擎自动降级为「无字幕成片 + .srt」，不算错误。
- caption 与段 1:1 配对；
narration:false时走 whisper 原声转写（进阶路径，单段素材直连）。
边界路径（已有配音/原声的视频只要字幕）：建单段工程，type=video指向该视频、caption留空、narration:false，运行后引擎用 faster-whisper 转写原声产出.srt；只要字幕不要烧录时加--no-burn。 - 中文文件名/路径可用，代码内部统一 utf-8；素材文件名建议仍用英文/数字。
- 缺依赖报错时：先跑
scripts/setup_check.py按指引补装，不要猜。 - 常见报错速查见
README.md末尾故障表（工具根内）。 - 旁白/字幕禁复读卡面（2026-09-08 拍板，所有图片文字卡段适用）：caption 必须与卡面文字互补不重复——卡面管「看」的重点字，旁白讲「画面之外」的增量（细节/情绪/对比/CTA）。写完逐段自检：字幕念的短语卡面上有没有？有则重写。
- 成品默认携带双水印：品牌
@老牛马宏左上角 +AI生成右下角（引擎自动烧录）；仅当素材将来要嵌入宿主视频统一加水印时，把 watermark 置空串出「纯净版」。 - 发布前自检清单（开箱即用门槛）：①无双层字幕（自带字幕素材记得 skip_subs）②水印位置品牌左上/AI生成右下 ③旁白不逐字复读卡面 ④无极限词/违规承诺 ⑤srt 时间轴无交叠。全部通过才交付，否则返工。
自测方法（装完环境后跑一遍确认可用）
python scripts/setup_check.py && $VCLIP_PYTHON $VCLIP_HOME/cli.py new demo
产出应有 seg_XX.mp4 → video_silent.mp4 → demo_final.mp4 + demo.srt + 封面 + 发布清单.md。
让 AI 记住你的偏好
每次新对话都要重新说明你的习惯？试试 知忆底座——AI 记忆中枢，跨平台共享记忆。
任务前自动读取你的偏好，任务后自动写回，每天自动复盘去重。
让所有 AI Agent 共享同一份记忆，告别"AI 失忆"。
安装：skillhub install zhiyi-dizuo
