blog-audio

Blog Audio -- Narração TTS com Gemini para Postagens de Blog

Gere narração de áudio profissional de conteúdo de blog usando o Google Gemini TTS. Três modos: resumo (visão geral falada de 200 a 300 palavras), leitura completa do artigo, ou diálogo estilo podcast com dois palestrantes. 30 vozes, mais de 80 idiomas, saída com incorporação HTML5.

Referência Rápida

Comando	O que faz
/blog audio generate <arquivo>	Gera narração de áudio de uma postagem de blog
/blog audio voices	Mostra vozes disponíveis com características
/blog audio setup	Verifica/configura a chave de API para o Gemini TTS

Pré-requisitos

• Python 3.11+ (venv gerenciado automaticamente pelo run.py)
• Variável de ambiente GOOGLE_AI_API_KEY (mesma chave usada pelo blog-image)
• FFmpeg (para conversão de WAV para MP3; usa WAV como fallback se ausente)

Sempre Use o Wrapper run.py

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

# ERRADO:
python3 scripts/generate_audio.py --text "..."  # Falha sem o venv

Verificação da Chave de API (Padrão de Portão)

Antes de gerar áudio, verifique a chave de API:

echo $GOOGLE_AI_API_KEY

• Se definida: prossiga com a geração
• Se não definida: oriente o usuário: "A geração de áudio requer uma chave de API do Google AI. Obtenha uma gratuitamente em https://aistudio.google.com/apikey Em seguida, defina: export GOOGLE_AI_API_KEY=sua-chave Esta é a mesma chave usada por /blog image -- se a geração de imagem funciona, a de áudio também."
• Quando chamado internamente (do blog-write): retorne silenciosamente se a chave estiver ausente. Nunca bloqueie o fluxo de escrita.

Configuração

Para /blog audio setup:

1. Verifique se GOOGLE_AI_API_KEY está definida no ambiente
2. Se blog-image estiver configurado (verifique .mcp.json), a chave já está disponível
3. Se não, oriente o usuário para https://aistudio.google.com/apikey
4. Verifique com uma execução de teste: python3 scripts/run.py generate_audio.py --text "Teste" --dry-run --json

Seleção de Voz

Para /blog audio voices:

Carregue references/voices.md e apresente o catálogo de vozes ao usuário.

Pergunte ao usuário qual voz prefere, ou recomende com base no tipo de conteúdo:

• Narração de artigo: Charon (Informativo) ou Sadaltager (Conhecimento)
• Tutorial/Instruções: Achird (Amigável) ou Sulafat (Caloroso)
• Notícias/Análise: Rasalgethi (Informativo) ou Schedar (Equilibrado)
• Estilo de vida/Bem-estar: Aoede (Leve) ou Vindemiatrix (Suave)
• Apresentador de diálogo: Puck (Animado) ou Laomedeia (Animado)
• Especialista em diálogo: Kore (Firme) ou Charon (Informativo)

Fluxo de Geração

Para /blog audio generate <arquivo>:

Passo 1: Leia a Postagem do Blog

Leia o arquivo e extraia:

• Título (do H1 ou frontmatter)
• Conteúdo completo (corpo em markdown)
• Contagem aproximada de palavras

Passo 2: Escolha o Modo

Pergunte ao usuário (ou selecione automaticamente se eles especificaram --mode):

Modo	Quando usar	Saída
Resumo	Visão geral rápida em áudio (1-2 min)	Resumo falado de 200 a 300 palavras
Completo	Leitura completa (5-15 min)	Artigo completo como fala natural
Diálogo	Estilo podcast (3-8 min)	Conversa entre duas pessoas sobre o artigo

Passo 3: Prepare o Texto

CRÍTICO: Claude prepara o texto. O script faz apenas TTS.

Modo Resumo: Escreva um resumo falado de 200 a 300 palavras do artigo. Regras:

• Escreva como fala natural, não texto escrito
• Abra com a descoberta ou resposta principal do artigo
• Cubra 3-5 principais conclusões
• Feche com conselhos acionáveis
• Sem markdown, sem "Neste artigo...", sem metalinguagem
• Use transições conversacionais ("Aqui está o que importa...", "A descoberta principal é...")

Modo Completo: Limpe o conteúdo markdown para texto falado limpo:

• Títulos se tornam transições naturais ("A seguir, vamos ver...")
• Links se tornam texto simples (remova URLs, mantenha o texto do link)
• Imagens e gráficos: omita ou descreva brevemente ("Como os dados mostram...")
• Blocos de código: descreva verbalmente ("O código usa um loop for para...")
• Listas: converta em frases naturais
• Remova frontmatter, marcação de esquema, tags HTML
• Adicione uma breve introdução: "Este é [título], publicado em [data]."

Modo Diálogo: Escreva um roteiro de conversa de 2 pessoas sobre o artigo:

• Palestrante1 = Apresentador (curioso, faz boas perguntas)
• Palestrante2 = Especialista (conhecimento, dá respostas claras)
• Formate cada linha como: [Palestrante1] Qual é a principal conclusão aqui?
• Cubra os pontos principais do artigo de forma conversacional
• 15-25 trocas (produz ~3-8 minutos)
• Natural, não forçado ("Esse é um ótimo ponto" em vez de "De fato, como a pesquisa indica")

Passo 4: Selecione a Voz

Se o usuário escolheu uma voz, use-a. Caso contrário, recomende com base no modo:

• Resumo/Completo: padrão para Charon (Informativo)
• Diálogo: padrão para Puck (Apresentador) + Kore (Especialista)

Passo 5: Gere o Áudio

Escreva o texto preparado em um arquivo temporário e então chame:

# Voz única (modo resumo ou completo)
python3 scripts/run.py generate_audio.py \
  --text-file /tmp/blog_audio_prepared.txt \
  --voice Charon \
  --model flash \
  --output /caminho/para/audio/post-slug.mp3 \
  --json

# Duas vozes (modo diálogo)
python3 scripts/run.py generate_audio.py \
  --text-file /tmp/blog_audio_dialogue.txt \
  --voice Puck \
  --voice2 Kore \
  --model pro \
  --output /caminho/para/audio/post-slug-dialogue.mp3 \
  --json

Seleção de modelo:

• flash (padrão): Rápido, barato. Bom para resumos e narração padrão.
• pro: Maior qualidade. Use para modo diálogo ou conteúdo premium.

Passo 6: Entregue

Apresente o resultado ao usuário:

1. Caminho do arquivo -- onde o áudio foi salvo
2. Duração -- legível (ex.: "3:42")
3. Código de incorporação -- tag de áudio HTML5 pronta para colar
4. Custo -- custo estimado da API
5. Sugestão de posicionamento -- onde inserir a incorporação na postagem do blog

Guia de Incorporação

HTML padrão (Hugo, Jekyll, sites estáticos)

<audio controls preload="metadata">
  <source src="audio/post-slug.mp3" type="audio/mpeg">
  Seu navegador não suporta o elemento de áudio.
</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"]

Posicionamento

Insira o player de áudio após a introdução (abaixo do primeiro H2) ou no início do artigo com um rótulo: "Ouça este artigo" ou "Versão em áudio".

API Interna (para blog-write)

Quando invocado internamente pelo blog-write:

Entrada:

• text: Texto preparado (já limpo por Claude)
• voice: Nome da voz (padrão: Charon)
• voice2: Segunda voz para diálogo (opcional)
• model: flash ou pro
• output_path: Onde salvar o arquivo

Saída:

### Narração em Áudio
- **Caminho:** /caminho/para/audio/post-slug.mp3
- **Duração:** 3:42
- **Voz:** Charon
- **Incorporação:** `<audio controls preload="metadata"><source src="audio/post-slug.mp3" type="audio/mpeg"></audio>`

Fallback gracioso: Se GOOGLE_AI_API_KEY não estiver definida, retorne imediatamente sem erro. O fluxo de escrita continua sem áudio. Nunca bloqueie o blog-write porque a geração de áudio está indisponível.

Tratamento de Erros

Erro	Resolução
GOOGLE_AI_API_KEY não definida	Obtenha a chave em https://aistudio.google.com/apikey
FFmpeg não encontrado	Instale: sudo apt install ffmpeg. Usa saída WAV como fallback.
Limite de taxa excedido	Espere e tente novamente. Verifique limites em https://aistudio.google.com/rate-limit
Texto muito longo (>32k tokens)	Divida em seções, gere separadamente
Nome de voz desconhecido	Execute /blog audio voices para ver opções válidas
Erro de API	Verifique validade da chave, disponibilidade do modelo (modelos de preview)
Chave de API ausente (chamada interna)	Retorne silenciosamente -- o fluxo de escrita continua

Documentação de Referência

Carregue sob demanda -- NÃO carregue tudo na inicialização:

• references/voices.md -- Catálogo completo de 30 vozes, recomendações por tipo de conteúdo, pares de diálogo