OmniVoice
Aperçu
Générez de l'audio localement via le serveur MCP OmniVoice Studio. Outils : generate_speech, list_voices, list_personalities, list_languages, check_health. Ressources : voice://{id}, history://recent.
Prérequis — Le backend doit être en cours d'exécution
Les outils MCP utilisent tous $OMNIVOICE_API_URL (par défaut http://localhost:3900). Si le backend est arrêté, chaque outil retourne une erreur de connexion. Installation + démarrage :
git clone https://github.com/debpalash/OmniVoice-Studio.git "$OMNIVOICE_HOME"
cd "$OMNIVOICE_HOME"
uv sync
VIRTUAL_ENV="$(pwd)/.venv" uv pip install 'mcp[cli]'
Puis :
scripts/check-health.sh # exit 0 si actif
scripts/start-backend.sh # démarre en arrière-plan (détection automatique MPS/CUDA)
Le premier appel de synthèse télécharge paresseusement le modèle k2-fsa/OmniVoice (~2,4 Go) depuis HuggingFace — mis en cache lors des démarrages suivants.
Index des tâches — Choisissez le bon outil
| Tâche | Outil | Notes |
|---|---|---|
| Vérifier que le backend est actif | check_health | Retourne `{"status":"ok","device":"mps |
| Texte → audio avec une voix enregistrée | generate_speech(text, profile_id) | Retourne WAV en base64. profile_id="demo0001" est la voix de démonstration fournie |
| Texte → audio sans clone (conception vocale) | generate_speech(text, instruct="…") | Omettez profile_id ; passez une instruct comme "narratrice chaleureuse d'âge moyen, rythme calme" |
| Narration multilingue | generate_speech(text, language="es") | Tout code ISO 639 ou "Auto" |
| Lister les voix existantes | list_voices | Retourne id, nom, type, personnalité |
| Lister les préréglages de personnalité | list_personalities | Retourne narrateur / décontracté / présentateur-radio / etc. avec leurs chaînes instruct |
| Lister les langues supportées | list_languages | 646 au total ; retourne 20 langues populaires + le nombre total |
Pour les décisions importantes (quel moteur utiliser, quand choisir OmniVoice plutôt que kokoro / Edge TTS / ElevenLabs), voir references/engines-comparison.md.
Pour les détails de câblage MCP, le cycle de vie du backend, le dépannage et un nettoyage complet, voir references/mcp-setup.md.
Workflows courants
1. Narration ponctuelle avec la voix de démonstration
# Appelé via le client MCP (votre agent le fera pour vous) :
result = generate_speech(
text="Bonjour — ici OmniVoice génère de la parole localement.",
profile_id="demo0001",
language="Français",
steps=16, # 8 = rapide/brouillon · 16 = équilibré · 32 = qualité
)
# result est un JSON avec audio_id, generation_time_s, audio_duration_s, format, wav_base64
Benchmark : 4,2 s d'audio en ~24 s côté serveur sur Apple Silicon MPS avec 16 étapes de diffusion.
2. Sauvegarder le WAV sur le disque et le lire
L'outil retourne un WAV PCM en base64 (16 bits, mono, 24 kHz). Décoder et écrire :
import base64, json
payload = json.loads(result_text) # analyser le JSON retourné par l'outil
open("out.wav","wb").write(base64.b64decode(payload["wav_base64"]))
Sur macOS : afplay out.wav. Convertir en MP3 avec ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3.
3. Clonage vocal — recette complète
Le clonage nécessite un extrait de référence de 3 à 10 secondes que le modèle utilisera comme plongement du locuteur. Le serveur MCP n'expose PAS la création de profil — il ne fait que lire les profils existants. Deux chemins pour en créer un :
Chemin A — script fourni (macOS, recommandé pour les nouveaux clones) :
scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1
# args : chemin_sortie durée_brute_sec index_micro
# index_micro par défaut = 1 (intégré MacBook) ; lister les périphériques via :
# ffmpeg -f avfoundation -list_devices true -i ""
Le script donne des signaux audibles de compte à rebours + début/fin via say de macOS + /System/Library/Sounds/Ping.aiff pour que l'utilisateur sache quand parler (la sortie terminal est tamponnée — les invites textuelles "parlez maintenant" arrivent trop tard). Il enregistre une fenêtre brute plus longue, puis la réduit à ~10 secondes de parole via silenceremove + atrim, la relit pour vérification et imprime la commande curl pour l'étape suivante.
Chemin B — manuel :
# 1. Enregistrer (mono, 24 kHz natif — correspond au taux interne du modèle)
ffmpeg -f avfoundation -i ":1" -t 12 -ac 1 -ar 24000 raw.wav
# 2. Supprimer le silence initial + prendre les 10 premières secondes de parole
ffmpeg -i raw.wav \
-af "silenceremove=start_periods=1:start_silence=0.05:start_threshold=-40dB,atrim=end=10" \
-ac 1 -ar 24000 ref.wav
# 3. Vérifier
ffmpeg -i ref.wav -af volumedetect -f null - 2>&1 | grep volume # max doit être > -20 dB
afplay ref.wav
POST vers /profiles (multipart/form-data — champs obligatoires : name, ref_audio) :
curl -X POST http://127.0.0.1:3900/profiles \
-F "name=clone-carlos" \
-F "[email protected]" \
-F "ref_text=Le texte exact prononcé dans l'extrait" \
-F "language=Français" \
| python3 -m json.tool
# retourne { "id": "abc12345", "name": "clone-carlos" }
Une fois créé, passez profile_id à generate_speech (via MCP) ou directement via POST /generate. Les profils persistent dans SQLite + fichiers audio de référence dans ~/Library/Application Support/OmniVoice/voices/<id>.<ext> (le backend préserve l'extension téléchargée — .wav si vous avez uploadé un WAV, .mp3 si MP3, etc.). L'état persiste entre les redémarrages du backend.
Conseils sur l'extrait de référence qui affectent matériellement la qualité :
| Facteur | Pourquoi c'est important |
|---|---|
| Locuteur unique | Des locuteurs mélangés brouillent le plongement |
| Parole claire, sans musique ni bruit | Le modèle intègre aussi le bruit |
| Prosodie naturelle (éviter les pangrammes) | Les échantillons de diffusion reproduisent la prosodie, pas seulement le timbre |
| 3 à 10 s est la zone idéale | < 3 s manque d'information ; > 10 s ajoute du calcul sans gain de qualité |
Faire correspondre ref_text à ce qui est dit | Améliore l'alignement, surtout sur les références bruyantes |
language correct | Une mauvaise langue → artefacts de transfert cross-lingue |
| Pic de volume ≥ -15 dB | Les références silencieuses fonctionnent mais se normalisent mal |
4. Conception vocale (sans extrait de référence)
Sautez profile_id ; fournissez une chaîne instruct décrivant la voix souhaitée :
generate_speech(
text="Bienvenue dans le futur des systèmes agentiques.",
instruct="narratrice chaleureuse d'âge moyen, rythme calme et autoritaire, style documentaire",
)
Obtenez des instructions préfabriquées via list_personalities et copiez celle correspondant au brief (narrateur, décontracté, présentateur-radio, etc.).
5. Doublage vidéo (interface web uniquement)
Le serveur MCP n'expose pas le point de terminaison de doublage. Le pipeline complet transcription → traduction → ré-voix → mixage se trouve derrière l'interface de bureau (bun run desktop dans $OMNIVOICE_HOME) et les routes REST /dub/*. Lorsque l'utilisateur demande de doubler une vidéo, orientez-le vers l'interface ; utilisez cette compétence uniquement pour les primitives de synthèse ci-dessus.
Quand NE PAS utiliser OmniVoice
- Narration rapide en anglais uniquement sur matériel faible →
kokoro-ttsest ~10× plus petit et 2× temps réel sur CPU (voir references/engines-comparison.md) - TTS ponctuel avec le moins de friction possible → Edge TTS ne nécessite ni installation ni backend
- Qualité la plus élevée possible quel que soit le coût → ElevenLabs reste leader pour la qualité de narration en anglais ; OmniVoice est à égalité ou meilleur pour le multilingue et le clonage
- Dictée en streaming temps réel → utilisez le widget de bureau OmniVoice (
⌘+⇧+Space), pas le serveur MCP
Ressources
- references/engines-comparison.md — Arbre de décision entre OmniVoice / kokoro / Voicebox / Edge TTS / ElevenLabs / API cloud
- references/mcp-setup.md — Câblage MCP, cycle de vie du backend, variables d'environnement, dépannage
- scripts/check-health.sh —
curl /health, exit 0/1 - scripts/start-backend.sh — Démarre uvicorn sur 127.0.0.1:3900 avec sonde de santé
- scripts/stop-backend.sh — Arrêt propre via
kill -TERMsur le PID lié - scripts/record-reference.sh — macOS uniquement : enregistrer + découper + vérifier un extrait de référence pour le clonage, avec des signaux audibles (
say+ bips système) qui contournent le tampon de sortie du terminal
Swagger / OpenAPI du backend : http://127.0.0.1:3900/docs (lorsque le backend est actif).
Amont : github.com/debpalash/OmniVoice-Studio — FSL-1.1-ALv2 (gratuit pour usage personnel/interne/non commercial ; se convertit automatiquement en Apache-2.0 deux ans après chaque publication).