README.md

---
title: VoiceClone TH API
emoji: 🎙️
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 8000
pinned: false
license: cc-by-4.0
---

# VoiceClone AI — Backend (โคลนเสียงจริง)

FastAPI + F5-TTS / XTTS-v2 ทำการโคลนเสียงจริงจากไฟล์ที่อัด แล้วส่งไฟล์ WAV กลับให้ frontend เล่น/ดาวน์โหลด

## เอนด์พอยต์ (ตาม PRD)

| Method | Path | หน้าที่ |
|---|---|---|
| GET  | `/api/v1/health` | สถานะ + เอนจินที่โหลด |
| POST | `/api/v1/voices` | อัปโหลดตัวอย่างเสียง (multipart: `sample`, `name`, `language`, `gender`, `ref_text`) → คืน `voice_id` |
| GET  | `/api/v1/voices` | รายการเสียง |
| POST | `/api/v1/generate` | `{voice_id, text, emotion, speed}` → คืน `{generation_id, audio_url}` |
| DELETE | `/api/v1/voices/{id}` | ลบเสียง |
| GET | `/files/audio/<id>.wav` | ไฟล์เสียงที่สร้าง |

## ติดตั้ง & รัน

```bash
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt      # f5-tts จะดึง torch มาด้วย (ใหญ่)
brew install ffmpeg                   # macOS (หรือ apt install ffmpeg)

./run.sh                              # หรือ: PYTHONHASHSEED=0 uvicorn app:app --port 8000 --reload
```

> ⚠️ ถ้าเชลล์ตั้ง `PYTHONHASHSEED` เป็นค่าว่าง จะทำให้ subprocess ของ torch crash —
> `run.sh` และ `app.py` จัดการให้แล้ว (ตั้งเป็น `0` อัตโนมัติ)

## ✅ เสียงไทยติดตั้งแล้ว (F5-TTS-THAI)

ดาวน์โหลด checkpoint ไทยไว้ที่ `backend/models/` เรียบร้อย:
- `models/model_1000000.pt` (~1.3 GB, 1,000,000 steps)
- `models/vocab.txt`

`tts_engine.py` ตรวจพบและใช้อัตโนมัติด้วยสถาปัตยกรรม `F5TTS_Base` →
`/api/v1/health` รายงาน `"engine":"F5-TTS-THAI"` และพูดไทยได้ชัด
(ทดสอบแล้ว: โหลดโมเดล ~8 วิ, สร้างเสียง ~20 วิ/ประโยค บน CPU)

เปิด frontend (`python3 -m http.server 8080` ที่โฟลเดอร์หลัก) — เมื่อ backend ออนไลน์
แอปจะขึ้นป้าย **"โคลนจริง"** อัตโนมัติ และการอัดเสียง/สร้างเสียงพูดจะใช้เสียงที่อัดจริง

> ถ้า backend ไม่ออนไลน์ หรือเอนจินยังไม่พร้อม → frontend สลับไปใช้ Web Speech ของเบราว์เซอร์เองโดยอัตโนมัติ (ไม่พัง)

## ภาษาไทย (F5-TTS-THAI)

F5-TTS ฐานหลักเก่งอังกฤษ/จีน สำหรับเสียงไทยให้โหลด checkpoint ไทย เช่น
[`VIZINTZOR/F5-TTS-THAI`](https://huggingface.co/VIZINTZOR/F5-TTS-THAI) แล้วตั้ง env:

```bash
export F5_CKPT_FILE=/path/to/model_thai.safetensors
export F5_VOCAB_FILE=/path/to/vocab.txt
uvicorn app:app --port 8000
```

เลือกเอนจินด้วย `TTS_ENGINE=f5|xtts|auto` (ค่าเริ่มต้น `auto`)

## หมายเหตุสำคัญ

- โมเดลโหลดแบบ lazy ครั้งแรกที่เรียก `/generate` (อาจรอสักครู่ตอน request แรก)
- ref_text = สคริปต์ที่ผู้ใช้อ่านตอนอัด (frontend ส่งมาให้อัตโนมัติ) ช่วยให้ F5-TTS โคลนแม่นขึ้น
- ต้องยืนยันความเป็นเจ้าของเสียง/ได้รับอนุญาตก่อนใช้งานเสมอ (frontend มีขั้นตอน consent แล้ว)