语言：简体中文 | 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 默认在本机处理文件。
| 能力 | 说明 |
|---|---|
| 多语言识别 | 支持自动识别，也可以手动指定常用语种。 |
| 时间轴对齐 | 使用本地强制对齐模型生成更贴近语音节奏的字幕时间轴。 |
| 本地推理 | 默认在本机运行模型，不调用 DashScope API，不依赖 qwen3-asr-toolkit。 |
| 批量处理 | GUI 支持多文件队列；CLI 支持单文件和目录批处理。 |
| 字幕后处理 | 自动去重、修复时间重叠、整理长行、清理 CJK 空格并重新编号。 |
| 预览字幕 | 识别过程中写入 movie.preview.srt，便于长视频先查看已完成片段。 |
| 本地 SRT 翻译 | 使用本地 HY-MT 翻译已有 SRT，支持多种翻译语言，并保留原编号和时间轴。 |
说明：项目公开名称不使用模型厂商商标；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 默认只显示文字，避免界面噪声。
推荐设置：
| 设置 | 默认值 | 建议 |
|---|---|---|
| 识别字幕语言 | 自动识别 | 不确定时保持默认；明确视频或音频里的说话语言时手动指定更稳定。 |
| 启用翻译 | 关闭 | 需要同时生成翻译语言字幕时再勾选；会保留原始字幕。 |
| 运行模式 | 推荐 | 显存不足时切换到低显存。 |
| 模型尺寸 | 1.7B | 质量优先用 1.7B；速度或显存优先用 0.6B。 |
| 音频分块 | 推荐（45 秒） | 识别不稳定时改为稳妥（30 秒）。 |
| 字幕样式 | 推荐 | 想让每条字幕更短时使用短句。 |
软件不调用第三方翻译 API，也不会自动上传字幕文件。主界面的“翻译已有 SRT”按钮会打开本地翻译窗口：
- 选择已有
.srt文件。 - 选择翻译语言，GUI 只展示识别与翻译共同支持的常用语种。
- 选择质量优先或快速轻量模式，开始翻译。
翻译逻辑只把字幕正文发给本地 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常用参数：
| 参数 | 说明 |
|---|---|
--model-size |
ASR 模型尺寸，默认 1.7B，可选 1.7B 或 0.6B。 |
--model |
自定义 ASR 模型路径或 Hugging Face ID；设置后覆盖 --model-size。 |
--aligner |
强制对齐模型路径或 Hugging Face ID。 |
--language |
识别语言，默认 auto；GUI 常用预设包括 English、Chinese、Japanese、Korean、Spanish、French、German 等，CLI 可传入模型支持的语言名。 |
-c, --context |
可选上下文提示，适合填写片名、角色名、人名、地名等具体词。 |
-d, --duration |
ASR 分块目标秒数，默认 45；低声、稀疏对白或识别为空时可改为 30。 |
--device |
推理设备，默认 auto；常用值为 auto、cuda:0、cpu。 |
--max-new-tokens |
每个音频块最大生成 token 数，默认 1536；长对白漏字时可临时调高。 |
--local-files-only |
只读取本地模型，不联网下载。 |
完整参数：
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
生成后会删除中间文件：
movie.raw.srt
movie.txt
AISRT 是面向个人使用的本地 AI 字幕生成工具，支持从视频或音频生成 .srt 字幕，也支持对已有 SRT 字幕做本地翻译。
常用工作流包括：视频转 SRT、音频转 SRT、多语言语音识别、字幕时间轴对齐、SRT 字幕翻译、GUI 多文件队列处理和 CLI 批量处理。
不会。AISRT 默认在本机运行 ASR、强制对齐和翻译模型，不调用云端翻译 API，也不会自动上传媒体、字幕或日志。
运行：
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 --checkWindows portable 包采用“轻量下载 + 首次启动自动安装依赖”的方式：ZIP 不包含 Python、PyTorch/CUDA 运行库、模型权重、FFmpeg、.venv、缓存、媒体、字幕、截图或日志，避免安装包体积失控。目标产物为：
dist/release/AiSRT-v0.1.4-windows-portable.zip
dist/release/aisrt-0.1.4-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。