Blog-Audio

Blog Audio – Gemini TTS Narration für Blogbeiträge

Generiere professionelle Audio-Narrationen von Bloginhalten mit Googles Gemini TTS. Drei Modi: Zusammenfassung (200-300 Wörter gesprochene Übersicht), vollständiger Artikel-Vorlesemodus oder Zwei-Sprecher-Podcast-Dialog. 30 Stimmen, 80+ Sprachen, HTML5-Einbettung als Ausgabe.

Kurzreferenz

Befehl	Funktion
/blog audio generate <datei>	Audio-Narration eines Blogbeitrags erstellen
/blog audio voices	Verfügbare Stimmen mit Eigenschaften anzeigen
/blog audio setup	API-Key für Gemini TTS prüfen/konfigurieren

Voraussetzungen

• Python 3.11+ (venw wird automatisch von run.py verwaltet)
• GOOGLE_AI_API_KEY Umgebungsvariable (derselbe Schlüssel, der von blog-image verwendet wird)
• FFmpeg (für WAV-zu-MP3-Konvertierung; falls nicht vorhanden, wird auf WAV zurückgegriffen)

Immer den run.py-Wrapper verwenden

# RICHTIG:
python3 scripts/run.py generate_audio.py --text "..." --voice Charon --json

# FALSCH:
python3 scripts/generate_audio.py --text "..."  # Scheitert ohne venw

API-Key-Prüfung (Gate-Muster)

Vor der Audio-Generierung den API-Key prüfen:

echo $GOOGLE_AI_API_KEY

• Wenn gesetzt: Mit der Generierung fortfahren
• Wenn nicht gesetzt: Den Benutzer anleiten: „Für die Audio-Generierung wird ein Google AI API-Key benötigt. Holen Sie sich kostenlos einen unter https://aistudio.google.com/apikey und setzen Sie ihn: export GOOGLE_AI_API_KEY=ihr-key Dies ist derselbe Schlüssel, der von /blog image verwendet wird – wenn die Bildgenerierung funktioniert, funktioniert auch Audio.“
• Bei internem Aufruf (von blog-write): Im Hintergrund zurückkehren, wenn der Schlüssel fehlt. Niemals den Schreibworkflow blockieren.

Einrichtung

Für /blog audio setup:

1. Prüfen, ob GOOGLE_AI_API_KEY in der Umgebung gesetzt ist
2. Wenn blog-image konfiguriert ist (.mcp.json prüfen), ist der Schlüssel bereits verfügbar
3. Falls nicht, Benutzer zu https://aistudio.google.com/apikey führen
4. Mit einem Probelauf verifizieren: python3 scripts/run.py generate_audio.py --text "Test" --dry-run --json

Stimmenauswahl

Für /blog audio voices:

references/voices.md laden und den Stimmenkatalog dem Benutzer präsentieren.

Den Benutzer fragen, welche Stimme er bevorzugt, oder basierend auf dem Inhaltstyp empfehlen:

• Artikel-Narration: Charon (Informativ) oder Sadaltager (Wissend)
• Tutorial/Anleitung: Achird (Freundlich) oder Sulafat (Warm)
• Nachrichten/Analyse: Rasalgethi (Informativ) oder Schedar (Ausgeglichen)
• Lifestyle/Wellness: Aoede (Leicht) oder Vindemiatrix (Sanft)
• Dialog-Moderator: Puck (Schwungvoll) oder Laomedeia (Schwungvoll)
• Dialog-Experte: Kore (Bestimmt) oder Charon (Informativ)

Generierungs-Workflow

Für /blog audio generate <datei>:

Schritt 1: Blogbeitrag lesen

Die Datei lesen und extrahieren:

• Titel (aus H1 oder Frontmatter)
• Vollständiger Inhalt (Markdown-Text)
• Ungefähre Wortanzahl

Schritt 2: Modus wählen

Den Benutzer fragen (oder automatisch auswählen, wenn --mode angegeben):

Modus	Wann verwenden	Ausgabe
Zusammenfassung	Kurze Audio-Übersicht (1-2 Min.)	Gesprochene Zusammenfassung (200-300 Wörter)
Vollständig	Komplettes Vorlesen (5-15 Min.)	Vollständiger Artikel als natürliche Sprache
Dialog	Podcast-Stil (3-8 Min.)	Zwei-Personen-Gespräch über den Artikel

Schritt 3: Text vorbereiten

KRITISCH: Claude bereitet den Text vor. Das Skript führt nur TTS aus.

Zusammenfassungsmodus: Eine gesprochene Zusammenfassung des Artikels mit 200-300 Wörtern schreiben. Regeln:

• Als natürliche Sprache schreiben, nicht als geschriebener Text
• Mit der wichtigsten Erkenntnis oder Antwort des Artikels beginnen
• 3-5 Hauptaussagen abdecken
• Mit handlungsorientiertem Rat abschließen
• Kein Markdown, kein „In diesem Artikel…“, keine Meta-Kommentare
• Konversationelle Übergänge verwenden („Folgendes ist wichtig…“, „Die wichtigste Erkenntnis ist…“)

Vollständiger Modus: Den Markdown-Inhalt zu sauberem gesprochenem Text vereinfachen:

• Überschriften werden zu natürlichen Übergängen („Als nächstes betrachten wir…“)
• Links werden zu Klartext (URLs entfernen, Ankertext behalten)
• Bilder und Diagramme: weglassen oder kurz beschreiben („Wie die Daten zeigen…“)
• Codeblöcke: verbal beschreiben („Der Code verwendet eine For-Schleife, um…“)
• Listen: in natürliche Sätze umwandeln
• Frontmatter, Schema-Markup, HTML-Tags entfernen
• Kurze Einleitung hinzufügen: „Dies ist [Titel], veröffentlicht am [Datum].“

Dialogmodus: Ein Zwei-Personen-Gesprächsskript über den Artikel schreiben:

• Sprecher1 = Moderator (neugierig, stellt gute Fragen)
• Sprecher2 = Experte (kenntnisreich, gibt klare Antworten)
• Jede Zeile formatieren als: [Sprecher1] Was ist hier die wichtigste Erkenntnis?
• Die Hauptpunkte des Artikels gesprächig abdecken
• 15-25 Austausche (ergibt ~3-8 Minuten)
• Natürlich, nicht gestelzt („Das ist ein großartiger Punkt“ statt „In der Tat, wie die Forschung zeigt“)

Schritt 4: Stimme auswählen

Wenn der Benutzer eine Stimme gewählt hat, diese verwenden. Andernfalls basierend auf dem Modus empfehlen:

• Zusammenfassung/Vollständig: Standardmäßig Charon (Informativ)
• Dialog: Standardmäßig Puck (Moderator) + Kore (Experte)

Schritt 5: Audio generieren

Den vorbereiteten Text in eine temporäre Datei schreiben und dann aufrufen:

# Einzelstimme (Zusammenfassungs- oder Vollständig-Modus)
python3 scripts/run.py generate_audio.py \
  --text-file /tmp/blog_audio_prepared.txt \
  --voice Charon \
  --model flash \
  --output /pfad/zu/audio/beitrags-slug.mp3 \
  --json

# Zwei Stimmen (Dialogmodus)
python3 scripts/run.py generate_audio.py \
  --text-file /tmp/blog_audio_dialogue.txt \
  --voice Puck \
  --voice2 Kore \
  --model pro \
  --output /pfad/zu/audio/beitrags-slug-dialogue.mp3 \
  --json

Modellauswahl:

• flash (Standard): Schnell, günstig. Gut für Zusammenfassungen und standardmäßige Narration.
• pro: Höhere Qualität. Für Dialogmodus oder Premium-Inhalte verwenden.

Schritt 6: Ausliefern

Das Ergebnis dem Benutzer präsentieren:

1. Dateipfad – wo die Audiodatei gespeichert wurde
2. Dauer – menschenlesbar (z. B. „3:42“)
3. Einbettungscode – fertig zum Einfügen als HTML5-Audio-Tag
4. Kosten – geschätzte API-Kosten
5. Platzierungsvorschlag – wo die Einbettung im Blogbeitrag eingefügt werden soll

Einbettungsanleitung

Standard-HTML (Hugo, Jekyll, statische Seiten)

<audio controls preload="metadata">
  <source src="audio/beitrags-slug.mp3" type="audio/mpeg">
  Ihr Browser unterstützt das Audio-Element nicht.
</audio>

MDX (Next.js, Gatsby)

<audio controls preload="metadata">
  <source src="/audio/beitrags-slug.mp3" type="audio/mpeg" />
</audio>

WordPress

[audio src="audio/beitrags-slug.mp3"]

Platzierung

Den Audioplayer nach der Einleitung (unter der ersten H2) oder ganz oben im Artikel mit einer Beschriftung einfügen: „Diesen Artikel anhören“ oder „Audio-Version“.

Interne API (für blog-write)

Bei internem Aufruf von blog-write:

Eingabe:

• text: Vorbereiteter Text (bereits von Claude bereinigt)
• voice: Stimmenname (Standard: Charon)
• voice2: Zweite Stimme für Dialog (optional)
• model: flash oder pro
• output_path: Wo die Datei gespeichert werden soll

Ausgabe:

### Audio-Narration
- **Pfad:** /pfad/zu/audio/beitrags-slug.mp3
- **Dauer:** 3:42
- **Stimme:** Charon
- **Einbettung:** `<audio controls preload="metadata"><source src="audio/beitrags-slug.mp3" type="audio/mpeg"></audio>`

Sanfter Fallback: Wenn GOOGLE_AI_API_KEY nicht gesetzt ist, sofort ohne Fehler zurückkehren. Der Schreibworkflow wird ohne Audio fortgesetzt. Niemals blog-write blockieren, weil die Audio-Generierung nicht verfügbar ist.

Fehlerbehandlung

Fehler	Lösung
GOOGLE_AI_API_KEY nicht gesetzt	Schlüssel unter https://aistudio.google.com/apikey holen
FFmpeg nicht gefunden	Installieren: sudo apt install ffmpeg. Fallback auf WAV-Ausgabe.
Rate-Limit erreicht	Warten und erneut versuchen. Limits unter https://aistudio.google.com/rate-limit prüfen
Text zu lang (>32k Tokens)	In Abschnitte aufteilen, separat generieren
Unbekannter Stimmenname	/blog audio voices ausführen, um gültige Optionen zu sehen
API-Fehler	Schlüsselgültigkeit, Modellverfügbarkeit (Vorschaumodelle) prüfen
API-Key fehlt (interner Aufruf)	Lautlos zurückkehren – Schreibworkflow wird fortgesetzt

Referenzdokumentation

Bei Bedarf laden – NICHT alle beim Start laden:

• references/voices.md – Vollständiger 30-Stimmen-Katalog, Empfehlungen nach Inhaltstyp, Dialogpaarungen