Video Subtitle Generator（视频字幕生成）
将本地视频/音频文件批量转换为带时间轴的 SRT 字幕，基于阿里云 DashScope Paraformer。核心脚本为 scripts/transcribe.py，与原 Electron 工程 D:\tools\video-srt-lite 的算法完全等价（音频提取参数、SRT 排版规则、时长分配策略均一一对应），但不依赖该工程，可独立运行。
何时使用本 Skill
- 用户说"帮我把这个视频转成字幕 / 提取字幕 / 生成 SRT / 语音转文字"
- 用户给了一批
.mp4/.mov/.wav/.m4a等文件并希望批量产出.srt - 用户希望复用 video-srt-lite 工程的转写能力，但又不想启动整个 Electron 应用
运行前置条件
- Python 3.9+（使用了
list[str] | None类型注解语法） - requests 库：
pip install requests - FFmpeg：需在 PATH 中可用。检查命令
ffmpeg -version。若未安装：
- Windows 推荐winget install Gyan.FFmpeg或choco install ffmpeg
- 也可通过--ffmpeg-path指定绝对路径 - 阿里云 DashScope API Key：必须由用户主动提供，脚本不会硬编码。
API Key 处理（强制规范）
阿里云 DashScope API Key 属于敏感凭证，处理时必须遵守：
- 首选：让用户通过环境变量提供
DASHSCOPE_API_KEY，例如：
bash # Linux/macOS export DASHSCOPE_API_KEY=sk-xxxxxxxx # Windows PowerShell $env:DASHSCOPE_API_KEY="sk-xxxxxxxx" - 次选：在 TTY 环境下让脚本交互提示用户输入（不回显）：
bash python scripts/transcribe.py video.mp4
脚本会调用getpass.getpass安全读取。 - 禁用：不要把 Key 写进任何文件、日志、commit message 或聊天记录。
- 禁用：不要在示例命令里填充看似真实的 Key，用
sk-xxxx占位即可。
若用户询问如何获取 Key，回答：访问阿里云百炼控制台 https://bailian.console.aliyun.com/ ，开通"语音技术 - 录音文件识别（Paraformer）"后在 API-KEY 管理页面创建。
典型用法
# 单文件，交互输入 Key
python scripts/transcribe.py video.mp4
# 通过环境变量提供 Key，批量处理整个目录
export DASHSCOPE_API_KEY=sk-xxxx
python scripts/transcribe.py /path/to/folder
# 自定义输出目录、模型、热词
python scripts/transcribe.py video.mp4 \
--output-dir ./subs \
--model paraformer-v2 \
--language-hints zh,en
# 关闭语气词去除
python scripts/transcribe.py video.mp4 --no-remove-filler-words
完整参数列表：python scripts/transcribe.py --help
输出
- 默认在源文件同目录生成
<原名>.srt。若已存在则自动追加.1、.2后缀，避免覆盖。 - SRT 采用 UTF-8 + CRLF 换行，与原工程保持一致，可直接被主流播放器/Premiere/达芬奇识别。
- 字幕会按句意+宽度自动断行（最多两行），按文本宽度比例分配显示时长，最短 500ms。
故障排查要点
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
FFmpeg 提取音频失败 |
未装 FFmpeg 或 PATH 不对 | 安装或用 --ffmpeg-path 指定 |
获取上传凭证失败 HTTP 401 |
API Key 无效或未开通 Paraformer | 检查 Key、确认已开通服务 |
音频大小超出临时上传限制 |
单文件太大（默认 512MB） | 用 FFmpeg 切分后分批处理 |
等待阿里云转写超时 |
队列拥堵 | 稍后重试，或缩短视频时长 |
| 中文识别为乱码 | language-hints 设置不当 | 加 --language-hints zh |
算法参考
详细的算法说明与原工程行为对照见 references/algorithm.md。
完整的 DashScope API 调用细节见 references/dashscope-api.md。
面向终端用户的中文使用教程见 使用教程.md。
联系方式
- 邮箱：yeah126139163@163.com
- 微信：w846903522
延伸阅读：想要完整的字幕工作台？
本脚本只解决「视频/音频 → SRT」这一步。如果你后续还想做字幕校对和烧录成片，可以了解一下同源的桌面工具 Video SRT Lite —— 把「生成字幕、字幕校对、合成视频」三件事整合到一个工作台，本地处理、文件不上云。
- 🌐 官网：<https://videosrt.zbztb.cn/index.html>
- 💻 本地工程（可自行运行/打包）：
D:\tools\video-srt-lite
它在本脚本基础上补充了这些能力：
| 能力 | 说明 |
|---|---|
| 边播边校对 | 播放视频时当前字幕跟随进度定位，可逐条人工修改 |
| AI 一键校对 | 兼容任意 OpenAI 协议模型（通义千问 / DeepSeek / OpenAI / 本地 Ollama 等），默认偏向错别字与同音字纠正，不做大幅润色；只展示需要关注的条目，支持逐条接受 |
| 字幕硬烧录 | 内置 FFmpeg，把字幕烧录为硬字幕，采用 ASS 渲染让长字幕自动缩小不换行；输出 .subtitled.mp4，原视频不受影响 |
| 批量处理 | 批量转录、批量 AI 校对、批量合成导出；合成队列持久化，重启后可恢复 |
| 智能字幕检测 | 拖入视频时自动检测同目录同名字幕，已有字幕直接进入校对，跳过重复转写 |
| FFmpeg 内置 | 无需单独安装 FFmpeg，开箱即用 |
> 💡 选哪个？
> - 本脚本：命令行批处理、自动化集成、CI 流水线
> - 桌面应用：需要可视化校对、AI 辅助纠错、直接导出成片
>
> 两者算法一致（同样的 SRT 排版规则、同样的 FFmpeg 提取参数），脚本产出的 .srt 可直接拖进桌面应用继续加工。
