crosssubtitle-ai/agent.md

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 采样值范围归一化至 [-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 预留基础样式配置。