PLAN.md

# PLAN — OmniSub (dịch SRT ZH→VI bằng Qwen3-Omni)

Tài liệu thiết kế chi tiết. Quyết định đã chốt: **cloud-first (Colab L4 24GB)**, **Qwen3-Omni 4-bit
làm tất cả** (nghe giọng + nhìn cảnh + dịch), **bỏ regex xưng hô** của bản cũ.

---

## 0. Quyết định đã chốt
- **Model**: `Qwen/Qwen3-Omni-30B-A3B-Instruct` (bản **Instruct**, 4-bit).
- **OCR sửa phụ đề cháy hình** (Bước 1, tùy chọn): **giữ lại nhưng MẶC ĐỊNH TẮT** (`correct_ocr: false`),
  bật khi cần qua config/CLI. Nguồn SRT hiện đã sạch.
- **Tên file ra**: giữ nếp cũ `*.vi.srt` (+ `*.vi.srt.report.json`).

## 1. Mục tiêu
1. Dịch SRT **Trung → Việt** tự nhiên, đúng văn nói, súc tích.
2. **Xưng hô đúng vai vế** nhờ:
   - **Nghe giọng**: ai đang nói (diarization) + giới/tuổi/cảm xúc/vai vế (Omni nghe trực tiếp).
   - **Nhìn ngữ cảnh**: frame video của cảnh đang dịch.
3. Nhất quán **tên riêng** và **cách xưng hô** xuyên suốt phim.
4. Phụ đề **vừa thời lượng** hiển thị (chars/giây, số dòng).

## 2. Bài học từ `Gemma-4` (giữ / bỏ)
**Giữ (port sạch):**
- `parse_srt`, `write_srt`, `subtitle_char_budget`, `_seconds_to_srt_time` — I/O SRT vững.
- `group_scenes`, `merge_adjacent_pairs` — gom cảnh, ghép cue vụn (sentence-aware, same-speaker).
- Pattern `chat_json` + `_extract_json` — parse JSON từ output model bền bỉ.
- Cấu trúc Colab + Google Drive (`Phim/`, `Cache/`).

**Bỏ / thay thế:**
- ❌ `RelationshipRegistry`, `_CJK_ROMANCE_RE`, `_CJK_FAMILY_RE`, `_VN_ANH_EM_RE`, `enforce_cue`
  (hàng trăm dòng regex khóa anh/em vs mẹ/con) → thay bằng **hồ sơ giọng + ngữ cảnh đa phương thức**.
- ❌ `estimate_speaker_demographics` (wav2vec2 age/gender) → Omni nghe hiểu trực tiếp.
- ❌ `_patch_speechbrain_lazy` (vá Windows) → Colab Linux không cần.
- 🔄 Gemma 4 12B (llama.cpp) → **Qwen3-Omni-30B-A3B** (transformers).

## 3. Kiến trúc & luồng 5 bước

```
INPUT: video.mp4 + video.srt (ZH)
                │
┌───────────────────────────────────────────────────────────────────────────────┐
│ Bước 1  Chuẩn bị SRT          srt.py + scenes.py                              │
│         parse → gom cảnh → ghép cue vụn → char budget                         │
│         [tùy chọn] OCR sửa phụ đề cháy hình (correct.py) — MẶC ĐỊNH TẮT     │
└───────────────────────────────────────────────────────────────────────────────┘
                │
┌───────────────────────────────────────────────────────────────────────────────┐
│ Bước 2  Phân tích người nói   diarize.py                                      │
│         pyannote community-1 → speaker turns → gán cue.speaker              │
└───────────────────────────────────────────────────────────────────────────────┘
                │
┌───────────────────────────────────────────────────────────────────────────────┐
│ Bước 3  Hồ sơ giọng           profiles.py                                     │
│         Qwen3-Omni nghe 3–5 clip/speaker → VoiceProfile                       │
│         {gender, age_range, emotion, role_guess, register_hint}               │
└───────────────────────────────────────────────────────────────────────────────┘
                │
┌───────────────────────────────────────────────────────────────────────────────┐
│ Bước 4  Dịch đa phương thức   translate.py + scene_context.py                 │
│         Qwen3-Omni: audio cảnh + frames + cues + profiles + glossary (partial)│
│         → bản dịch VN + ghi chú xưng hô                                       │
└───────────────────────────────────────────────────────────────────────────────┘
                │
┌───────────────────────────────────────────────────────────────────────────────┐
│ Bước 5  Hậu kiểm & xuất       glossary.py + srt.py                            │
│         nhất quán tên/xưng hô → fit thời lượng → ghi file                     │
└───────────────────────────────────────────────────────────────────────────────┘
                │
OUTPUT: video.vi.srt + video.vi.srt.report.json + glossary.json
```

| Bước | Module | Model | Mặc định |
|---|---|---|---|
| 1 — Chuẩn bị SRT | `srt.py`, `scenes.py`, `correct.py` | — / Omni (nếu bật OCR) | OCR **tắt** |
| 2 — Phân tích người nói | `diarize.py` | pyannote | bật |
| 3 — Hồ sơ giọng | `profiles.py` | Qwen3-Omni | bật |
| 4 — Dịch | `translate.py`, `scene_context.py` | Qwen3-Omni | bật |
| 5 — Hậu kiểm | `glossary.py` | — / Omni (rút gọn cue) | bật |

### Vì sao vẫn cần pyannote (Bước 2)
Qwen3-Omni hiện **chưa gán nhãn speaker ổn định** trên cả phim (xác nhận qua tài liệu kỹ thuật &
nghiên cứu HumanOmni-Speaker 2026 — cần adapter riêng). pyannote cho **nhãn nhất quán** để gắn
hồ sơ giọng (Bước 3) cho đúng người ở mọi cảnh.

### Vì sao một mô hình Omni cho Bước 3 & 4
Đưa **audio đoạn cảnh + frame + cue** cùng lúc → model "nghe" được tông giọng (ai đang nói với ai,
tình cảm hay gắt gỏng) và "thấy" bối cảnh → tự chọn xưng hô. Không còn luật cứng.

## 4. Module chi tiết (`src/omnisub/`)

| File | Trách nhiệm | Nguồn |
|---|---|---|
| `srt.py` | Dataclass `Cue`, parse/write SRT, char budget | Port từ bản cũ |
| `scenes.py` | `Scene`, `group_scenes`, `merge_adjacent_pairs` | Port, dọn lại |
| `diarize.py` | Wrapper pyannote → `SpeakerTurn`, gán `cue.speaker` | Port rút gọn |
| `correct.py` | Bước 1 — OCR sửa phụ đề cháy hình (**mặc định tắt**) | Port từ `correct_scene` cũ |
| `profiles.py` | ★ `VoiceProfile`; trích clip/speaker; gọi Omni nghe → hồ sơ | Mới |
| `scene_context.py` | Trích frame (ffmpeg), chọn audio đoạn cảnh | Port `extract_frame` + mới |
| `translate.py` | Dựng prompt đa phương thức/cảnh, gọi Omni, parse kết quả | Viết lại (bỏ regex) |
| `glossary.py` | ★ Nhất quán tên riêng + xưng hô theo dữ liệu (không regex) | Mới (thay NameRegistry) |
| `backends/base.py` | Interface `LLMBackend.chat_json(text, images, audio, …)` | Mới |
| `backends/transformers_qwen.py` | Qwen3-Omni qua HF transformers (Colab) | Mới |
| `pipeline.py` | Điều phối Bước 1→5, logging, progress, stop | Viết lại gọn |
| `cli.py` | Argparse CLI | Phỏng theo bản cũ |

### `VoiceProfile` (Bước 3) — cấu trúc đề xuất
```python
@dataclass
class VoiceProfile:
    speaker: str            # "SPEAKER_01" (khớp pyannote)
    gender: str             # nam | nữ | trẻ em | chưa rõ
    age_range: str          # trẻ em | thiếu niên | thanh niên | trung niên | lớn tuổi
    emotion_baseline: str   # vd: điềm đạm / nóng nảy / dịu dàng
    role_guess: str         # vd: "phụ nữ trẻ, có vẻ là người yêu của SPEAKER_02"
    register_hint: str      # gợi ý xưng hô VN: "nên dùng em với SPEAKER_02"
    evidence: str           # vì sao (model tự giải thích ngắn)
```
Hồ sơ này được nhét vào prompt dịch để Omni giữ xưng hô nhất quán theo từng nhân vật.

### Glossary (Bước 5) — thay regex bằng dữ liệu
- Thu thập **tên riêng** (token CJK lặp lại) → khóa **một** cách phiên âm VN, tái dùng (giữ ý tưởng
  `NameRegistry` cũ nhưng tách bạch, có thể chỉnh tay qua `glossary.json`).
- **Cặp xưng hô** giữa các speaker do **model đề xuất** (không hard-code), lưu vào glossary và đưa lại
  vào prompt các cảnh sau để khóa nhất quán — thay cho `RelationshipRegistry`.

## 5. Backend & mô hình (Colab L4 24GB)
- **Model**: `Qwen/Qwen3-Omni-30B-A3B-Instruct` (Bước 3 & 4).
- **Lượng hóa**: **4-bit** (bitsandbytes hoặc checkpoint AWQ/GPTQ Int4) → ~17–18GB, vừa L4 24GB
  (chừa chỗ cho KV cache + encoder audio/vision). *Cần kiểm tra checkpoint 4-bit sẵn có trên HF.*
- **Audio**: resample 16 kHz mono (đã có sẵn `extract_audio` bản cũ). Đưa audio **sau** text trong prompt
  (theo best practice Gemma/Qwen multimodal: ảnh trước text, audio sau text).
- **Vision**: frame trích bằng ffmpeg, đưa **trước** text.
- **Tham số sampling**: theo khuyến nghị Qwen (temperature ~0.7–1.0, top_p 0.95, top_k 64) — chốt khi test.
- **Drive**: cache model ở `Gemma/Cache/`, phim ở `Gemma/Phim/` (giữ nếp cũ).

## 6. Cấu hình (`config.yaml`)
```yaml
models:
  omni: "Qwen/Qwen3-Omni-30B-A3B-Instruct"
  quant: "4bit"
  diarize: "pyannote/speaker-diarization-community-1"
translate:
  source_lang: "Chinese"
  target_lang: "Vietnamese"
  chars_per_sec: 22
  max_line_chars: 52
  max_lines: 2
  correct_ocr: false        # Bước 1 — OCR sửa phụ đề cháy hình (mặc định tắt)
  output_suffix: ".vi.srt"  # giữ nếp cũ
scene:
  max_gap: 1.5
  max_cues: 4
  max_dur: 20.0
profiling:
  clips_per_speaker: 5
  max_seconds_per_clip: 8
paths:
  drive_root: "/content/drive/MyDrive/Gemma"
```

## 7. Lộ trình (milestones)
- **M1 — Bước 1 Chuẩn bị SRT**: scaffold thư mục, `srt.py`, `scenes.py`, `config.yaml`, `backends/base.py`.
  *Done khi*: parse SRT → gom cảnh → write SRT chạy được; `python -m omnisub.cli --help`.
- **M2 — Backend Omni (Colab)**: notebook tải Qwen3-Omni 4-bit; `chat_json` text-only; dịch thử 1 cảnh.- **M3 — Bước 2 Diarization**: port pyannote gọn; gán `cue.speaker`; xuất nhãn.
- **M4 — Bước 3 Voice Profiling ★**: `profiles.py` — Omni nghe clip → `VoiceProfile`.
- **M5 — Bước 4 Dịch đa phương thức**: `translate.py` ghép audio+frame+cue+profile; **không regex**.
- **M6 — Bước 5 Hậu kiểm**: nhất quán tên/xưng hô; fit timing; xuất `.vi.srt` + report JSON.
- **M7 — Tài liệu & hoàn thiện**: tinh chỉnh prompt, hoàn thiện README + notebook Colab.

## 8. Rủi ro & phương án
| Rủi ro | Phương án |
|---|---|
| Omni 4-bit không có checkpoint sẵn / chất lượng tụt | Thử AWQ Int4; nếu kẹt → tách: Qwen3-Omni nghe giọng + Qwen3-VL dịch |
| L4 24GB tràn VRAM khi kèm audio+vision dài | Giảm số frame/cảnh, cắt audio ≤ 8s/clip, giảm visual token budget |
| pyannote chậm với phim dài | Chỉ diarize tới `max(cue.end)`; cân nhắc NeMo Sortformer |
| Diarization gán sai người nói | Cho phép sửa tay nhãn speaker trước Bước 3 |
| Mất kết nối/ngắt phiên Colab giữa chừng | Cache theo cảnh, cho chạy lại từ cảnh dở; lưu kết quả ra Drive |

## 9. Quyết định (đã chốt — xem mục 0)
- ✅ Qwen3-Omni **`-Instruct`** 4-bit.
- ✅ OCR (Bước 1) **mặc định tắt** (`correct_ocr: false`), bật khi cần.
- ✅ Tên file ra **`.vi.srt`**.

### Việc cần kiểm tra trước M2
- Xác nhận có checkpoint **Qwen3-Omni-30B-A3B-Instruct 4-bit / AWQ Int4** trên Hugging Face.
  Nếu chưa có → phương án dự phòng: Qwen3-Omni (nghe giọng) + Qwen3-VL (dịch). (Xem mục 8.)