lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

ElevenLabs TTS zu MP3

Konvertiert Skripttext in MP3-Sprachaufnahmen über die ElevenLabs Text-to-Speech-API.

Standardwerte

• Voice-ID: K7ewtjKRNtwwt3lKQ6M0 (Hoangs Markenstimme — gesperrt) — überschreibbar über ELEVENLABS_VOICE_ID-Umgebungsvariable oder --voice_id
• Modell: eleven_v3 (ausdrucksstärkstes Modell, unterstützt Audio-Tags wie [excited], [whisper], [laugh]; am besten für erzählende Inhalte) — überschreibbar über --model_id. Alternativ: eleven_multilingual_v2 (hohe Qualität, langsamer), eleven_turbo_v2_5 (schnell, leicht flach), eleven_flash_v2_5 (am schnellsten)
• Ausgabeformat: mp3_44100_128 (44,1 kHz / 128 kbps) — überschreibbar über --output_format
• Voice-Einstellungen: stability=0.5, similarity_boost=0.75, style=0, use_speaker_boost=true (ElevenLabs-Standard)
• Aussprachekarte: automatisch geladen aus assets/vn-pronunciation-map.json — deaktivieren mit --no-pronounce-map, oder auf eine andere Datei verweisen mit --pronounce-map pfad.json
• Zeichenlimit: 5000 pro Anfrage (ElevenLabs-Hardlimit). Text > 5000 Zeichen → Skript beendet sich mit Fehler und bittet Benutzer um manuelle Aufteilung.

Schnellverwendung

Aus Datei

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file pfad/zum/skript.txt \
  -o workspace/content/JJJJ-MM-TT/voiceover.mp3

Aus Inline-Text

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  "Xin chào các bạn, hôm nay mình chia sẻ về AI Agent" \
  -o workspace/assets/elevenlabs/beispiel.mp3

Eigene Stimme / Modell

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file skript.txt \
  --voice_id K7ewtjKRNtwwt3lKQ6M0 \
  --model_id eleven_turbo_v2_5 \
  -o ausgabe.mp3

Voice-Ausdruckskraft anpassen

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file skript.txt \
  --stability 0.4 \
  --similarity_boost 0.8 \
  --style 0.2 \
  -o ausgabe.mp3

Voice-Einstellungen — wann anpassen?

Einstellung	Bereich	Wirkung
stability	0.0–1.0	Höher = monotoner/vorhersagbarer; niedriger = emotionaler/variabler. 0.5 ist der Sweet Spot für Erzählungen. Auf 0.3–0.4 senken für lockere Hooks; auf 0.7+ erhöhen für formelle Erklärungen.
similarity_boost	0.0–1.0	Wie genau die Referenzstimme nachgeahmt wird. 0.75 Standard. In Richtung 0,9 erhöhen, wenn die Stimme "anders" als das Original klingt.
style	0.0–1.0	Stilübertreibung. 0 Standard. Fügt Latenz hinzu, wenn > 0. Nützlich (0.1–0.3) für ausdrucksstarke Inhalte.
use_speaker_boost	bool	Schärft die Sprecherähnlichkeit. Auf true lassen für konsistente Markenstimme.

Aussprachekarte (Englisch-Wort-Korrektur)

ElevenLabs-Mehrsprachenmodelle versuchen, den gesamten Text in der dominierenden Sprache zu lesen. In einem vietnamesischen Skript werden englische Wörter wie doc, chat, git wie vietnamesische Silben ausgesprochen und klingen falsch. Um dies zu beheben, ohne jedes Skript manuell zu bearbeiten, lädt das Skill automatisch eine ganzwortweise, groß-/kleinschreibungsunabhängige Ersetzungskarte aus assets/vn-pronunciation-map.json und wendet sie an, bevor der Text an die API gesendet wird.

Standardzuordnung:

{
  "doc": "đóc",
  "chat": "chát",
  "git": "gít"
}

So funktioniert es: Jeder Schlüssel wird groß-/kleinschreibungsunabhängig mit \b...\b-Grenzen abgeglichen und dann durch den vietnamesisch-phonetischen Wert ersetzt. Das Modell sieht "đóc" statt "doc" und spricht es nahe /dɒk/ aus. Dies betrifft nur das Audio — Ihr Quellskript bleibt sauber.

Wörterbuch kuratieren — zuerst anhören, dann hinzufügen:

• Führen Sie das Skill mit einem kurzen Testskript aus, das das Kandidatenwort enthält
• Wenn das Modell es bereits korrekt liest, fügen Sie es nicht hinzu (Überanpassung wird Dinge kaputt machen)
• Achten Sie auf Kollisionen: Das Hinzufügen von "code" würde auch das Code in Claude Code (Markenname) umschreiben → das niemals tun
• Bei Markennamen, die geschützt werden müssen, lassen Sie sie komplett weg

Überschreiben / Deaktivieren:

# Eigene Karte für ein spezifisches Projekt verwenden
uv run scripts/text_to_mp3.py --file s.txt --pronounce-map workspace/.../map.json -o out.mp3

# Ersetzung komplett überspringen
uv run scripts/text_to_mp3.py --file s.txt --no-pronounce-map -o out.mp3

Das Skript gibt jede angewendete Ersetzung auf stderr aus (z.B. 'doc' -> 'đóc' (4x)), damit Sie überprüfen können, was geändert wurde.

Arbeitsablauf

1. ELEVENLABS_API_KEY aus dem Projekt-.env laden
2. Text aus --file oder positionsabhängigem Argument lesen, Leerzeichen entfernen
3. Aussprachekarte anwenden (außer bei --no-pronounce-map) — ganzwortweise, groß-/kleinschreibungsunabhängige Ersetzung
4. len(text) <= 5000 validieren
5. POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}?output_format=mp3_44100_128
   • Header: xi-api-key: <key>, Content-Type: application/json, Accept: audio/mpeg
   • Body:

     {
       "text": "...",
       "model_id": "eleven_v3",
       "voice_settings": {
         "stability": 0.5,
         "similarity_boost": 0.75,
         "style": 0,
         "use_speaker_boost": true
       }
     }
     

6. Audio-Bytes direkt in die Ausgabe-MP3 streamen (keine Transcodierung nötig — Server gibt MP3 zurück)
7. output_path, size_mb, char_count, voice_id, model_id ausgeben

Ausgabekonvention

• Kurz/Test: workspace/assets/elevenlabs/<name>.mp3
• Videoproduktion: workspace/content/JJJJ-MM-TT/video-short/<projekt>/voiceover.mp3

Voraussetzungen

• ELEVENLABS_API_KEY im Projekt-.env (Header-Authentifizierung: xi-api-key)
• Optional ELEVENLABS_VOICE_ID in .env für eine andere Standardstimme
• Python-Abhängigkeiten via PEP 723 Inline-Metadaten (automatisch installiert durch uv run): requests, python-dotenv
• Kein ffmpeg nötig — ElevenLabs gibt MP3 direkt zurück

Warum keine Aufteilung in Stücke

ElevenLabs begrenzt Anfragen auf 5000 Zeichen. Das Skill schlägt fehl über diesem Limit anstatt automatisch aufzuteilen, weil:

• Eine einzelne Sprachaufnahme sollte ein kohärenter Block sein — eine Aufteilung mitten im Skript verursacht Prosodie-Sprünge an den Schnittstellen
• Der Inhalt des Benutzers (Hooks, kurze Skripte, Videosegmente) passt normalerweise gut unter 5000 Zeichen
• Wenn der Benutzer wirklich längeres Audio benötigt, sollte er das Skript semantisch (Absatzumbrüche) aufteilen und dieses Skill pro Block aufrufen, dann mit ffmpeg in seiner eigenen Pipeline zusammenfügen

API-Referenz

• Endpunkt: POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}
• Authentifizierung: xi-api-key: <api_key>-Header
• Modellkatalog: https://elevenlabs.io/docs/models
• Sprachkatalog (durchsuchen / Voice-IDs erhalten): https://elevenlabs.io/app/voice-library
• API-Dokumentation: https://elevenlabs.io/docs/api-reference/text-to-speech/convert
• Rate-Limits: abhängig vom Abonnement — siehe https://elevenlabs.io/pricing
• Ausgabeformate: mp3_44100_128 (Standard), mp3_44100_192 (höhere Qualität, nur kostenpflichtig), pcm_44100, ulaw_8000 (Telefonie)