# Pipeline Trích Xuất Audio Myanmar → Văn Bản Sạch

**Version:** 2.0 | **Date:** 2026-06-20 | **Author:** Panna (System Architect)  
**Cải tiến:** Thay Chirp+G4 bằng Gemini 3 Flash Preview direct transcribe (timestamped)

---

## 🎯 Mục tiêu

Chuyển đổi audio bài giảng Phật giáo tiếng Myanmar → TXT + SRT, 1 API call/chunk.

## 🏗️ Kiến trúc 4 Giai đoạn (đơn giản hóa từ v1)

```
┌──────────┐    ┌──────────┐    ┌──────────────┐    ┌──────────┐
│ G1: PREP │───▶│ G2: CHUNK│───▶│ G3: TRANSCRIBE│───▶│ G5: MERGE│
│ ffmpeg   │    │ 2-phút   │    │ Gemini Flash  │    │ TXT + SRT│
└──────────┘    └──────────┘    └──────────────┘    └──────────┘
```

### G1: PREPARE — Tiền xử lý Audio
- **Script:** `scripts/audio_preprocess.py`
- Chuẩn hóa → 16kHz Mono, compand filter, volume boost 2x
- Output: `output/<name>_clean.wav`

### G2: CHUNK — Chia nhỏ
- **Script:** `scripts/audio_chunk.py`
- Cắt block 2 phút (120s), overlap 0.3s
- Output: `output/chunks/<name>_chunk_XXX.wav`

### G3: TRANSCRIBE — Gemini Direct ⭐
- **Script:** `scripts/gemini_transcribe.py`
- **Model:** `google/gemini-3-flash-preview` qua **OpenRouter**
- **1 API call** → TXT + SRT (có timestamp)
- Prompt yêu cầu format: `[MM:SS.mmm] text`
- Chất lượng: giữ nguyên trợ từ, phân biệt từ đồng âm, timestamp chính xác
- Output: `output/transcripts/<name>_chunk_XXX_gemini.{txt,srt}`

### G5: ASSEMBLE — Ghép nối
- **Script:** `scripts/assemble_transcript.py`
- Merge TXT + SRT từ các chunk
- Output: `output/<name>_final.{txt,srt}`

## 💰 Chi phí (đã kiểm chứng)

| Giai đoạn | Model | Cost/batch | Tổng (52 phút) |
|-----------|-------|-----------|----------------|
| G1 | ffmpeg (local) | Free | Free |
| G2 | ffmpeg (local) | Free | Free |
| G3 | Gemini 3 Flash Preview | ~$0.005/chunk | **~$0.12** |
| G5 | Python (local) | Free | Free |

> **So với pipeline cũ:** Chirp STT ($1.25) + Gemini post-process ($0.22) = $1.47 → **Rẻ hơn ~12 lần, chất lượng cao hơn!**

## 🚀 Cách chạy

### Toàn bộ pipeline:
```bash
python3 scripts/pipeline_orchestrator.py 012.mp3 --name 012
```

### Từng bước:
```bash
# G1
python3 scripts/audio_preprocess.py 012.mp3 -o output/012_clean.wav

# G2 (2-phút chunks)
python3 scripts/audio_chunk.py output/012_clean.wav -d 120 -o output/chunks/

# G3 (cần OPENROUTER_API_KEY)
python3 scripts/gemini_transcribe.py output/chunks/ -o output/transcripts/

# G5
python3 scripts/assemble_transcript.py output/transcripts/ -o output/012_final.txt
```

## ⚙️ Environment

```bash
export OPENROUTER_API_KEY="sk-or-..."
```

## 📊 So sánh chất lượng

| Tiêu chí | Chirp RAW | Gemini Direct (v2) |
|----------|-----------|-------------------|
| "ထီးတောင်ဝှေး" | ❌ `ထိတောင်ငွေ` | ✅ Chuẩn |
| Trợ từ | Thiếu | ✅ Đầy đủ |
| Timestamp | Có (word-level) | ✅ Có (phrase-level, tự nhiên hơn) |
| SRT | Cần gen thêm | ✅ Tự động từ timestamp |
| API calls | 2 (Chirp + Gemini) | **1** |
| Cost/52ph | ~$1.47 | **~$0.12** |

## 📝 Bài học

- **Gemini 3 Flash Preview xử lý audio Myanmar xuất sắc** — hiểu ngữ cảnh sâu hơn Chirp STT thuần
- Timestamp dạng `[MM:SS.mmm]` trong prompt → Gemini trả về chính xác, không cần xử lý riêng
- 1 API call thay 2 → nhanh hơn, rẻ hơn, ít fail point