# Blog Audio

> Genera narración en audio de posts con Google Gemini TTS: resumen hablado, lectura completa o diálogo tipo pódcast a dos voces, con 30 voces y salida MP3 más el código de inserción HTML5.

Fuente: https://skillsagentes.com/skills/agricidaniel/claude-blog/blog-audio
Markdown: https://skillsagentes.com/skills/agricidaniel/claude-blog/blog-audio.md

Repositorio: https://github.com/AgriciDaniel/claude-blog
Autor: AgriciDaniel
Licencia: MIT
Actualizado: hace 19 días
Coste de contexto: 129 tok instalada, 2.2k tok al activarse, 21.4k tok con todos los archivos del bundle
Bundle: 8 archivos, 84 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add AgriciDaniel/claude-blog --skill blog-audio --agent claude-code
# Cursor
npx -y skills add AgriciDaniel/claude-blog --skill blog-audio --agent cursor
# Codex
npx -y skills add AgriciDaniel/claude-blog --skill blog-audio --agent codex
# Gemini CLI
npx -y skills add AgriciDaniel/claude-blog --skill blog-audio --agent gemini
# Windsurf
npx -y skills add AgriciDaniel/claude-blog --skill blog-audio --agent windsurf
# Cline
npx -y skills add AgriciDaniel/claude-blog --skill blog-audio --agent cline
```

## Qué hace

- Prepara el texto hablado (resumen de 200-300 palabras, lectura completa limpia o guion de 15-25 intervenciones) y deja al script solo la síntesis de voz
- Genera el MP3 con `python3 scripts/run.py generate_audio.py`, eligiendo modelo `flash` o `pro` y una o dos voces
- Devuelve ruta, duración, coste estimado, etiqueta `<audio>` lista para pegar y dónde colocarla en el post
- Recomienda voz según el contenido: Charon para artículos, Achird para tutoriales, Puck y Kore para el diálogo
- Si falta `GOOGLE_AI_API_KEY` y la llamada viene de blog-write, vuelve en silencio y nunca bloquea la escritura

## Cuándo usarla

- El usuario dice "blog audio", "narrar el blog", "versión en audio", "text to speech" o "modo pódcast"
- blog-write necesita una narración opcional del post recién generado

## Qué la activa

- "Genera la versión en audio de este post"
- "Conviértelo en un diálogo tipo pódcast a dos voces"
- "¿Qué voces hay disponibles?"

## Antes de instalar

- Necesita Python 3.11+, `GOOGLE_AI_API_KEY` exportada en el entorno y FFmpeg para pasar de WAV a MP3; sin FFmpeg devuelve WAV.
- Necesita en el PATH: python3
- Variables de entorno: GEMINI_API_KEY, GOOGLE_AI_API_KEY
- makes network requests
- needs API credentials

## Archivos

- SKILL.md — 9 KB
- references/voices.md — 5 KB
- scripts/__init__.py — 62 B
- scripts/generate_audio.py — 19 KB
- scripts/requirements.lock — 42 KB
- scripts/requirements.txt — 509 B
- scripts/run.py — 3 KB
- scripts/setup_environment.py — 5 KB

## SKILL.md

Reproducido tal cual desde AgriciDaniel/claude-blog bajo MIT. Esta sección es el documento original y está en inglés.

# 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

| Command | What it does |
|---------|-------------|
| `/blog audio generate <file>` | Generate audio narration of a blog post |
| `/blog audio voices` | Show available voices with characteristics |
| `/blog audio setup` | Check/configure API key for Gemini TTS |

## 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

```bash
# 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:

```bash
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`):

| Mode | When to use | Output |
|------|-------------|--------|
| **Summary** | Quick audio overview (1-2 min) | 200-300 word spoken summary |
| **Full** | Complete read-aloud (5-15 min) | Full article as natural speech |
| **Dialogue** | Podcast-style (3-8 min) | Two-person conversation about the article |

### Step 3: Prepare Text

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 file under the working directory, then call:

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

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

**Model selection:**
- `flash` (default): maps to `gemini-3.1-flash-tts-preview`, good for summaries and standard narration.
- `flash31`: explicit alias for `gemini-3.1-flash-tts-preview`.
- `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)
```html
<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)
```jsx
<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:**
```markdown
### 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

| Error | Resolution |
|-------|-----------|
| GOOGLE_AI_API_KEY not set | Get key at https://aistudio.google.com/apikey |
| FFmpeg not found | Install: `sudo apt install ffmpeg`. Falls back to WAV output. |
| Rate limited | Wait and retry. Check limits at https://aistudio.google.com/rate-limit |
| Text too long (>8,192 input tokens) | Split into sections around 7,800 tokens; the script chunks and stitches prepared text |
| Unknown voice name | Run `/blog audio voices` to see valid options |
| API error | Check key validity and model availability |
| API key missing (internal call) | Return silently: writing workflow continues |

## Reference Documentation

Load on-demand: do NOT load all at startup:
- `references/voices.md`: Full 30-voice catalog, recommendations by content type, dialogue pairings

## Dónde encaja

- Categoría: [Redacción y contenido](https://skillsagentes.com/categorias/redaccion-contenido.md) — Redacción, edición y estructuración de contenido extenso.
- Creador: [AgriciDaniel](https://skillsagentes.com/creators/agricidaniel.md) — 80 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Blog](https://skillsagentes.com/skills/agricidaniel/claude-blog/blog.md): Motor de blog de ciclo completo con 31 subskills, 12 plantillas, puntuación sobre 100 y 5 agentes. Enruta cada petición a la subskill correcta: escribir, reescribir, analizar, auditar, schema, clusters y publicación multilingüe.
- [Blog Google](https://skillsagentes.com/skills/agricidaniel/claude-blog/blog-google.md): Integración con las APIs de Google para rendimiento de blog: PageSpeed Insights, CrUX con 25 semanas de histórico, Search Console, URL Inspection, Indexing API, GA4, NLP de entidades, YouTube y Keyword Planner.
- [Blog Notebooklm](https://skillsagentes.com/skills/agricidaniel/claude-blog/blog-notebooklm.md): Consulta cuadernos de Google NotebookLM para obtener respuestas ancladas en tus propios documentos y con citas: gestiona la biblioteca de cuadernos, la autenticación con Google y el descubrimiento de contenido.
- [Blog Image](https://skillsagentes.com/skills/agricidaniel/claude-blog/blog-image.md): Generación y edición de imágenes con IA para contenido de blog mediante Gemini por MCP: portadas, ilustraciones, tarjetas sociales y OG, con 6 modos de dominio y retorno silencioso si el MCP no está disponible.
- [Blog Cluster](https://skillsagentes.com/skills/agricidaniel/claude-blog/blog-cluster.md): Motor de clusters temáticos semánticos: investiga keywords desde el SERP, agrupa por intención y solapamiento, construye una arquitectura hub-and-spoke, genera un mapa SVG y ejecuta el cluster llamando a blog-write.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)