# VRSub

为视频生成 **VR 双眼字幕**的单体应用：API、调度器与全部节点在同一进程内运行，
单仓库、单环境、单命令启动。由原分布式 WOV 多仓库合并而来。

用户上传视频，选择工作流，即可得到中文 `.srt` 与 VR 双目 `.ass` 字幕；
也可以按文件夹批量处理整个媒体库，产物直接落在视频旁。

## 快速开始

```bash
uv sync
uv run uvicorn wov_app.main:app --reload
```

访问：

```
http://127.0.0.1:8000/              应用中心（上传视频 → 字幕生成）
http://127.0.0.1:8000/tasks.html    任务管理
http://127.0.0.1:8000/batch.html    批量处理（按文件夹）
http://127.0.0.1:8000/admin.html    管理后台（工作流）
http://127.0.0.1:8000/workflow.html 工作流编排（DAG JSON）
http://127.0.0.1:8000/docs          API 文档
```

- 模型权重本地优先：把 whisper 模型放在 `model/faster-whisper-large-v2`
  （含 `model.bin`）即可完全离线运行。
- LLM 翻译默认使用 SiliconFlow，API Key 放在 gitignored 的 `.env`
  （`LLM_API_KEY=sk-...`），启动时自动加载。
- 环境变量全表与依赖管理见 [docs/configuration.md](./docs/configuration.md)。

## 文档导航

| 文档 | 内容 |
| --- | --- |
| [docs/architecture.md](./docs/architecture.md) | 目录结构、核心机制（registry/scheduler/前端）、北极星不变式、单体化说明 |
| [docs/node-protocol.md](./docs/node-protocol.md) | 节点输入输出协议表、字幕样式统一、模型权重解析、长音频分块、VLM OCR 并发、暂停断点、前端框选 |
| [docs/workflows.md](./docs/workflows.md) | 内置工作流一览、`_note_` 参数标注约定、decode_full 与幻觉清洗、切换模型、产物命名 |
| [docs/configuration.md](./docs/configuration.md) | 环境变量全表、启动方式、Python/uv 管理 |
| [docs/operations.md](./docs/operations.md) | 孤儿数据清理、任务暂停/继续、进度日志、文件夹批量处理 |
| [docs/testing.md](./docs/testing.md) | 测试结构（按模块目录组织）、测试资产归属、真实模型集成测试 |
| [docs/decisions.md](./docs/decisions.md) | 设计决策与踩坑记录（模型选型、glm-ocr 循环、帧号排序等） |
| [docs/代码审查问题跟踪.md](./docs/代码审查问题跟踪.md) | 缺陷清单 R01–R08、修复记录与验收标准 |
| [docs/待办-翻译上下文复用与语义纠错.md](./docs/待办-翻译上下文复用与语义纠错.md) | 待办：翻译上下文复用需求、ASR 听岔成句、已知坑与数据现状 |
| [docs/实验数据-字幕重生成成本与耗时.md](./docs/实验数据-字幕重生成成本与耗时.md) | 字幕重生成的成本/耗时/功率实测口径与全量推算 |
| [docs/实验数据-字幕审校定位与修复实验.md](./docs/实验数据-字幕审校定位与修复实验.md) | 字幕审校（定位+定向修复）的实测结果、成本与暂缓结论 |
| [docs/VR双目字幕景深与遮挡调查报告.md](./docs/VR双目字幕景深与遮挡调查报告.md) | VR 字幕景深/遮挡方案的调研全文 |
| [docs/调研-whisper漏句与decode_full验证.md](./docs/调研-whisper漏句与decode_full验证.md) | whisper 漏句与 decode_full 的实验记录 |
| [docs/adaptive_vad.md](./docs/adaptive_vad.md) | 每视频自适应 VAD 调参方案 |
| [docs/proper_nouns.md](./docs/proper_nouns.md) | 专有名词处理表 |

代理协作规则（TDD、提交许可、测试与注释规范、执行环境）见
[AGENTS.md](./AGENTS.md)，该文件只写规则、不含项目信息。

## 目录

| 路径 | 说明 |
| --- | --- |
| `src/wov_sdk/` | 协议数据模型（与分布式版兼容） |
| `src/wov_app/` | 应用层：API、注册表、调度器、批量引擎、数据库 |
| `nodes/` | 进程内节点实现（echo/ffmpeg/whisper/llm/vlm/ass/ocr/filter） |
| `manifests/` | 节点清单 JSON |
| `workflows/` | 默认工作流定义 JSON（模型与链路均为数据） |
| `web/` | 静态前端 |
| `model/` | 本地模型权重（gitignored） |
| `data/` | SQLite 与存储（gitignored） |
| `docs/` | 设计与运维文档 |
| `tests/` | 按模块组织的测试（见 [docs/testing.md](./docs/testing.md)） |

## 内置工作流

| ID | 名称 | 链路 |
| --- | --- | --- |
| `zh-direct` | 中文直出字幕 | 提音 → 中文转写 → ASS |
| `ocr-subtitle` | 字幕OCR提取 | 抽帧 → 逐帧 OCR → 汇总 SRT → LLM 过滤 |
| `learn-translate` | 学习资料转译+翻译字幕 | 提音 → 转写(decode_full) → LLM 翻译 → ASS |

链路细节与参数约定见 [docs/workflows.md](./docs/workflows.md)。

## 模型与实验结论摘要

- 默认 LLM 为 `Qwen/Qwen3.5-35B-A3B`（2026-09 切换）：对同片 2 小时日语 ASR 做
  8 个模型全量对比，质量与旧默认 `Qwen/Qwen3.6-35B-A3B` 持平，速度 0.232 s/行
  （全评测最快），评测报告见 `data/experiments/translate_models/REPORT.md`。
- `subtitle-correction` 节点**不跟随**该默认值，有意保留
  `Qwen/Qwen3.6-35B-A3B`：错听泛化实测新模型 0/4、旧模型 4/4。
- 通用转写模型为 `faster-whisper-large-v2`（2026-09 由 large-v3 切换），
  依据见 [docs/decisions.md](./docs/decisions.md#whisper-large-v2-vs-large-v3-切换)。
- `llm-filter` 节点的 LLM 五类分类层**默认关闭**（`use_llm=0`）：
  实测该层额外删除的 131 条中 56% 是真实对话，净收益为负；
  现只跑确定性规则层，误删真对话从 73 条降为 0 条且无 LLM 调用。
  详细依据见 [docs/decisions.md](./docs/decisions.md#llm-filter-的-llm-分类层默认关闭)。

## 测试

```bash
uv run pytest
```

测试资产与集成测试说明见 [docs/testing.md](./docs/testing.md)，
测试规则（TDD、真实数据要求）见 [AGENTS.md](./AGENTS.md#测试规则)。

## 与分布式版的关系

- 协议数据模型、工作流 DAG 数据化、调度拓扑执行保持不变。
- 已移除：子进程节点、节点 HTTP 协议、节点注册/实例管理、TTL 回收。
- 未来回退分布式时，只需为 `registry.invoke` 重新加上进程边界。
- 详见 [docs/architecture.md](./docs/architecture.md#单体化说明)。