Was macht OmniVoice?
Übersicht
Generiere Audio lokal über den OmniVoice Studio MCP-Server. Werkzeuge: generate_speech, list_voices, list_personalities, list_languages, check_health. Ressourcen: voice://{id}, history://recent.
Voraussetzungen – Backend muss laufen
Die MCP-Werkzeuge greifen alle auf $OMNIVOICE_API_URL zu (Standard: http://localhost:3900). Wenn das Backend nicht läuft, liefert jedes Werkzeug einen Verbindungsfehler. Installation + Start:
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]'
Dann:
scripts/check-health.sh # exit 0 wenn verfügbar
scripts/start-backend.sh # Start im Hintergrund (MPS/CUDA automatisch erkannt)
Der erste Synthese-Aufruf lädt das Modell k2-fsa/OmniVoice (~2,4 GB) von HuggingFace herunter – bei späteren Starts gecacht.
Aufgabenindex – Das richtige Werkzeug wählen
| Aufgabe | Werkzeug | Hinweise |
|---|---|---|
| Backend-Verfügbarkeit prüfen | check_health | Gibt `{"status":"ok","device":"mps |
| Text → Audio mit einer gespeicherten Stimme | generate_speech(text, profile_id) | Gibt Base64-WAV zurück. profile_id="demo0001" ist die mitgelieferte Demo-Stimme |
| Text → Audio ohne Klon (Stimmdesign) | generate_speech(text, instruct="…") | profile_id weglassen; instruct wie "warmherzige, mittelalte weibliche Erzählerin, ruhiges Tempo" übergeben |
| Mehrsprachige Erzählung | generate_speech(text, language="es") | Beliebiger ISO-639-Code oder "Auto" |
| Vorhandene Stimmen auflisten | list_voices | Gibt ID, Name, Typ, Persönlichkeit zurück |
| Persönlichkeitsvorlagen auflisten | list_personalities | Gibt Erzähler / Lässig / Nachrichtensprecher / usw. mit ihren instruct-Zeichenketten zurück |
| Unterstützte Sprachen auflisten | list_languages | Insgesamt 646; gibt 20 beliebte + die Gesamtzahl zurück |
Für komplexere Entscheidungen (welche Engine verwenden, wann OmniVoice gegenüber kokoro / Edge TTS / ElevenLabs wählen) siehe references/engines-comparison.md.
Für MCP-Verdrahtungsdetails, Backend-Lebenszyklus, Fehlerbehebung und eine saubere Deinstallation siehe references/mcp-setup.md.
Häufige Workflows
1. Einmalige Erzählung mit der Demo-Stimme
# Wie durch den MCP-Client aufgerufen (Ihr Agent führt dies für Sie aus):
ergebnis = generate_speech(
text="Hallo – dies ist OmniVoice, das Sprachausgabe lokal generiert.",
profile_id="demo0001",
language="German",
steps=16, # 8 = schnell/Entwurf · 16 = ausgewogen · 32 = Qualität
)
# Ergebnis ist JSON mit audio_id, generation_time_s, audio_duration_s, format, wav_base64
Benchmark: 4,2 s Audio in ~24 s serverseitig auf Apple Silicon MPS bei 16 Diffusionsschritten.
2. WAV auf Festplatte speichern und abspielen
Das Werkzeug gibt Base64-PCM-WAV (16 Bit, Mono, 24 kHz) zurück. Dekodieren + Schreiben:
import base64, json
payload = json.loads(ergebnis_text) # JSON parsen, das das Werkzeug zurückgibt
open("out.wav","wb").write(base64.b64decode(payload["wav_base64"]))
Auf macOS: afplay out.wav. In MP3 konvertieren mit ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3.
3. Stimmklonung – Komplettlösung
Für die Klonung wird ein 3-10 Sekunden langes Referenzclip benötigt, das das Modell als Sprecherembedding verwendet. Der MCP-Server bietet KEINE Profilerstellung – er liest nur vorhandene Profile. Zwei Wege zur Erstellung:
Weg A – Mitgeliefertes Hilfsskript (macOS, empfohlen für neue Klone):
scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1
# Argumente: Ausgabepfad raw_duration_sec mic_index
# Standard mic_index=1 (MacBook eingebaut); Geräte auflisten via:
# ffmpeg -f avfoundation -list_devices true -i ""
Das Skript gibt hörbare Countdown + Start/Stopp-Signale über macOS say + /System/Library/Sounds/Ping.aiff aus, damit der Benutzer weiß, wann er sprechen soll (Terminal-Stdout ist gepuffert – Text-Prompts „Jetzt sprechen" kommen zu spät). Es zeichnet ein längeres Rohfenster auf, trimmt dann auf ~10 Sekunden Sprache via silenceremove + atrim, spielt es zur Überprüfung ab und gibt den nächsten curl-Befehl aus.
Weg B – Manuell:
# 1. Aufnahme (Mono, 24 kHz nativ – entspricht der internen Rate des Modells)
ffmpeg -f avfoundation -i ":1" -t 12 -ac 1 -ar 24000 raw.wav
# 2. Stille am Anfang entfernen + die ersten 10 Sekunden Sprache nehmen
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. Überprüfen
ffmpeg -i ref.wav -af volumedetect -f null - 2>&1 | grep volume # max sollte > -20 dB
POST an /profiles (multipart/form-data – erforderliche Felder: name, ref_audio):
curl -X POST http://127.0.0.1:3900/profiles \
-F "name=carlos-klon" \
-F "[email protected]" \
-F "ref_text=Der genaue Text, der im Clip gesprochen wurde" \
-F "language=German" \
| python3 -m json.tool
# gibt zurück { "id": "abc12345", "name": "carlos-klon" }
Nach der Erstellung profile_id an generate_speech übergeben (via MCP) oder direkt via POST /generate. Profile bleiben in SQLite + Referenz-Audiodateien erhalten unter ~/Library/Application Support/OmniVoice/voices/<id>.<ext> (das Backend behält die hochgeladene Erweiterung bei – .wav, wenn Sie eine WAV hochgeladen haben, .mp3 bei MP3 usw.). Der Zustand bleibt über Backend-Neustarts hinweg erhalten.
Tipps für Referenzclips mit spürbarem Einfluss auf die Qualität:
| Faktor | Warum es wichtig ist |
|---|---|
| Ein einzelner Sprecher | Gemischte Sprecher verwischen das Embedding |
| Saubere Sprache, keine Musik/Geräusche | Das Modell embeddet auch das Rauschen |
| Natürliche Prosodie (Pangramme vermeiden) | Diffusionsproben replizieren die Prosodie, nicht nur die Klangfarbe |
| 3-10 Sekunden ist der optimale Bereich | < 3 s hat zu wenig Information; > 10 s erhöht Rechenaufwand ohne Qualitätsgewinn |
ref_text mit dem Gesprochenen abgleichen | Verbessert die Ausrichtung, besonders bei verrauschten Referenzen |
language korrekt | Falsche Sprache → cross-linguale Transfer-Artefakte |
| Lautstärkespitze ≥ -15 dB | Leise Referenzen funktionieren, aber normalisieren schlecht |
4. Stimmdesign (ohne Referenzclip)
profile_id weglassen; stattdessen eine instruct-Zeichenkette mit der gewünschten Stimme übergeben:
generate_speech(
text="Willkommen in der Zukunft von agentischen Systemen.",
instruct="warmherzige, mittelalte weibliche Erzählerin, ruhiger autoritativer Ton, Dokumentationsstil",
)
Vorgefertigte Anleitungen gibt es via list_personalities – kopieren Sie die passende zur Aufgabenstellung (Erzähler, Lässig, Nachrichtensprecher, usw.).
5. Videosynchronisation (nur Web-UI)
Der MCP-Server stellt den Synchronisationsendpunkt nicht bereit. Die vollständige Pipeline (Transkribieren → Übersetzen → Neu vertonen → Multiplexen) läuft hinter der Desktop-Oberfläche (bun run desktop in $OMNIVOICE_HOME) und den /dub/* REST-Routen. Wenn der Benutzer nach Videosynchronisation fragt, verweisen Sie ihn auf die UI; nutzen Sie dieses Skill nur für die oben genannten Synthese-Grundfunktionen.
Wann OmniVoice NICHT verwendet werden sollte
- Schnelle englischsprachige Erzählung auf schwacher Hardware →
kokoro-ttsist ~10× kleiner und 2× Echtzeit auf CPU (siehe references/engines-comparison.md) - Hürdenärmste einmalige TTS → Edge TTS benötigt keine Installation oder Backend
- Höchstmögliche Qualität unabhängig von den Kosten → ElevenLabs hat bei englischer Erzählungsglätte noch die Nase vorn; OmniVoice liegt gleichauf oder übertrifft bei Mehrsprachigkeit + Klonung
- Echtzeit-Streaming-Diktat → das OmniVoice Desktop-Widget verwenden (
⌘+⇧+Space), nicht den MCP-Server
Ressourcen
- references/engines-comparison.md – Entscheidungsbaum zwischen OmniVoice / kokoro / Voicebox / Edge TTS / ElevenLabs / Cloud-APIs
- references/mcp-setup.md – MCP-Verdrahtung, Backend-Lebenszyklus, Umgebungsvariablen, Fehlerbehebung
- scripts/check-health.sh –
curl /health, exit 0/1 - scripts/start-backend.sh – uvicorn auf 127.0.0.1:3900 mit Gesundheitsprüfung starten
- scripts/stop-backend.sh – Sauberes Herunterfahren via
kill -TERMauf die gebundene PID - scripts/record-reference.sh – Nur macOS: Referenzclip für Klonung aufnehmen + trimmen + überprüfen, mit hörbaren Signalen (
say+ Systemklänge), die die Terminal-Pufferung umgehen
Backend Swagger / OpenAPI: http://127.0.0.1:3900/docs (wenn Backend läuft).
Upstream: github.com/debpalash/OmniVoice-Studio – FSL-1.1-ALv2 (kostenlos für private/interne/nicht-kommerzielle Nutzung; konvertiert zwei Jahre nach jedem Release automatisch zu Apache-2.0).