214 lines
12 KiB
Markdown
214 lines
12 KiB
Markdown
# VOICE_ENROLLMENT_SPEC — conversion WAV → `.cvps` (clonage vocal CosyVoice)
|
|
|
|
> 🛑 **SUPERSEDED (23/06/2026) — CosyVoice retiré, remplacé par OmniVoice.**
|
|
> Cet algorithme (teacher CosyVoice3-0.5B → 4 tenseurs GGUF `.cvps`) **n'est plus
|
|
> utilisé**. L'enrôlement actuel = **OmniVoice** : `create_voice_clone_prompt` → binaire
|
|
> **`.ovsp`** (magic `OVSP` | T_ref | text_len | tokens[8·T_ref] | ref_text), cap réf
|
|
> **16 s**, ASR de réf via OmniVoice (plus de Whisper), venv **`ov_venv`**. Source de
|
|
> vérité : **`OMNIVOICE_VOICE_MIGRATION.md`** + `/opt/Kazeia-engine/dist/omnivoice/scripts/make_ovsp.py`.
|
|
> Le code `kazeia_central/voice/` est migré. Document conservé pour historique.
|
|
|
|
> **Destinataire : dev Kazeia-central.** Comment transformer un échantillon de voix
|
|
> (WAV) en artefact `.cvps` chargeable par le moteur TTS CosyVoice de l'app patiente.
|
|
>
|
|
> **Pourquoi côté PC (Kazeia-central) et pas sur la tablette** : l'enrôlement charge le
|
|
> **teacher CosyVoice3-0.5B complet en PyTorch (~9,1 Go)** et son *frontend*
|
|
> d'extraction. La tablette n'embarque que le `.gguf` distillé de **synthèse** (aucun
|
|
> frontend, aucune entrée JNI d'enrôlement). Porter ça on-device = shipper campplus +
|
|
> s3tokenizer + torch sur chaque device pour une opération one-shot → mauvais
|
|
> compromis. L'enrôlement est offline, opérateur, *enroll-once → sync N tablettes* :
|
|
> c'est le mandat de Kazeia-central (cf. `CLAUDE.md` §6).
|
|
|
|
---
|
|
|
|
## 1. Vue d'ensemble du workflow
|
|
|
|
```
|
|
[Tablette] [Kazeia-central / PC] [Flotte]
|
|
capture WAV (micro, ~15 s) ──adb pull──► enrôlement (cv_make_prompt) ──adb push──► <id>.cvps
|
|
+ pré-transcription Whisper = teacher 0.5B PyTorch dans .../cosyvoice/
|
|
(seed REF_TXT, relue opérateur) → 4 tenseurs → GGUF .cvps + maj catalogue
|
|
```
|
|
|
|
1. La tablette enregistre le clip de consentement (elle le fait déjà) et peut
|
|
**pré-transcrire avec son Whisper embarqué** pour pré-remplir le texte de référence.
|
|
2. Kazeia-central récupère le WAV + le texte (relu/corrigé par l'opérateur), lance
|
|
l'enrôlement, obtient `<id>.cvps`, le pousse vers les tablettes et met à jour le
|
|
catalogue voix (source de vérité des voix CosyVoice disponibles).
|
|
|
|
---
|
|
|
|
## 2. Référence : `cv_make_prompt.py` (l'algorithme exact)
|
|
|
|
Source : `/opt/Kazeia/cv_make_prompt.py` (et copie `/opt/Kazeia-engine/dist/cosyvoice/`).
|
|
|
|
```python
|
|
import sys, numpy as np, torch
|
|
sys.path.insert(0, "<COSYVOICE_REPO>")
|
|
sys.path.insert(0, "<COSYVOICE_REPO>/third_party/Matcha-TTS")
|
|
from cosyvoice.cli.cosyvoice import CosyVoice3
|
|
import gguf
|
|
|
|
REF, REF_TXT, OUT = sys.argv[1], sys.argv[2], sys.argv[3]
|
|
|
|
cv = CosyVoice3("<TEACHER_0.5B_DIR>", load_trt=False, fp16=False) # charge ~9,1 Go
|
|
fe = cv.frontend
|
|
text = open(REF_TXT).read().strip() if REF_TXT.endswith(".txt") else REF_TXT
|
|
|
|
feat, _ = fe._extract_speech_feat(REF) # mel prompt → [1, T, 80]
|
|
emb = fe._extract_spk_embedding(REF) # x-vector campplus → [1, dim]
|
|
tok, _ = fe._extract_speech_token(REF) # speech tokens s3 → [1, n]
|
|
|
|
feat = feat.squeeze(0).cpu().numpy().astype(np.float32) # [T, 80]
|
|
emb = emb.cpu().numpy().astype(np.float32) # [1, dim]
|
|
tok = tok.squeeze(0).cpu().numpy().astype(np.int32) # [n]
|
|
txt = np.frombuffer(text.encode("utf-8"), dtype=np.int8) # [bytes]
|
|
|
|
w = gguf.GGUFWriter(OUT, "cosyvoice-prompt-speech")
|
|
w.add_tensor("feat", feat) # mel prompt
|
|
w.add_tensor("embedding", emb) # x-vector
|
|
w.add_tensor("tokens", tok) # speech tokens
|
|
w.add_tensor("text", txt) # transcription UTF-8 brute
|
|
w.write_header_to_file(); w.write_kv_data_to_file(); w.write_tensors_to_file(); w.close()
|
|
```
|
|
|
|
Trois extractions du frontend (c'est *tout* le « clonage ») + écriture GGUF. Pas de
|
|
crc32, pas de check au chargement côté C++ → le format doit être exact.
|
|
|
|
---
|
|
|
|
## 3. Format `.cvps` (contrat avec le loader C++)
|
|
|
|
Conteneur **GGUF**, nom d'architecture **`"cosyvoice-prompt-speech"`**, **4 tenseurs**
|
|
(noms et dtypes **exacts** — le loader `nativeLoadVoice` ne tolère aucune dérive) :
|
|
|
|
| tenseur | contenu | shape (numpy) | dtype | note layout GGUF |
|
|
| --- | --- | --- | --- | --- |
|
|
| `feat` | mel prompt de la voix | `[T, 80]` | `float32` | GGUF inverse → `ne0=80, ne1=T` |
|
|
| `embedding` | x-vector campplus (empreinte locuteur) | `[1, dim]` | `float32` | `ne0=dim, ne1=1` |
|
|
| `tokens` | speech tokens s3 | `[n]` | `int32` | 1-D |
|
|
| `text` | transcription UTF-8 **brute** | `[octets]` | `int8` | 1-D, octets UTF-8 |
|
|
|
|
- `T` ∝ durée du clip ; `dim` fixé par campplus ; `n` = nb de tokens audio.
|
|
> **Le texte de référence est CONNU, pas à transcrire (décision 2026-06-19).** La
|
|
> personne lit toujours **la même phrase de consentement** (admin string
|
|
> `rec_reference_text`, nom interpolé). Donc `text` = cette phrase canonique (nom
|
|
> rempli), **pas** un résultat Whisper. Conséquence : `transcribe.py`/Whisper **sort
|
|
> du chemin critique** (fallback legacy seulement, pour des clips au contenu inconnu).
|
|
> Source de vérité = la string admin (idéalement portée par le `reference_text` du
|
|
> manifeste voix). Fenêtre d'enrôlement portée à **`CV_TARGET_S=22 s`** pour que la
|
|
> phrase de consentement (~13 s) + la fin phonétiquement riche entrent en entier.
|
|
|
|
- `text` est conditionnant (CosyVoice = *audio réf + texte réf → texte cible, même
|
|
voix*) : il **doit correspondre au contenu parlé** du WAV. Une transcription fausse
|
|
dégrade la similarité.
|
|
|
|
---
|
|
|
|
## 4. Entrées & contraintes
|
|
|
|
- **WAV de référence** : mono, PCM ; le frontend gère le ré-échantillonnage (fournir
|
|
≥16 kHz propre). **~15 s** = sweet spot (la similarité ECAPA/campplus monte avec la
|
|
longueur du prompt, mais le **cache K/V on-device ~270 Mo** et la latence du 1ᵉʳ
|
|
énoncé montent aussi). Éviter <8 s (similarité faible) et >~30 s (coût mémoire).
|
|
Clip propre, une seule voix, peu de bruit/musique.
|
|
- **Transcription** : texte exact de ce qui est dit, dans la **langue du clip**.
|
|
L'enrôlement est **cross-lingual** : un `.cvps` sert pour les 9 langues
|
|
(fr,en,de,es,it,ru,zh,ja,ko). La tablette peut la pré-générer (Whisper) ; **faire
|
|
relire/corriger par l'opérateur** avant enrôlement.
|
|
- **Sortie** : `<voiceId>.cvps`. `voiceId` = slug stable (`[a-z0-9_]`), c'est la clé de
|
|
cache moteur et le nom de fichier.
|
|
|
|
---
|
|
|
|
## 5. Dépendances hôte (poste Kazeia-central)
|
|
|
|
Lourdes mais one-time, sur le poste opérateur (local-first) :
|
|
|
|
| dépendance | détail | emplacement actuel (poste Richard) — **vérifié 2026-06-19** |
|
|
| --- | --- | --- |
|
|
| **interpréteur encodeur** | Python 3.10.20, torch 2.3.1+cu121 (CPU, `cuda=False`), `gguf` OK ; `from cosyvoice.cli.cosyvoice import CosyVoice3` résout | **`/opt/Kazeia/cv_venv/bin/python3`** |
|
|
| **repo CosyVoice** + `third_party/Matcha-TTS` | code `cosyvoice.cli.cosyvoice` | `/opt/Kazeia/cosyvoice-repo` (`requirements.txt` présent) |
|
|
| **teacher CosyVoice3-0.5B** | ~9,1 Go, modèles frontend (campplus, s3tokenizer, mel) | `/opt/Kazeia/_models_dl/cosyvoice3-0.5b` |
|
|
| package python `gguf` | écriture du conteneur | dans `cv_venv` |
|
|
| `cv_make_prompt.py` | le script | `/opt/Kazeia/cv_make_prompt.py` |
|
|
|
|
> **Env de référence confirmé** : `/opt/Kazeia/cv_venv` fait tourner l'encodeur
|
|
> (imports validés sans charger le teacher). C'est l'env à réutiliser/pointer depuis
|
|
> Kazeia-central (ou à recréer depuis `cosyvoice-repo/requirements.txt`).
|
|
>
|
|
> **Chemins device confirmés** (tablette dev, legacy) :
|
|
> - WAV source : `/data/local/tmp/kazeia/voix/voix/<id>.wav`
|
|
> - cible `.cvps` : `/data/local/tmp/kazeia/models/cosyvoice/<id>.cvps`
|
|
> (présents : `damien.cvps`, `elodie.cvps` — 242 720 o ≈ 15 s, refs de validation).
|
|
|
|
> ⚠️ Les chemins repo/teacher sont **codés en dur** dans `cv_make_prompt.py`. Pour
|
|
> Kazeia-central : **les rendre configurables** (env/config `CV_REPO`, `CV_TEACHER`) et
|
|
> documenter le pré-requis d'installation. Le teacher 9,1 Go n'est PAS versionné — le
|
|
> dev doit le provisionner sur le poste (pas dans le repo, pas dans l'APK).
|
|
|
|
---
|
|
|
|
## 6. Intégration dans Kazeia-central (module `voice/`)
|
|
|
|
**Recommandation forte : un worker d'enrôlement persistant, pas un `python` par voix.**
|
|
Charger le teacher 0.5B coûte plusieurs dizaines de secondes (9,1 Go) — relancer le
|
|
process à chaque voix est inacceptable pour un enrôlement de flotte. Garder le modèle
|
|
**chaud** et traiter une file.
|
|
|
|
Forme cible (Python natif à Kazeia-central, d'où le choix de stack) :
|
|
```
|
|
voice/
|
|
enroll.py # importe CosyVoice3 UNE fois ; expose enroll(wav_path, text, voice_id) -> cvps_path
|
|
worker.py # garde le teacher chaud ; file de jobs d'enrôlement
|
|
```
|
|
- **Préférer réimplémenter la logique** des 25 lignes de `cv_make_prompt.py` dans
|
|
`enroll.py` (mêmes 3 extractions + écriture GGUF) plutôt que de shell-out, pour
|
|
charger `CosyVoice3` une seule fois et enchaîner les voix.
|
|
- API exposée par Kazeia-central (cf. `CLAUDE.md` §6) :
|
|
1. `POST /api/voices/{serial}/capture` → déclenche/récupère le WAV de la tablette
|
|
(`adb pull` depuis `…/voix/voix/<id>.wav`), pré-transcription Whisper optionnelle.
|
|
2. `POST /api/voices/enroll` `{voice_id, wav, transcription}` → worker → `<id>.cvps`.
|
|
3. `POST /api/voices/{serial}/deploy` → `adb push` du `.cvps` dans
|
|
`<modelsDir>/cosyvoice/<id>.cvps` + (option) `rag_sync`/reload, ou publication
|
|
WebDAV + bump catalogue pour propagation OTA à la flotte.
|
|
|
|
---
|
|
|
|
## 7. Déploiement & runtime on-device (rappel, pour cohérence)
|
|
|
|
- Destination : `<modelsDir>/cosyvoice/<voiceId>.cvps`. Sur la tablette dev (legacy) :
|
|
`/data/local/tmp/kazeia/models/cosyvoice/` ; en prod : `Android/data/com.kazeia/files/kazeia/models/cosyvoice/`.
|
|
- Chargement : `CosyVoiceJni.nativeLoadVoice(handle, cvpsPath)`. Synthèse 24 kHz mono.
|
|
- 1ʳᵉ synthèse d'une voix = lente (remplit le cache K/V prompt ~270 Mo, RTF ~2) ; les
|
|
suivantes RTF 0,88. Cache par-voix (clé = identité du `.cvps`).
|
|
- **Repli** : si le `.cvps` demandé est absent, l'app retombe sur la voix par défaut
|
|
(`damien`) — une voix non enrôlée ne rend plus le TTS muet (fix 613c7ef). Mais
|
|
l'objectif de Kazeia-central est qu'**aucune voix proposée ne soit non déployée**.
|
|
|
|
---
|
|
|
|
## 8. À réconcilier (lié, hors enrôlement strict)
|
|
|
|
L'endpoint `/voices` de l'app patiente reflète l'**ancien inventaire Qwen3** (WAV +
|
|
`.bin`), pas les `.cvps` CosyVoice réellement présents → l'admin peut sélectionner une
|
|
voix muette (incident « zelda »). Kazeia-central, en devenant le maître de l'enrôlement
|
|
et du déploiement des `.cvps`, doit être la **source de vérité des voix CosyVoice
|
|
disponibles** (ce qui est enrôlé + déployé), et à terme pousser l'app à exposer son
|
|
inventaire `.cvps` réel. À traiter avec `PROVIDER_RPC_SPEC.md` (méthode `voices_reload`
|
|
+ futur endpoint d'inventaire `.cvps`).
|
|
|
|
---
|
|
|
|
## 9. Checklist dev Kazeia-central
|
|
|
|
- [ ] Provisionner sur le poste : repo CosyVoice + teacher 0.5B + `torch` + `gguf`.
|
|
- [ ] Rendre les chemins configurables (env/config), pas codés en dur.
|
|
- [ ] `voice/enroll.py` : charger `CosyVoice3` une fois ; `enroll(wav, text, id)→.cvps`
|
|
(3 extractions + GGUF arch `cosyvoice-prompt-speech`, 4 tenseurs §3, dtypes exacts).
|
|
- [ ] `voice/worker.py` : teacher chaud + file (pas de cold-load par voix).
|
|
- [ ] Routes capture / enroll / deploy (§6) + pré-transcription Whisper optionnelle.
|
|
- [ ] Valider un `.cvps` produit : taille proche de `damien.cvps` (~240 Ko pour ~15 s),
|
|
push device, synthèse de test non vide, écoute (similarité voix).
|
|
- [ ] Devenir la source de vérité de l'inventaire voix (§8).
|