blog-audio

Blog Audio: Gemini TTS Narration for Blog Posts

Generate professional audio narration of blog content using Google's Gemini TTS. Three modes: summary (200-300 word spoken overview), full article read-aloud, or two-speaker podcast dialogue. 30 voices, 80+ languages, HTML5 embed output.

Quick Reference

Prerequisites

• Python 3.11+ (venv managed automatically by run.py)
• GOOGLE_AI_API_KEY environment variable (same key used by blog-image)
• FFmpeg (for WAV-to-MP3 conversion; falls back to WAV if missing)

Always Use run.py Wrapper

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

# WRONG:
python3 scripts/generate_audio.py --text "..."  # Fails without venv

API Key Check (Gate Pattern)

Before generating audio, check for the API key:

test -n "${GOOGLE_AI_API_KEY:-}" && echo "GOOGLE_AI_API_KEY is set" || echo "GOOGLE_AI_API_KEY is not set"

• If set: proceed with generation
• If not set: guide the user: "Audio generation requires a Google AI API key. Get one free at https://aistudio.google.com/apikey Then set it: export GOOGLE_AI_API_KEY=your-key This can be the same key used by /blog image, but it must be exported in the shell."
• When called internally (from blog-write): return silently if key is missing. Never block the writing workflow.

Setup

For /blog audio setup:

1. Check if GOOGLE_AI_API_KEY is set in environment
2. If blog-image uses project .mcp.json, confirm the referenced env var is exported
3. If not, guide user to https://aistudio.google.com/apikey
4. Verify with a dry run: python3 scripts/run.py generate_audio.py --text "Test" --dry-run --json

Voice Selection

For /blog audio voices:

Load references/voices.md and present the voice catalog to the user.

Ask the user which voice they prefer, or recommend based on content type:

• Article narration: Charon (Informative) or Sadaltager (Knowledgeable)
• Tutorial/how-to: Achird (Friendly) or Sulafat (Warm)
• News/analysis: Rasalgethi (Informative) or Schedar (Even)
• Lifestyle/wellness: Aoede (Breezy) or Vindemiatrix (Gentle)
• Dialogue host: Puck (Upbeat) or Laomedeia (Upbeat)
• Dialogue expert: Kore (Firm) or Charon (Informative)

Generation Workflow

For /blog audio generate <file>:

Step 1: Read the Blog Post

Read the file and extract:

• Title (from H1 or frontmatter)
• Full content (markdown body)
• Approximate word count

Step 2: Choose Mode

Ask the user (or auto-select if they specified --mode):

Step 3: Prepare Text

CRITICAL: Claude prepares the text. The script does TTS only.

Summary mode: Write a 200-300 word spoken summary of the article. Rules:

• Write as natural speech, not written text
• Open with the article's key finding or answer
• Cover 3-5 main takeaways
• Close with actionable advice
• No markdown, no "In this article...", no meta-commentary
• Use conversational transitions ("Here's what matters...", "The key finding is...")

Full mode: Strip the markdown content to clean spoken text:

• Headings become natural transitions ("Next, let's look at...")
• Links become plain text (remove URLs, keep anchor text)
• Images and charts: omit or briefly describe ("As the data shows...")
• Code blocks: describe verbally ("The code uses a for-loop to...")
• Lists: convert to natural sentences
• Remove frontmatter, schema markup, HTML tags
• Add brief intro: "This is [title], published on [date]."

Dialogue mode: Write a 2-person conversation script about the article:

• Speaker1 = Host (curious, asks good questions)
• Speaker2 = Expert (knowledgeable, gives clear answers)
• Format each line as: Speaker1: What's the key takeaway here?
• Cover the article's main points conversationally
• 15-25 exchanges (produces ~3-8 minutes)
• Natural, not stilted ("That's a great point" over "Indeed, as the research indicates")

Step 4: Select Voice

If the user chose a voice, use it. Otherwise, recommend based on mode:

• Summary/Full: default to Charon (Informative)
• Dialogue: default to Puck (Host) + Kore (Expert)

Step 5: Generate Audio

Write the prepared text to a temp file, then call:

# Single voice (summary or full mode)
python3 scripts/run.py generate_audio.py \
  --text-file /tmp/blog_audio_prepared.txt \
  --voice Charon \
  --model flash \
  --output /path/to/audio/post-slug.mp3 \
  --json

# Two voices (dialogue mode)
python3 scripts/run.py generate_audio.py \
  --text-file /tmp/blog_audio_dialogue.txt \
  --voice Puck \
  --voice2 Kore \
  --model pro \
  --output /path/to/audio/post-slug-dialogue.mp3 \
  --json

Model selection:

• flash (default): maps to gemini-3.1-flash-tts, good for summaries and standard narration.
• flash31: explicit alias for gemini-3.1-flash-tts.
• legacy-flash25: retained only for older compatibility.
• pro or legacy-pro25: maps to gemini-2.5-pro-preview-tts, use only when needed.

Step 6: Deliver

Present the result to the user:

1. File path: where the audio was saved
2. Duration: human-readable (e.g., "3:42")
3. Embed code: ready-to-paste HTML5 audio tag
4. Cost: estimated API cost
5. Placement suggestion: where to insert the embed in the blog post

Embedding Guide

Standard HTML (Hugo, Jekyll, static sites)

<audio controls preload="metadata">
  <source src="audio/post-slug.mp3" type="audio/mpeg">
  Your browser does not support the audio element.
</audio>

MDX (Next.js, Gatsby)

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

WordPress

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

Placement

Insert the audio player after the introduction (below the first H2) or at the very top of the article with a label: "Listen to this article" or "Audio version".

Internal API (for blog-write)

When invoked internally from blog-write:

Input:

• text: Prepared text (already cleaned by Claude)
• voice: Voice name (default: Charon)
• voice2: Second voice for dialogue (optional)
• model: flash or pro
• output_path: Where to save the file

Output:

### Audio Narration
- **Path:** /path/to/audio/post-slug.mp3
- **Duration:** 3:42
- **Voice:** Charon
- **Embed:** `<audio controls preload="metadata"><source src="audio/post-slug.mp3" type="audio/mpeg"></audio>`

Graceful fallback: If GOOGLE_AI_API_KEY is not set, return immediately with no error. The writing workflow continues without audio. Never block blog-write because audio generation is unavailable.

Error Handling

Reference Documentation

Load on-demand: do NOT load all at startup:

• references/voices.md: Full 30-voice catalog, recommendations by content type, dialogue pairings