README.md

---
license: apache-2.0
language:
  - vi
  - en
tags:
  - subtitles
  - srt
  - translation
  - gemma4
  - vision
  - llama.cpp
pipeline_tag: translation
library_name: gemma-srt-translate
---

# Gemma SRT Translate

Dịch và sửa phụ đề SRT bằng **Gemma 4 12B vision** (llama-server + MTP).  
Repo này chứa **script + notebook Colab**; model GGUF tải từ [`unsloth/gemma-4-12B-it-qat-GGUF`](https://huggingface.co/unsloth/gemma-4-12B-it-qat-GGUF).

## Cấu trúc repo

```
YOUR_USERNAME/gemma-srt-translate/
├── README.md                 ← file này
├── config.yaml               ← cấu hình mặc định
├── translate_srt.py          ← pipeline chính
├── diarize_audio.py          ← Pass 0: phân tích giọng nói (tùy chọn)
├── requirements-diarize.txt  ← dependency cho Pass 0
├── colab/
│   └── GemmaSRT_Colab.ipynb  ← chạy trên Google Colab (L4 24GB)
└── scripts/
    ├── download_models.py    ← tải GGUF từ Unsloth
    └── build_llama_server.sh ← build llama-server Linux (Colab)
```

## Chạy trên Google Colab (khuyến nghị L4 24GB)

Repo **Private** → **không** mở được bằng nút Open in Colab trên HF (lỗi 401).

**Cách mở:** tải [colab/GemmaSRT_Colab.ipynb](https://huggingface.co/STBack23/gemma-srt-translate/blob/main/colab/GemmaSRT_Colab.ipynb) → Colab **File → Upload notebook** → dán **`HF_TOKEN`** vào cell cấu hình → lưu copy lên Drive `Gemma/` để dùng lại.

Repo này nằm trên **Hugging Face**, không phải GitHub — link `colab.research.google.com/github/...` sẽ lỗi 404.

**Cách mở (chọn một):**

1. **Nút Open in Colab trên HF** (khuyến nghị):  
   [colab/GemmaSRT_Colab.ipynb](https://huggingface.co/STBack23/gemma-srt-translate/blob/main/colab/GemmaSRT_Colab.ipynb) → bấm **Open in Colab**

2. **Shortcut HF `/colab`**:  
   [https://huggingface.co/STBack23/gemma-srt-translate/colab](https://huggingface.co/STBack23/gemma-srt-translate/colab)

3. **Colab → File → Upload notebook** → tải file `.ipynb` từ HF về rồi upload

Sau khi mở notebook:

1. Runtime → **Change runtime type** → GPU **L4** (hoặc T4/A100)
2. Chạy tuần tự các cell (lần đầu ~15–20 phút: build llama-server + tải model)
3. Upload video + SRT hoặc trỏ vào Google Drive
4. Tải file `*.vi.srt` về máy

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://huggingface.co/STBack23/gemma-srt-translate/colab)

## Chạy trên máy local (Windows)

Repo HF **không** chứa `llama-server.exe` — dùng bản Windows trong project gốc:

```powershell
.\run-translate.ps1 -Video "phim.mp4" -InputSrt "phim.srt" -OutputSrt "phim.vi.srt"
```

Hoặc mở GUI: `GemmaSRT.bat`

## Tải model thủ công

```bash
pip install huggingface_hub
python scripts/download_models.py --dest ./models
```

File tải về (~12–15 GB):

| File | Mục đích |
|------|----------|
| `gemma-4-12B-it-qat-UD-Q4_K_XL.gguf` | Model chính |
| `mmproj-F16.gguf` | Vision projector |
| `mtp-gemma-4-12B-it.gguf` | MTP draft (tăng tốc) |

## Pipeline

1. Parse SRT → gom scene
2. **Pass 0** *(tùy chọn)*: phân tích giọng nói (pyannote) → "ai nói câu nào" + giới tính/độ tuổi → gán vào từng cue để xưng hô nhất quán
3. **Pass 1**: cắt frame (ffmpeg) → OCR/sửa SRT gốc (vision)
4. **Pass 2**: dịch theo ngữ cảnh + xưng hô
5. Ghi SRT dịch, SRT đã sửa, báo cáo JSON

### Pass 0 — phân tích giọng nói (diarization)

Bật bằng `--diarize` (CLI) hoặc `ENABLE_DIARIZE = True` (Colab). Cần thêm:

```bash
pip install -r requirements-diarize.txt
```

Token HF phải bấm **Agree** điều kiện các model gated:
[community-1](https://hf.co/pyannote/speaker-diarization-community-1) ·
[3.1](https://hf.co/pyannote/speaker-diarization-3.1) ·
[segmentation-3.0](https://hf.co/pyannote/segmentation-3.0).
`--gender-method model` dùng [audeering wav2vec2 age/gender](https://hf.co/audeering/wav2vec2-large-robust-24-ft-age-gender) (~1GB).

## VRAM

| GPU | 1 phim | 2 phim song song |
|-----|--------|------------------|
| RTX 4060 Ti 16GB | ✅ | ❌ |
| Colab L4 24GB | ✅ | ❌ (dùng local + Colab = 2 phim độc lập) |

## Cấu hình

Chỉnh `config.yaml` hoặc tham số CLI:

```bash
python translate_srt.py \
  --video phim.mp4 \
  --input-srt phim.srt \
  --output-srt phim.vi.srt \
  --target-lang Vietnamese \
  --skip-correction   # bỏ pass OCR (nhanh hơn)
```

## Model gốc

- [unsloth/gemma-4-12B-it-qat-GGUF](https://huggingface.co/unsloth/gemma-4-12B-it-qat-GGUF)
- [Gemma 4 license](https://ai.google.dev/gemma/docs/gemma_4_license)

## Upload repo lên Hugging Face

Xem [UPLOAD.md](./UPLOAD.md) (trong project gốc: `huggingface/UPLOAD.md`).