Video Subtitle Generator（视频字幕生成）

将本地视频/音频文件批量转换为带时间轴的 SRT 字幕，基于阿里云 DashScope Paraformer。核心脚本为 scripts/transcribe.py，与原 Electron 工程 D:toolsvideo-srt-lite 的算法完全等价（音频提取参数、SRT 排版规则、时长分配策略均一一对应），但不依赖该工程，可独立运行。

何时使用本 Skill

• 用户说"帮我把这个视频转成字幕 / 提取字幕 / 生成 SRT / 语音转文字"
• 用户给了一批 .mp4/.mov/.wav/.m4a 等文件并希望批量产出 .srt
• 用户希望复用 video-srt-lite 工程的转写能力，但又不想启动整个 Electron 应用

运行前置条件

1. Python 3.9+（使用了 list[str] | None 类型注解语法）
2. requests 库：pip install requests
3. FFmpeg：需在 PATH 中可用。检查命令 ffmpeg -version。若未安装：
   • Windows 推荐 winget install Gyan.FFmpeg 或 choco install ffmpeg
   • 也可通过 --ffmpeg-path 指定绝对路径
4. 阿里云 DashScope API Key：必须由用户主动提供，脚本不会硬编码。

API Key 处理（强制规范）

阿里云 DashScope API Key 属于敏感凭证，处理时必须遵守：

• 首选：让用户通过环境变量提供 DASHSCOPE_API_KEY，例如：

  # Linux/macOS
  export DASHSCOPE_API_KEY=sk-xxxxxxxx
  # Windows PowerShell
  $env:DASHSCOPE_API_KEY="sk-xxxxxxxx"
  

• 次选：在 TTY 环境下让脚本交互提示用户输入（不回显）：

  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。

故障排查要点

算法参考

详细的算法说明与原工程行为对照见 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:toolsvideo-srt-lite

它在本脚本基础上补充了这些能力：

💡 选哪个？

• 本脚本：命令行批处理、自动化集成、CI 流水线
• 桌面应用：需要可视化校对、AI 辅助纠错、直接导出成片

两者算法一致（同样的 SRT 排版规则、同样的 FFmpeg 提取参数），脚本产出的 .srt 可直接拖进桌面应用继续加工。