AISRT：本地 AI 字幕生成工具，视频/音频转 SRT 与本地翻译

语言：简体中文 | English

AISRT 是面向 Windows 桌面和命令行的本地 AI 字幕生成工具，专注把视频、音频转换为带时间轴的 .srt 字幕。它支持多语言 ASR、字幕时间轴对齐、GUI 多文件队列、CLI 批量处理和本地 SRT 翻译；媒体文件、字幕、缓存和日志默认保留在本机，适合离线字幕生成、视频转 SRT、音频转 SRT 和隐私敏感的个人字幕工作流。

你可以用 AISRT：

• 把 mp4、mkv、mov、mp3、wav 等常见媒体文件生成 .srt 字幕。
• 在本机完成语音识别、时间轴对齐和字幕翻译，不自动上传媒体或字幕。
• 用图形界面处理单个或多个文件，也可以用 CLI 做字幕批处理。
• 在长视频处理时查看 movie.preview.srt 预览字幕，完成后得到最终 movie.srt。

项目定位很明确：个人桌面/命令行工具，优先保证简单、稳定、可维护。不做 Web UI，不做服务端，不接数据库。

常见搜索场景：本地 AI 字幕生成、视频转 SRT、音频转 SRT、离线字幕工具、多语言 ASR、语音识别字幕、字幕时间轴对齐、SRT 翻译、Windows 字幕生成、GUI 字幕软件和 CLI 字幕批处理。

界面预览

新用户先看

• 只想快速试用：按 快速开始 安装依赖后运行 ai-sub-gui。
• 想批量生成字幕：看 命令行，用 ai-sub ".\media" --recursive。
• 已有字幕只想翻译：看 SRT 字幕翻译，用 GUI 或 ai-sub-translate。
• 担心隐私：看 隐私与开源发布，AISRT 默认在本机处理文件。

功能速览

说明：项目公开名称不使用模型厂商商标；Qwen3-ASR 与 Qwen3-ForcedAligner 只作为模型 ID 和技术依赖出现。

适用与不适用场景

适合：

• 在本机为视频、音频生成 .srt 字幕。
• 处理个人媒体文件或离线批量任务。
• 需要 GUI 给普通用户操作，同时保留 CLI 便于排查和脚本化。
• 希望模型、缓存、日志和生成文件都留在本机。

不适合：

• 在线字幕服务、多人协作后台或 Web 应用。
• 必须使用云端翻译 API、在线协作或自动上传字幕文件的场景。
• 没有 FFmpeg、磁盘空间或可用模型下载渠道的环境。
• 希望在 CPU 上快速处理长视频的场景。

工作流程

视频/音频文件
  -> FFmpeg 提取 16k 单声道临时 WAV
  -> 本地 ASR 模型识别语音文本
  -> 本地强制对齐模型生成时间戳
  -> 字幕后处理
  -> 输出 .srt 文件

快速开始

Windows 10/11 是主要支持环境。Linux 和 macOS 可自行验证。

开始前先确认：

• 已安装 Python 3.10-3.12，推荐 Python 3.11。
• 已安装 FFmpeg，并且 ffmpeg、ffprobe 能在命令行中直接运行。
• 推荐使用 NVIDIA GPU；CPU 可以运行，但处理长视频会明显变慢。
• 首次使用远程模型 ID 时会下载模型权重，请预留磁盘空间。

git clone https://github.com/zkwi/AiSRT.git
cd AiSRT
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -r requirements.txt
ai-sub doctor
ai-sub-gui --check

启动图形界面：

ai-sub-gui

命令行处理单个文件：

ai-sub "movie.mp4" --overwrite

完成后，默认会在 movie.mp4 旁边生成 movie.srt。长视频处理期间可以打开同目录的 movie.preview.srt 查看已识别片段；全部完成后会自动删除预览文件并重写最终字幕。

也可以双击：

• activate_env.bat：进入项目虚拟环境，并设置项目内模型缓存目录。
• open_ui.bat：用当前虚拟环境启动 GUI。

环境要求

• Python 3.10-3.12，推荐 Python 3.11。
• FFmpeg 与 ffprobe 已安装，并可在命令行中直接运行。
• 推荐 NVIDIA GPU。CPU 可以运行，但长视频会明显变慢。
• 首次使用远程模型 ID 时需要下载模型权重，请预留足够磁盘空间。

当前默认安装使用 CUDA 版 PyTorch，具体固定项放在 requirements-torch-cu130.txt：

torch==2.11.0+cu130
torchaudio==2.11.0+cu130

如果你的 CUDA/PyTorch 环境不同，请先按 PyTorch 官方安装方式调整 requirements-torch-cu130.txt，或手动安装匹配版本后再安装本项目依赖。

图形界面

GUI 面向普通用户，主界面只保留高频操作：

• 添加文件：选择一个或多个视频/音频文件，也支持拖拽文件进入窗口。
• 开始处理：按文件队列逐个生成 ASR 原始字幕。
• 启用翻译：勾选后，主按钮会变为“识别并翻译”，先生成 ASR 原始字幕，再继续输出翻译语言字幕。
• 文件队列：显示文件、状态、进度和字幕目录。
• 进度提示：ASR 识别和字幕翻译会显示预估剩余时间，格式为 分钟:秒。
• 语言设置：界面语言默认跟随系统语言，手动切换后会记住；识别字幕语言用于 ASR；翻译语言用于生成译文字幕。
• 常用设置：识别字幕语言、是否启用翻译、翻译语言、运行模式、模型尺寸。
• 高级设置：设备、音频分块、字幕样式、覆盖输出、本地缓存。
• 运行日志：默认显示关键进度、剩余时间和问题提示；勾选“显示详细日志”后显示更完整的底层细节。
• 翻译已有 SRT：选择已有 SRT 文件，使用本地翻译模型输出多语言字幕。

默认行为：

• 字幕保存到每个媒体文件所在目录。
• 不覆盖已有 .srt，发现同名输出会先询问。
• 支持简体中文、繁体中文、英语、日语、韩语、西班牙语六种界面语言；首次启动默认匹配系统语言，手动切换后优先使用用户选择。
• 识别字幕语言和翻译语言使用 ASR 与本地翻译共同支持的常用语种，例如简体中文、繁体中文、英语、日语、韩语、西班牙语、法语、德语、葡萄牙语、俄语和阿拉伯语。
• 本次运行内会记住上次添加媒体文件的位置，下一次添加文件会从该目录打开。
• 添加文件和开始处理是核心按钮，保留图标；翻译开关、停止和翻译已有 SRT 默认只显示文字，避免界面噪声。

推荐设置：

SRT 字幕翻译

软件不调用第三方翻译 API，也不会自动上传字幕文件。主界面的“翻译已有 SRT”按钮会打开本地翻译窗口：

1. 选择已有 .srt 文件。
2. 选择翻译语言，GUI 只展示识别与翻译共同支持的常用语种。
3. 选择质量优先或快速轻量模式，开始翻译。

翻译逻辑只把字幕正文发给本地 HY-MT 模型，SRT 编号和时间轴由程序保留并合并。默认质量模式使用官方 HY-MT 1.8B 模型；快速模式使用轻量量化模型，适合先快速预览。翻译模型复用当前 .venv 中的 PyTorch/CUDA 环境，不需要用户额外安装另一套 Python 或 CUDA。

主界面勾选“启用翻译”后，适合从音视频一步生成双语结果。例如识别字幕语言设为英语、翻译语言设为简体中文时，会在媒体文件旁生成：

movie.srt      # ASR 识别后的英文原始字幕
movie.zh.srt   # 本地翻译模型生成的简体中文字幕

启用翻译后，处理流程会先写入 ASR 原始字幕，再加载翻译模型。若翻译模型缺失或翻译失败，原始字幕会保留，队列状态会提示“翻译失败，已保留原字幕”，可在模型准备好后重试失败项。

命令行

单文件处理：

ai-sub "movie.mp4" --overwrite

使用轻量模型：

ai-sub "movie.mp4" --model-size 0.6B --overwrite

批量处理目录：

ai-sub ".\media" -o ".\subtitles" --recursive --overwrite

翻译已有 SRT：

ai-sub-translate "sample.srt" --to 简体中文 --overwrite

使用快速轻量翻译模型：

ai-sub-translate "sample.srt" --to English --model-mode fast --overwrite

使用本地已下载模型：

ai-sub "movie.mp4" `
  --model .\models\Qwen3-ASR-1.7B `
  --aligner .\models\Qwen3-ForcedAligner-0.6B `
  --local-files-only `
  --overwrite

常用参数：

完整参数：

ai-sub --help

模型与缓存

默认模型：

Qwen/Qwen3-ASR-1.7B
Qwen/Qwen3-ForcedAligner-0.6B

可选 ASR 尺寸：

1.7B  默认，质量更好，显存占用更高
0.6B  更轻量，速度更快，适合低显存或快速预览

首次运行如果使用 Hugging Face ID，会自动下载模型权重。建议把缓存放在项目目录 .hf_cache/，便于清理和开源发布时忽略。

手动下载示例：

mkdir models
huggingface-cli download Qwen/Qwen3-ASR-1.7B --local-dir .\models\Qwen3-ASR-1.7B
huggingface-cli download Qwen/Qwen3-ASR-0.6B --local-dir .\models\Qwen3-ASR-0.6B
huggingface-cli download Qwen/Qwen3-ForcedAligner-0.6B --local-dir .\models\Qwen3-ForcedAligner-0.6B

运行时会在 .hf_cache/audio_tmp/ 下生成临时 WAV。该目录属于运行缓存，不应提交到 Git。

输出文件

默认输出：

movie.srt

处理过程中会临时写入预览字幕，方便提前查看已识别内容；完整处理成功后会删除预览文件，并重新写入最终字幕：

movie.preview.srt

AISRT 只会清理本次运行实际创建的预览文件，不会按媒体文件名猜测并删除同名的 .txt 或 .raw.srt。批量任务会在加载模型前检查最终字幕、翻译字幕和预览字幕的文件名冲突；所有字幕文件均通过原子替换写入，失败时保留已有文件。

常见问题

AISRT 是什么？

AISRT 是面向个人使用的本地 AI 字幕生成工具，支持从视频或音频生成 .srt 字幕，也支持对已有 SRT 字幕做本地翻译。

AISRT 支持哪些字幕工作流？

常用工作流包括：视频转 SRT、音频转 SRT、多语言语音识别、字幕时间轴对齐、SRT 字幕翻译、GUI 多文件队列处理和 CLI 批量处理。

AISRT 会上传媒体或字幕文件吗？

不会。AISRT 默认在本机运行 ASR、强制对齐和翻译模型，不调用云端翻译 API，也不会自动上传媒体、字幕或日志。

找不到 FFmpeg

运行：

ai-sub doctor

如果 ffmpeg 或 ffprobe 不可用，请先安装 FFmpeg，并确认 ffmpeg、ffprobe 能在命令行中直接运行。

首次运行很慢

首次运行可能会下载模型权重，并进行模型加载。模型体积较大，耗时取决于网络、磁盘和显卡环境。

显存不足

优先尝试：

• GUI 中切换到“低显存”运行模式。
• 模型尺寸改为 0.6B。
• CLI 中使用 --device cpu 作为兜底，但速度会明显变慢。

不想联网下载模型

提前把模型下载到 models/ 目录，然后使用 --local-files-only 和本地模型路径。

生成字幕不够稳定

可尝试：

• 明确指定识别字幕语言。
• CLI 可通过 -c, --context 提供片名、人名、地名或专有名词。
• 把音频分块从 45 秒改为 30 秒。
• 使用 1.7B 模型而不是 0.6B。

项目结构

aisrt/
  cli.py           CLI 入口、音频准备、单文件处理编排
  gui.py           PyQt 主窗口与用户交互
  gui_worker.py    GUI 后台处理线程
  gui_i18n.py      GUI 多语言文案和日志本地化
  gui_theme.py     GUI QSS 样式
  local_asr.py     本地 ASR 调用、分块识别、时间戳整理
  local_translate.py 本地 SRT 翻译、分段和译文合并
  translate_cli.py  SRT 翻译命令行入口
  translate_worker.py GUI 翻译后台线程
  postprocess.py   SRT 解析、清洗、去重、断行和时间轴修复
  diagnostics.py   本地环境检查
tests/             单元测试和 GUI offscreen 测试
docs/              工程治理、发布检查和维护文档

开发与验证

安装开发、测试和打包依赖：

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt

依赖文件分工：

• requirements.txt：普通运行环境，安装默认 CUDA PyTorch 栈和 AISRT 包。
• requirements-dev.txt：开发环境，复用默认 CUDA PyTorch 栈，并以 editable 模式安装开发工具。
• requirements-torch-cu130.txt：默认 CUDA PyTorch 固定项；切换 CUDA/CPU 版本时优先改这里。

常用检查：

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q aisrt tests
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe -m aisrt --help
.\.venv\Scripts\python.exe -m aisrt doctor
.\.venv\Scripts\python.exe -m aisrt.gui --check
git diff --check

发布构建

Windows portable 包采用“轻量下载 + 首次启动自动安装依赖”的方式：ZIP 不包含 Python、PyTorch/CUDA 运行库、模型权重、FFmpeg、.venv、缓存、媒体、字幕、截图或日志，避免安装包体积失控。目标产物为：

dist/release/AiSRT-v0.1.5-windows-portable.zip
dist/release/aisrt-0.1.5-py3-none-any.whl
dist/release/SHA256SUMS.txt

构建命令：

.\scripts\build_portable.ps1 -InstallDeps

约束：

• Portable ZIP 包含 AISRT.bat，普通用户解压后优先双击它。
• 首次运行 AISRT.bat 时会自动调用 install_runtime.bat，在当前目录创建 .venv 并安装 requirements.txt 中的 Python 依赖；后续启动会直接打开 GUI。
• Portable ZIP 不包含模型权重、模型缓存、测试媒体、截图、日志或生成字幕。
• Portable ZIP 不包含 Python 解释器、PyTorch/CUDA DLL 或其他本地运行环境。
• 使用远程模型 ID 时，模型权重会在首次运行时下载到 Hugging Face 缓存目录。
• FFmpeg 和 ffprobe 需要用户单独安装，并确保可在 PATH 中直接运行。
• start_gui.bat 和 open_shell.bat 保留给需要手动启动或排查命令行环境的用户。
• Release asset 上传前应保留 ZIP、wheel 和 SHA256SUMS.txt 三个文件。
• packaging/aisrt_portable.spec 仅保留给维护者本地试验完整运行时打包，默认 Release 不使用它。

文档导航

• AGENTS.md：给代码代理和维护者看的项目约束、验证命令和协作规则。
• 贡献指南：开发原则、提交前检查、Issue 与 PR 要求。
• 支持说明：Issue 范围、提问前检查和隐私提醒。
• 安全说明：敏感信息、日志脱敏和安全问题报告。
• 行为准则：公开协作中的基本沟通规则。
• 工程治理说明：源码模块边界、GUI/CLI 约定和发布前检查。
• 开源发布检查清单：发布前逐项核对。
• 变更日志：版本变更记录。

隐私与开源发布

发布到 GitHub 前请确认：

• .env、模型缓存、音频缓存、测试媒体、截图、生成字幕、运行日志没有进入 Git。
• 文档、脚本、测试样例只使用占位路径和占位文件名，不包含个人用户名、邮箱、网盘目录、真实影片名或本机绝对路径。
• 公开 Issue、PR 和日志前先脱敏，删除用户目录、完整媒体文件名、访问令牌、Cookie、鉴权头和第三方服务密钥。
• Git 作者邮箱适合公开，必要时使用 GitHub noreply 邮箱重新整理发布分支。
• 发布前至少用一段可公开的短视频完成端到端验证，不要使用受版权或隐私限制的媒体文件。

建议发布前额外执行：

git status --short --ignored
.\.venv\Scripts\python.exe -m pytest tests/test_open_source_hygiene.py -q

许可证

本项目使用 MIT License，详见 LICENSE。