README.md

# OmniSub — Dịch phụ đề ZH→VI bằng Qwen3-Omni (đa phương thức)

Dịch và hiệu đính phụ đề SRT **Trung → Việt**, trong đó mô hình **nghe giọng nói thật** và
**nhìn ngữ cảnh video** để chọn **xưng hô** (anh/em, mẹ/con, tỷ/muội, ngài/ta…) cho đúng vai vế —
thay vì suy đoán bằng luật regex như bản cũ.

> Đây là bản viết lại, tối ưu từ dự án `Gemma-4`. Khác biệt chính: gom về **một họ Qwen**,
> dùng **Qwen3-Omni** nghe–nhìn–dịch trong cùng một mô hình, và **bỏ toàn bộ regex khóa quan hệ/xưng hô**.

## Vì sao đổi từ Gemma sang Qwen3-Omni
- **Dịch ZH→VI tốt hơn**: Qwen dẫn đầu benchmark tiếng Việt & tiếng Trung (SEA-HELM 2026).
- **Nghe hiểu giọng**: Qwen3-Omni nhận **text + ảnh + audio + video** natively, SOTA audio,
  cho biết giới tính/tuổi/cảm xúc/vai vế của người đang nói → neo xưng hô vào ngữ cảnh thật.
- **Đơn giản hóa**: một mô hình thay cho 3 stack rời (LLM + wav2vec2 + regex).

## Kiến trúc — 5 bước (cloud-first, Colab L4)
```
Video + SRT(ZH)
  ├─ Bước 1  Chuẩn bị SRT          parse, gom cảnh, ghép cue  [OCR: mặc định tắt]
  ├─ Bước 2  Phân tích người nói   pyannote → ai nói lúc nào
  ├─ Bước 3  Hồ sơ giọng           Qwen3-Omni nghe → VoiceProfile từng nhân vật
  ├─ Bước 4  Dịch đa phương thức   Qwen3-Omni: audio + frame + cue + hồ sơ → VN
  └─ Bước 5  Hậu kiểm & xuất       glossary + fit thời lượng → phim.vi.srt
```
Qwen3-Omni-30B-A3B đảm nhiệm **Bước 3 & 4** (nghe giọng, nhìn cảnh, dịch). pyannote dùng ở
**Bước 2** (gán nhãn người nói nhất quán — việc Omni chưa làm tốt natively).

## Phần cứng — chạy trên Colab
Qwen3-Omni 4-bit/AWQ khá nặng nên **toàn bộ pipeline chạy trên Colab**, không có nhánh chạy local.

| Nơi chạy | Cấu hình | Vai trò |
|---|---|---|
| **Colab** | GPU **A100 40GB** | Chạy Qwen3-Omni **AWQ Int4** chỉ thinker (~17GB) + pyannote — toàn bộ pipeline, không offload nên nhanh |

> Có thể chạy trên **L4 24GB** vì chỉ nạp thinker; A100 nhanh hơn rõ rệt do không phải offload.

## Trạng thái
🚧 Đang phát triển. Đã xong **M1 — Chuẩn bị SRT** (parse → ghép cue vụn → gom cảnh → xuất)
và bộ khung đầy đủ Bước 2–5 (diarization, hồ sơ giọng, dịch đa phương thức, hậu kiểm) cùng
backend Qwen3-Omni cho Colab. Chi tiết kiến trúc, module và lộ trình: xem [`PLAN.md`](PLAN.md).

## Cách dùng (Colab)
Mở [`colab/OmniSub_Colab.ipynb`](colab/OmniSub_Colab.ipynb) trên Colab (Runtime → L4) và chạy lần lượt các cell.
Cell cuối gọi pipeline tương đương:
```bash
python -m omnisub.cli run phim.srt --video phim.mp4 --backend qwen --config config.yaml
```
Kiểm tra nhanh Bước 1 (không nạp model) ngay trong Colab/môi trường có Python:
```bash
python -m omnisub.cli prepare samples/demo.zh.srt
```

## Cấu trúc thư mục
```
Gemma/
├── README.md / PLAN.md
├── pyproject.toml / requirements-colab.txt / config.yaml
├── src/omnisub/{srt,scenes,diarize,correct,profiles,scene_context,translate,glossary,pipeline,cli,config}.py
│   └── backends/{base,transformers_qwen}.py
├── colab/OmniSub_Colab.ipynb
└── samples/demo.zh.srt
```