CrossSubtitle-AI 技术需求与开发规划书
1. 项目愿景
CrossSubtitle-AI 的目标是打造一款 极简、高性能、完全本地优先 的视频转录与翻译工具，面向多语言视频内容生产场景，最终输出高质量字幕文件。

核心价值：

本地运行，保护音视频内容隐私
利用 AI PC 的 GPU / NPU / CoreML 加速，实现高吞吐推理
减少 Whisper 在静音、背景音、纯音乐场景下的“幻听”问题
支持全球主流语言识别，并稳定转换为中文或英文字幕
提供实时预览、可编辑、可导出的完整字幕工作流
2. 技术目标
2.1 功能目标
支持视频/音频文件导入
自动抽取音频并标准化预处理
基于 VAD 切分有效语音区间
执行本地 Whisper 转录/翻译
根据目标语言选择不同翻译策略
实时展示字幕生成进度
支持导出 SRT / ASS / VTT
2.2 非功能目标
启动快、包体小、资源占用可控
支持 macOS / Windows
推理链路可扩展，便于后续接入更多模型
模块解耦，便于替换 VAD、ASR、翻译后端
前后端通信稳定，可观察任务状态和错误信息
3. 技术栈选型
模块	技术选型	说明
表现层（UI）	Vue 3 + Vite + Tailwind CSS + Pinia	轻量、开发效率高、组件化好
容器层（Desktop）	Tauri v2 + Rust	包体小、性能高、系统能力强
音频处理	FFmpeg Sidecar	统一抽流与重采样
语音活动检测	Silero VAD + ONNX Runtime (ort)	过滤静音/噪声/纯音乐，提高识别质量
转录引擎	whisper-rs	本地推理，支持多平台硬件加速
翻译引擎	Whisper Native / OpenAI-compatible API / 本地 LLM	按目标语言动态选择策略
字幕导出	Rust 原生实现	统一输出 SRT / ASS / VTT
4. 系统架构设计
整体处理链路如下：

用户导入视频或音频文件
Rust 调用 FFmpeg 提取并转码为标准 PCM
VAD 模块分析音频，生成语音片段时间轴
Whisper 模块对片段执行转录或直译
若目标为中文，则进入 LLM 翻译链路
实时将结果推送给 Vue 前端展示
用户校对字幕并导出目标格式
5. 核心模块设计
5.1 音频预处理管线
输入
视频文件：mp4 / mkv / mov / avi
音频文件：mp3 / wav / m4a / flac
处理步骤
1. FFmpeg 抽流与标准化
统一转换为：

采样率：16kHz
位深：16bit
声道：mono
输出格式：PCM 或 WAV
建议命令逻辑：

ffmpeg -i input.mp4 -ac 1 -ar 16000 -f wav output.wav
2. PCM 解码与缓存
Rust 读取 WAV/PCM 数据，转换为：

Vec<f32>
采样值范围归一化至 [-1.0, 1.0]。

3. Silero VAD 检测
使用 ort 加载 silero_vad.onnx，输出语音片段：

Vec<(f32, f32)>
每个元组表示：

起始时间（秒）
结束时间（秒）
预期收益
跳过静音与非语音段
降低 Whisper 幻听概率
减少无效推理时长
提升整体处理速度
5.2 智能转录与翻译引擎
路由策略
路径 A：源语言 -> 英文
直接使用 Whisper 原生翻译能力：

task = translate
适用场景：

非英语语音转英文字幕
对实时性要求较高
尽量减少外部翻译调用
路径 B：源语言 -> 中文
分两步：

Whisper 转录原文
task = transcribe
将原文批量送入 LLM 翻译为中文
适用场景：

非英语内容转中文
需要更自然的语义表达
对专有名词、人称、上下文一致性要求更高
5.3 上下文关联翻译
为避免逐句翻译导致语义断裂，翻译模块采用 滑动窗口策略。

策略设计
每批发送 10~15 条字幕
携带上一批末尾若干条作为上下文
保留角色称呼、专有名词、代词指代一致性
示例结构
{
  "context": [
    "上一段末尾字幕1",
    "上一段末尾字幕2"
  ],
  "segments": [
    "当前待翻译字幕1",
    "当前待翻译字幕2"
  ]
}
目标
提升“你/您”“他/她”等代词一致性
减少断句错误
提高术语统一性
5.4 实时同步与前端预览
Rust 后端在每个阶段通过事件通知前端：

文件入队
抽流进度
VAD 进度
Whisper 推理进度
翻译进度
单条字幕产出
任务完成/失败
Tauri 事件建议：

window.emit("task:progress", payload)
window.emit("task:segment", payload)
window.emit("task:error", payload)
window.emit("task:done", payload)
前端 UI 应支持：

多文件任务队列
当前任务状态可视化
实时字幕流式展示
双栏对照编辑
时间戳定位
5.5 字幕导出模块
支持格式
SRT
ASS
VTT
输出要求
时间轴准确
支持多语言文本
保留编辑后的最终内容
ASS 可扩展样式配置
字幕数据结构建议统一为：

type SubtitleSegment = {
  id: string
  start: number
  end: number
  sourceText: string
  translatedText?: string
}
6. 数据流设计
建议建立统一任务模型：

type TaskStatus =
  | 'queued'
  | 'extracting'
  | 'vad_processing'
  | 'transcribing'
  | 'translating'
  | 'completed'
  | 'failed'
type SubtitleTask = {
  id: string
  filePath: string
  fileName: string
  sourceLang?: string
  targetLang: 'zh' | 'en'
  status: TaskStatus
  progress: number
  segments: SubtitleSegment[]
  error?: string
}
7. 模块划分建议
Rust 侧
audio.rs
负责：

调用 FFmpeg
管理音频抽取与格式标准化
输出 WAV/PCM 文件路径
vad.rs
负责：

加载 ONNX Runtime
执行 Silero VAD
返回语音时间片段
whisper.rs
负责：

加载 Whisper 模型
执行转录/翻译
汇报处理进度
translate.rs
负责：

对接 OpenAI-compatible API 或本地模型
管理上下文窗口翻译
返回中文结果
subtitle.rs
负责：

统一字幕结构
导出 SRT / ASS / VTT
task.rs
负责：

管理任务生命周期
协调各模块串联
向前端广播事件
Vue 侧
页面建议
文件拖拽上传页
任务队列面板
字幕预览与编辑面板
导出设置面板
Pinia Store 划分
useTaskStore
useSubtitleStore
useSettingsStore
8. 开发路线图
第一阶段：环境与音频引擎（Week 1）
Rust
集成 tauri-plugin-shell
打通 FFmpeg sidecar 调用
实现 audio.rs
实现 vad.rs 基础版本
Vue
搭建基础界面
实现多文件拖拽上传
建立任务队列状态管理
交付物
可导入文件
可抽取音频
可生成 VAD 时间片段
第二阶段：Whisper 推理核心（Week 1-2）
Rust
实现 whisper.rs
支持模型动态加载
支持 large-v3-turbo 及量化模型
加入平台加速检测逻辑
Vue
显示 VAD / 转录进度条
展示实时字幕输出
交付物
完整本地转录链路可跑通
前端实时看到字幕增量结果
第三阶段：翻译中枢（Week 2）
Rust
实现 translate.rs
对接 OpenAI-compatible 接口
实现滑动窗口翻译缓存
Vue
双栏字幕编辑器
支持原文/译文联动显示
点击时间戳跳转定位
交付物
中英目标语言翻译流程打通
具备可编辑字幕界面
第四阶段：优化与打包（Week 3）
性能
优化批处理与内存占用
Windows 侧尝试 Vulkan 加速
macOS 侧适配 CoreML
工程化
增加错误处理与日志
配置 Github Actions
自动构建 Windows / macOS 安装包
交付物
可分发桌面应用
基本可用的发布版本
9. 风险与关键问题
1. Whisper 幻听问题不能只靠模型解决
必须结合：

VAD 过滤
合理切片
静音抑制
长音频分段策略
2. 不同平台硬件加速差异较大
需要预留能力检测和回退机制：

可用 GPU/NPU 就启用
不可用时回退 CPU
前端明确提示当前推理模式
3. 翻译质量依赖上下文设计
中文输出质量主要取决于：

分批粒度
上下文拼接方式
专有名词缓存策略
4. 超长文件需要任务恢复与断点信息
后续可考虑：

中间结果缓存
崩溃恢复
已完成片段复用
10. 第一版 MVP 范围建议
为了尽快落地，建议第一版先做：

单文件处理
本地 Whisper 转录
VAD 过滤
英文直译 / 中文二段翻译
SRT 导出
简单实时预览
先不做：

视频预览播放器
ASS 高级样式编辑
批量复杂任务编排
云端模型管理
自动术语表
11. 给 Codex 的可执行 Prompt
模块 A：VAD 实现
请在 Rust 的 Tauri v2 项目中实现一个 `src-tauri/src/vad.rs` 模块，使用 `ort` 加载 Silero VAD ONNX 模型。输入为 `Vec<f32>` 格式的 16kHz 单声道音频采样，输出为 `Vec<(f32, f32)>`，表示检测到语音的开始和结束秒数。请封装成结构清晰、内存安全的 API，并处理模型初始化、推理失败和阈值配置。
模块 B：Whisper 命令封装
请基于 `whisper-rs` 为 Tauri v2 编写一个 Rust Command。命令接收 WAV 文件路径、源语言、目标语言和任务 ID。如果目标语言是英文，则使用 Whisper 的 `translate` 任务；否则使用 `transcribe`。处理过程中通过 `window.emit` 持续向前端发送进度事件和分段结果事件。请把实现拆分到 `src-tauri/src/whisper.rs`，并提供可复用的数据结构。
模块 C：翻译滑动窗口
请在 Rust 中实现 `src-tauri/src/translate.rs`，对接 OpenAI-compatible Chat Completions 接口。输入是一组带时间轴的字幕片段，目标是将原文翻译成中文。要求实现滑动窗口翻译：每批 10 到 15 条，并附带上一批末尾若干条作为上下文，以保证人称和术语一致。请返回结构化结果，并处理接口超时、重试和 JSON 解析失败。
模块 D：字幕导出
请在 Rust 中实现一个 `subtitle.rs` 模块，接收统一的字幕片段结构，支持导出为 SRT、VTT 和 ASS 三种格式。要求时间格式正确，支持多语言文本，并为 ASS 预留基础样式配置。