feat(dub): thêm giọng "My Review"; giọng clone chạy bằng trọng số mã hoá sẵn

Thêm my_review vào danh sách giọng có sẵn tiếng Việt (file mẫu my_review.wav).

Clone trong VieNeu = chạy codec-encoder trên wav mẫu để ra mảng ref_codes.
Bản cũ truyền ref_audio= nên việc này LẶP LẠI Ở MỖI DÒNG THOẠI. Đo thực tế:
my_review ~8,5s lần đầu (nạp session codec) rồi ~1,5s/dòng; adam ~27s lần đầu
— trong khi mảng codes chỉ 10-28 KB và không bao giờ đổi.

Nay mã hoá một lần rồi tái sử dụng, 3 tầng:
- Nhớ trong RAM theo (đường dẫn, mtime, cỡ file), có khoá vì synth_line chạy
song song nhiều luồng.
- File <wav>.v3turbo.codes.npy cạnh wav, sống qua cả lần khởi động lại. Hai
giọng preset đã có sẵn file này trong repo -> lần chạy đầu trên máy chủ
cũng không phải chờ mã hoá.
- Không có thì mới mã hoá, xong ghi lại cho lần sau (thư mục chỉ-đọc thì bỏ
qua, vẫn còn cache RAM).

Sidecar để git thường chứ không qua LFS: file chỉ 10-28 KB mà code đọc lúc
khởi động, LFS lỗi smudge sẽ thành file con trỏ. Mọi nhánh đều có đường lùi
về ref_audio nên hỏng sidecar/đổi engine cũng không gãy.

Đã kiểm: encode_reference gọi 0 lần khi dựng lại giọng, output tương đương
đường cũ. Bộ test 92/92 PASS.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitattributes

@@ -46,3 +46,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.webm filter=lfs diff=lfs merge=lfs -text
 *.otf filter=lfs diff=lfs merge=lfs -text
 *.ttf filter=lfs diff=lfs merge=lfs -text
+
+# Trọng số giọng clone (10-30 KB) — để git thường, KHÔNG qua LFS: code đọc
+# lúc khởi động, LFS lỗi smudge sẽ thành file con trỏ và phải clone lại từ đầu.
+*.codes.npy -filter -diff -merge binary

backend/app/assets/voices/vi/README.md

@@ -5,12 +5,29 @@ của phần Dịch/Đổi giọng (ngôn ngữ Việt). Model VieNeu sẽ **clo
 
 ## Đang khai báo sẵn
 
-| Tên hiện trên UI                        | id     | File cần thả (đặt đúng tên) |
-|-----------------------------------------|--------|-----------------------------|
-| Adam — nam, giọng trầm ấm       | `adam` | `adam.wav`                  |
+| Tên hiện trên UI                        | id          | File cần thả (đặt đúng tên) |
+|-----------------------------------------|-------------|-----------------------------|
+| Adam — nam, giọng trầm ấm       | `adam`      | `adam.wav`                  |
+| My Review — nữ, giọng review      | `my_review` | `my_review.wav`             |
 
 > Mục chỉ hiện khi file tương ứng đã tồn tại. Thiếu file → không hiện (tránh lỗi).
 
+## File `*.v3turbo.codes.npy` — trọng số giọng đã mã hoá sẵn
+
+Cạnh mỗi `.wav` có một file `<tên>.wav.v3turbo.codes.npy`. Đó là kết quả bước
+"clone" (codec-encoder chạy trên file mẫu) đã tính trước và commit vào repo, chỉ
+10–30 KB. Nhờ vậy TTS **không phải clone lại ở mỗi dòng thoại** — đo thực tế trên
+`my_review.wav`: ~8,5s lần đầu rồi ~1,5s mỗi dòng, `adam.wav` tới ~27s lần đầu.
+
+Thay file `.wav` thì **xoá luôn file `.npy`** tương ứng (hoặc để nguyên cũng
+được: code bỏ qua sidecar cũ hơn wav và tự mã hoá lại, xong ghi đè). Sinh lại bằng:
+
+```python
+import numpy as np, vieneu
+m = vieneu.Vieneu(mode="v3turbo")
+np.save("ten.wav.v3turbo.codes.npy", np.asarray(m.encode_reference("ten.wav"), dtype="int64"))
+```
+
 ## Yêu cầu file mẫu (để clone đạt chất lượng)
 
 - Định dạng: `.wav` (khuyến nghị) — 16–48 kHz, mono hoặc stereo đều được.
@@ -24,6 +41,9 @@ của phần Dịch/Đổi giọng (ngôn ngữ Việt). Model VieNeu sẽ **clo
    ```python
    "ten_id": ("Nhãn hiện trên UI", "ten_file.wav"),
    ```
+3. Nên sinh luôn file `.v3turbo.codes.npy` (xem mục trên) rồi commit cùng, để
+   lần chạy đầu tiên trên máy chủ không phải chờ mã hoá. Bỏ qua cũng chạy được
+   — code tự mã hoá lần đầu rồi ghi file cho những lần sau.
 
 ## Lưu ý về giọng "Adam"
 

backend/app/assets/voices/vi/my_review.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ff5e6d04cff39e9a971a7601fc419b1e168497c04f33cfd50e48391dba29e582
+size 304910

backend/app/services/dubber/tts.py

@@ -33,9 +33,15 @@ _ASSET_VOICE_DIR = os.path.normpath(
 _CLONE_PRESETS: dict[str, dict[str, tuple[str, str]]] = {
     "vi": {
         "adam": ("Adam — nam, giọng trầm ấm (clone)", "adam.wav"),
+        "my_review": ("My Review — nữ, giọng review (clone)", "my_review.wav"),
     },
 }
 
+# Đuôi file "trọng số giọng" đã mã hoá sẵn, nằm cạnh file wav mẫu.
+# Có gắn tên engine vì mã phụ thuộc codec của từng model — đổi engine thì
+# tên sidecar cũng khác, không ăn nhầm mã cũ.
+_REF_CODES_SUFFIX = ".v3turbo.codes.npy"
+
 
 def _clone_preset_path(lang: str, preset_id: str) -> str | None:
     """Trả đường dẫn file mẫu nếu preset_id là giọng clone-preset và file TỒN TẠI."""
@@ -200,10 +206,73 @@ class TTSEngine:
 # --------------------------------------------------------------- vi: VieNeu ---
 
 class VieNeuEngine(TTSEngine):  # pragma: no cover - cần model local
+    """VieNeu v3 Turbo. Giọng clone chạy bằng "trọng số" mã hoá sẵn, không clone lại.
+
+    Clone trong VieNeu = chạy codec-encoder trên file wav mẫu để ra mảng
+    `ref_codes` (T, 16). Bản cũ truyền thẳng `ref_audio=` nên VIỆC NÀY LẶP LẠI
+    Ở MỖI DÒNG THOẠI — đo trên my_review.wav: ~8.5s lần đầu (nạp session codec)
+    rồi ~1.5s/dòng, trong khi mảng codes chỉ 10 KB và không đổi.
+
+    Nay mã hoá 1 lần rồi tái sử dụng, 3 tầng từ rẻ đến đắt:
+      1. Nhớ trong RAM theo (đường dẫn, mtime, cỡ file) — hết trong 1 job.
+      2. File `<wav>.v3turbo.codes.npy` cạnh wav — sống qua cả lần khởi động lại.
+         Giọng preset (adam, my_review) có sẵn file này trong repo -> chạy phát
+         đầu tiên đã nhanh, không phải chờ mã hoá lần nào.
+      3. Không có thì mới mã hoá, xong ghi lại cho lần sau.
+    """
+
     def __init__(self):
         import vieneu  # type: ignore
+        import threading
         # v3turbo: 48 kHz, CPU chạy ONNX (nhẹ, real-time), không bắt buộc torch.
         self.model = vieneu.Vieneu(mode="v3turbo")
+        self._codes: dict[tuple, object] = {}
+        # synth_line chạy song song nhiều luồng (xem pipeline) -> khoá lại để
+        # cùng một mẫu không bị mã hoá mấy lần cùng lúc.
+        self._codes_lock = threading.Lock()
+        # Model không có encode_reference (mode khác) -> lùi về truyền ref_audio.
+        self._can_cache = hasattr(self.model, "encode_reference")
+
+    def _ref_codes(self, ref: str):
+        """Trọng số giọng của file mẫu `ref`. Không lấy được -> None (lùi ref_audio)."""
+        if not self._can_cache:
+            return None
+        try:
+            st = os.stat(ref)
+            key = (os.path.abspath(ref), st.st_mtime_ns, st.st_size)
+        except OSError:
+            return None
+
+        with self._codes_lock:
+            if key in self._codes:
+                return self._codes[key]
+
+            import numpy as np  # type: ignore
+            sidecar = ref + _REF_CODES_SUFFIX
+            codes = None
+            try:
+                # Chỉ nhận sidecar KHÔNG cũ hơn wav; wav thay mới thì mã hoá lại.
+                if os.path.exists(sidecar) and os.path.getmtime(sidecar) >= st.st_mtime:
+                    arr = np.load(sidecar)
+                    if arr.ndim == 2 and arr.size:
+                        codes = arr.astype("int64", copy=False)
+            except Exception as ex:
+                print(f"[tts] bỏ qua trọng số giọng hỏng {sidecar}: {ex}")
+
+            if codes is None:
+                try:
+                    codes = np.asarray(self.model.encode_reference(ref), dtype="int64")
+                except Exception as ex:
+                    print(f"[tts] mã hoá mẫu giọng lỗi ({ref}): {ex}")
+                    self._codes[key] = None
+                    return None
+                try:
+                    np.save(sidecar, codes)
+                except Exception:
+                    pass          # thư mục chỉ-đọc -> vẫn còn cache RAM, bỏ qua
+
+            self._codes[key] = codes
+            return codes
 
     def synth(self, text, out_wav, cfg):
         kw = {}
@@ -216,7 +285,11 @@ class VieNeuEngine(TTSEngine):  # pragma: no cover - cần model local
         # Ưu tiên mẫu upload/video; nếu preset là giọng clone-preset (vd Adam) -> clone file mẫu.
         ref = cfg.speaker_wav or _clone_preset_path(cfg.target_lang, cfg.preset)
         if ref:                                   # clone từ mẫu
-            audio = self.model.infer(text, ref_audio=ref, **kw)
+            codes = self._ref_codes(ref)
+            if codes is not None:                 # trọng số sẵn -> khỏi clone lại
+                audio = self.model.infer(text, ref_codes=codes, **kw)
+            else:
+                audio = self.model.infer(text, ref_audio=ref, **kw)
         else:                                     # giọng preset built-in (voice nhận tên str)
             audio = self.model.infer(text, voice=cfg.preset or None, **kw)
         self.model.save(audio, out_wav)           # ghi wav ở sample_rate của model