视频小工具（压缩 · 剪切 · 合并 · 转格式 · 转 MP3 · 转 GIF · 字幕水印）

铁律（每次都要遵守）

1. 绝不覆盖原视频。 新文件一律另存到原视频旁边的「处理后」文件夹，重名自动加 _1、_2（用 --out-dir 指定别的文件夹时也一样），每隔几秒截图每次都新建文件夹，任何已有文件都不会被覆盖。处理失败会自动删掉没做完的半成品。
2. 只处理用户自己有权处理的本地视频。 不下载网上视频（给网址脚本会直接拒绝），不处理有版权保护的内容，不去除别人的水印。
3. 不联网、不自动装软件。 没有 ffmpeg 时只把安装步骤念给用户，由用户自己装。
4. 对用户用白话说明。 说「画质高/中/低」「快速模式/精确模式」，不堆码率参数、编码器名。脚本每次运行前会显示「将运行：<程序位置> <参数>」，这是为了透明，不要隐瞒；用户问起用了哪个程序、程序在哪里时如实告诉他。
5. 数字以脚本输出为准（大小、时长、分辨率），不要自己估算。
6. 出错时脚本输出两行「出错了：…」「下一步：…」，原样转述给用户，按「下一步」引导。

先确认有 ffmpeg

本技能靠免费开源的 ffmpeg 处理视频（脚本本身只用 Python 自带功能）。第一次用先跑：

python {baseDir}/scripts/video_tools.py check

• 脚本只在这几处找：本次命令用 --ffmpeg 指定的位置 → 系统 PATH（winget 安装后就在这里）→ C:\Program Files\ffmpeg\bin 这类受管安装目录。不会去下载、桌面等文件夹里翻找；找到后会显示所用程序的完整位置。
• 找不到时会输出安装指引：Windows 在终端输入 winget install Gyan.FFmpeg，或到 ffmpeg 官网下载解压后把文件夹位置告诉你。把指引念给用户，不要替用户下载或安装。
• 用户说「ffmpeg 在 D:\ffmpeg」时，跑 check --ffmpeg "D:\ffmpeg" 确认；脚本不会保存这个位置，本次对话里之后的每条命令都要带上同样的 --ffmpeg "D:\ffmpeg"。
• 装完后如果还提示找不到，让用户关掉重开一次助手（新装的程序要重开才认得）。

命令一览

全部是 python {baseDir}/scripts/video_tools.py <子命令> "<视频路径>" [选项]。路径一定要加英文双引号。

通用选项：--out-dir "文件夹" 让新文件放到别处（用户明确要求时才用；不能是 Windows 目录、Program Files 等系统文件夹，重名同样自动加 _1、_2）；--ffmpeg "位置" 指定本次使用的 ffmpeg。

时间写法都认：90、90秒、1:30、1分30秒、01:02:03、1小时2分。

每个功能要跟用户说清楚的事

• 压到指定大小：用「两遍法」，先分析一遍画面再正式压，大小误差一般在几个百分点内，所以会跑两遍进度。目标很小时会自动把画面缩到 1080P / 720P / 480P 保清晰度（脚本会说明）。如果视频本来就比目标小，脚本会说「不用压缩」。压到某个上限（如 100 MB）卡着传时，建议目标说小 5 MB 留余量。
• 按画质压缩：高 = 几乎看不出区别、文件减小有限；中 = 推荐，肉眼基本无差，体积明显变小；低 = 体积最小，细节会糊。
• 剪切的两种模式（一定要讲区别）：
• 快速模式：不重新压缩，几秒就好，画质完全不变；但开头只能从最近的「关键画面」切，可能比说的时间早零点几秒到两三秒。
• 精确模式：重新压缩，切点准确到每一帧，速度慢一些，画质几乎无损。
• 用户说「要准」「卡点」「一秒都不能多」时用精确模式；只是大概剪一下用快速模式。
• 合并：格式完全一样时直接首尾相接（快、无损）；不一样时自动统一成第一个视频的尺寸再合并，尺寸不同的加黑边，不会拉变形；没声音的片段自动补静音。
• 转格式：本来就是通用编码的只换「外壳」，几秒完成；苹果手机的 HEVC 会转成 H.264，时间较长，HDR 视频颜色可能稍淡。
• 转 GIF：没说时长默认取 10 秒；GIF 很占空间，超过 10 MB 脚本会提醒缩短或调小。
• 字幕：字幕会「印」进画面，任何播放器都能看到、也关不掉。支持 .srt / .ass，GBK 编码的中文字幕会自动识别；字幕文件名带空格、中文、括号都没问题。
• 背景音乐：音乐比视频短会自动循环，结尾 2 秒淡出。提醒用户只用自己有权使用的音乐。
• 处理进度：脚本会每 10% 打印一次「处理中：40%」，长视频处理时把进度告诉用户，让他别关窗口。

大白话 → 怎么做（例子）

1. 「这个视频太大了微信发不出去」→ 先 info 看大小；聊天软件和网站都有大小限制，用户没说多大时问一句「压到 100MB 以内可以吗？」，再 compress --size-mb 95。
2. 「帮我把视频压小一点，别太糊」→ compress --quality 中。
3. 「把第 1 分 20 秒到 2 分 05 秒剪出来」→ cut --start 1:20 --end 2:05；告诉用户这是快速模式，开头可能早一点点，要卡准再用精确模式。
4. 「把这三段视频拼成一个」→ merge "第一段" "第二段" "第三段"，按用户说的顺序。
5. 「把这个讲座视频转成音频，我开车听」→ audio（中音质即可；只听人声想更小用 --quality 低）。
6. 「苹果手机拍的视频电脑打不开 / 剪映导不进去」→ 先 info 确认是 HEVC，再 convert。
7. 「把这段做成表情包动图」→ gif --start <开始> --length 3 --width 320。
8. 「给这个视频截个封面」→ snapshot；「截 3 分 10 秒那个画面」→ snapshot --at 3:10；「每 30 秒截一张图做笔记」→ snapshot --every 30。
9. 「4K 视频太大了，转成 1080P」→ resize --to 1080P。
10. 「这个教程讲太慢了，弄成 1.5 倍速」→ speed --rate 1.5；「慢动作」→ speed --rate 0.5。
11. 「把视频里的声音去掉，换成这首歌」→ bgm --music "歌.mp3"；「保留说话声，加点轻音乐」→ bgm --keep-voice --music-volume 25。
12. 「在右下角加上我的抖音号」→ text --text "抖音号：xxx" --pos 右下。
13. 「把字幕文件加到视频上」→ subtitle --srt "字幕.srt"。
14. 「视频是横着的，转正」→ 问清是往左还是往右转，rotate --how 右转90 或 左转90；「镜像反了」→ rotate --how 水平翻转。
15. 「这个视频多长、清不清楚」→ info，把时长、分辨率（720P/1080P/4K）、大小、有没有声音念给用户。
16. 「电脑上没有那个什么 ffmpeg」→ check，把安装指引念给用户，等用户说装好了再继续。

用户只说文件名时，先问清楚视频在哪个文件夹（或让他在文件上按住 Shift 右键「复制文件地址」粘贴过来）。

不做什么

• 不下载网上的视频（抖音、B 站、YouTube 等任何网址都不处理），不录屏、不抓直播。
• 不处理有版权保护（加密/DRM）的内容，不去除视频里的水印、台标、字幕，不帮绕过任何保护。只处理用户自己有权处理的视频（自己拍的、自己做的、已获授权的）。
• 不覆盖、不删除、不移动原视频；新文件只放在「处理后」文件夹。
• 不联网，不上传视频或任何文件信息。
• 不自动下载或安装 ffmpeg 或任何软件，不改系统设置，不需要管理员权限。
• 不做复杂剪辑（转场、特效、多轨道配音、调色、AI 抠图/去人声），这些建议用剪映等剪辑软件。