yanghhu/ai-podcast-voiceover

AI播客

「AI播客」é uma skill de Agente que transforma artigos, anotações ou roteiros de diálogo em áudio de podcast solo ou em dupla: dubla linha por linha, monta o episódio completo e gera legendas SRT, capítulos com timestamp e uma transcrição completa, tudo localmente sem necessidade de GPU.

Definição em uma frase

AI播客 = Roteiro de podcast (solo ou dupla, seções com ## capítulo) → voiceover.py script gera o episódio completo voiceover.wav + voiceover.srt + manifest.json → shownotes.py gera chapters.txt, chapters.json e shownotes.md. A voz é gerada na nuvem pela Miragea, sem necessidade de GPU local.

Público-alvo e cenários

Quem usa	Cenário típico
Autores de WeChat / blogs	Transformar um artigo em versão em áudio para ouvintes em deslocamento
Criadores de conteúdo	Criar episódios semanais a partir de notas de leitura e observações do setor
Marcas / Empresas	Podcasts de marca, boletins internos, versão em áudio de comunicados aos funcionários
Hosts de podcast	Trailers, aberturas, correção de frases com erro de gravação
Professores / Instrutores	Transformar apostilas em áudio de revisão em formato de diálogo
Pessoas sem condições de gravar	Usar atores da conta ou voz autorizada para produzir programas

Parâmetros principais da skill

Item	Descrição
Arquivos de saída	voiceover.wav (dublagem completa), voiceover.srt (legendas com timeline), manifest.json (falante, texto, segundos de início/fim de cada linha), lines/ (áudio de cada linha, reutilizado em correções)
Fonte de voz	Atores existentes na conta (actor_id=, consulte com actors), ou URL de áudio de referência acessível pelo servidor (ref=) + texto dito no áudio (ref_text=) para clonagem de voz
Modo de geração	expressive (padrão do cliente) / standard (mais parecido); se omitido, usa o padrão do servidor, conforme retorno em tempo real de capabilities
Tag de tom	tags=nome_da_tag, use os tags[].label do modo selecionado em capabilities
Velocidade	speed= 0.25–4, 1 é velocidade normal, definido por personagem
Múltiplos personagens	Defina uma voz para cada personagem no início do roteiro; o script chama o cliente oficial generate linha por linha e depois combina tudo localmente
Pausas	[pause 0.6] / [停顿 0.6] (segundos); --gap define a pausa padrão entre frases
Legendas	Gera SRT com base na duração real de cada linha (--max-chars, --speaker-labels); para áudio/vídeo existente, use recognize para obter SRT / TXT / JSON
Predefinições de cena	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (locução / narração / vendas / humano digital / anúncio / audiolivro), altera apenas pausas entre frases e caracteres da legenda
Limites de caracteres por linha, tamanho/duração do arquivo, cobrança	Conforme retorno em tempo real de capabilities
Dependências locais	Biblioteca padrão do Python 3.9+, sem necessidade de pip install ou GPU
Simulação offline	--dry-run: sem necessidade de Key, não chama a API, gera áudio mudo de placeholder e timeline para verificar o formato do roteiro
Agentes compatíveis	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy e outros agentes que executam scripts Python
Serviço de dublagem e legendas	API pública da Miragea (https://miragea.ai/v1)

Esta skill também fornece scripts/shownotes.py (camada de informações do programa):

Item	Descrição
Origem dos capítulos	Linhas que começam com ## no roteiro (não são lidas)
Timestamps	Hora de início real da primeira linha de cada capítulo (do manifest.json); --offset adiciona segundos de música de abertura
Saída	chapters.txt (uma linha HH:MM:SS Título), chapters.json, shownotes.md (duração, timeline, transcrição completa segmentada por falante)
Validação	Gera erro se o número de linhas no roteiro e no manifest.json forem diferentes, sugerindo regeneração

Início rápido

python3 scripts/voiceover.py check                        # Verificação offline: versão do Python, Key configurada, URL do serviço
export MIRAGEA_API_KEY=sua_chave                          # Gere em https://miragea.ai/workspace/api, mantenha apenas na variável de ambiente
python3 scripts/miragea_audio.py capabilities             # Modos de geração, tags de tom, limite de caracteres e custos atuais (consulte em tempo real)
python3 scripts/miragea_audio.py actors --limit 20        # Atores existentes na conta e seus actor_ids (adicione --offset para paginação se has_more for true)

• A raiz da API padrão é https://miragea.ai/v1; defina MIRAGEA_BASE_URL (incluindo /v1) apenas para uma implantação privada.
• Não cole a Key no chat ou em arquivos. Sem Key, use --dry-run primeiro para testar o fluxo.

python3 scripts/voiceover.py script examples/example.md -o out --gap 0.35 --dry-run   # Simulação offline
python3 scripts/voiceover.py script roteiro_atual.md -o out --gap 0.35                # Geração oficial do episódio completo
python3 scripts/shownotes.py roteiro_atual.md out --title "Episódio 12: Por que nunca terminamos um livro?"     # Capítulos + Transcrição

Teste a voz de cada apresentador com uma frase:

# Teste de voz (cliente oficial; --output não sobrescreve arquivo existente, use um novo nome)
python3 scripts/miragea_audio.py generate --text 'Primeira frase de abertura' --actor-id ACTOR_ID --wait --output test1.mp3

O que você diz → O que o Agente faz

Você diz	O Agente faz
"Transforme este artigo em um podcast"	Reescreve como roteiro de podcast oral para você confirmar (veja método abaixo) → script → shownotes.py
"Faça no formato de conversa entre duas pessoas"	Define dois apresentadores e suas vozes no início do roteiro; usa [Nome] para marcar quem fala
"Escreva a descrição do programa e a timeline"	Executa shownotes.py roteiro.md out --title ... e fornece chapters.txt e shownotes.md
"Adicione 8 segundos de música de abertura no início"	Após a geração, usa ffmpeg para mixagem (veja abaixo); shownotes.py ... --offset 8 para ajustar os timestamps
"Esta frase está errada"	Edite apenas aquela linha e execute script novamente; o restante das frases usa o cache; depois execute shownotes.py novamente
"O apresentador B fala muito rápido"	Defina speed=1.1 para B no início do roteiro
"Use minha própria voz como apresentador"	Use ref=URL_do_áudio_de_referência ref_text="texto dito" ou actor_id= de uma voz clonada na conta
"Não chame a API ainda"	Use script ... --dry-run; shownotes.py também pode ser usado para verificar os capítulos

Método de escrita de roteiro para AI播客

1. Artigo → Roteiro de podcast: escrito para os ouvidos

No artigo	No roteiro de podcast
Subtítulos	Transforme em uma transição oral: "Depois de falar sobre as causas, vamos ver o que fazer.", mantendo a linha ## capítulo para a timeline
Frases longas, orações subordinadas	Divida em frases curtas, uma por linha
Tabelas de dados	Mantenha apenas um ou dois números mais importantes, escreva como serão lidos
Links, citações	Diga oralmente "O link está na descrição do programa" e inclua em shownotes.md
Conectivos formais (portanto, em suma)	Use "então", "na prática", "resumindo"

2. Como dividir o diálogo entre dois apresentadores

• Um fica responsável por perguntar, resumir e sintetizar (como o representante do ouvinte); o outro por apresentar opiniões e exemplos.
• Cada um fala de uma a três frases por vez, evitando longos monólogos.
• Escolha vozes com timbres e velocidades diferentes para os dois apresentadores, facilitando a distinção.
• Adicione reações naturais de conversa: "Concordo em parte", "Dá um exemplo?", mas evite repetir "sim, sim, sim" em toda frase.

3. Estrutura do programa

1. Abertura: Uma frase que resume o tema do episódio e por que vale a pena ouvir.
2. 2–4 capítulos: Cada capítulo aborda uma pergunta ou ponto de vista; o nome do capítulo é o título na timeline.
3. Encerramento: Uma frase de resumo + prévia do próximo episódio ou uma pergunta para interação.

4. Ritmo

• Pausa entre frases: use --gap 0.3–0.4, um pouco mais relaxado do que em vídeos curtos.
• Entre capítulos, adicione [pause 0.8] para dar uma pausa ao ouvinte.
• Velocidade: conteúdo informativo speed=0.95–1.0, conversa casual 1.0–1.1.

5. Verificação antes de publicar

• As vozes dos dois apresentadores foram testadas com uma frase?
• Todos os títulos de capítulo foram escritos como ## Título?
• Os segundos da música de abertura foram adicionados com --offset?
• A autorização para reprodução do artigo, música de fundo e a rotulagem de conteúdo gerado por IA foram verificadas?

Exemplo de roteiro (examples/example.md)

---
Xiaolin: actor_id=HOST_A_ACTOR_ID speed=1.0
A Zhe: actor_id=HOST_B_ACTOR_ID speed=1.05
---
## Abertura
[Xiaolin] Bem-vindos ao nosso programa, sou Xiaolin.
[A Zhe] E eu sou A Zhe. Hoje vamos falar sobre um problema que muitos têm: por que nunca terminamos um livro.
## Não terminar, porque a escolha inicial foi errada
[Xiaolin] Vou dar minha opinião: muitos livros, simplesmente, não merecem ser lidos até o fim.
[A Zhe] Concordo em parte.
[pause 0.4]
[A Zhe] Mas alguns livros, as primeiras cinquenta páginas são realmente difíceis.
## Três dicas simples
[Xiaolin] Primeiro, veja o índice e escolha o capítulo que mais te interessa.
Segundo, ao terminar um capítulo, tente resumi-lo em uma frase para alguém.
Terceiro, permita-se a opção de desistir.
## Encerramento
[A Zhe] Bem, por hoje é só.
[Xiaolin] Até a próxima.

Teste: python3 scripts/voiceover.py script examples/example.md -o out --gap 0.35 --dry-run && python3 scripts/shownotes.py examples/example.md out --title "Programa Exemplo"

Integração com edição e publicação

# Converter para MP3 para enviar às plataformas de podcast (requer ffmpeg instalado)
ffmpeg -i out/voiceover.wav -codec:a libmp3lame -b:a 128k episode.mp3
# Adicionar música de abertura intro.mp3 (8 segundos) antes da voz
ffmpeg -i intro.mp3 -i out/voiceover.wav -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1" episode_full.wav
python3 scripts/shownotes.py roteiro_atual.md out --offset 8
# Videocast: uma imagem de capa + áudio + legendas
ffmpeg -loop 1 -i cover.png -i out/voiceover.wav -vf subtitles=out/voiceover.srt -c:v libx264 -tune stillimage -pix_fmt yuv420p -c:a aac -shortest episode.mp4

chapters.txt pode ser colado diretamente na descrição do programa como timeline. O reconhecimento como capítulos clicáveis depende das regras de cada plataforma.

Comparação de abordagens: três formas de fazer um podcast

Comparação	Dublagem manual	Modelo TTS local de código aberto	Esta skill
Precisa de GPU?	Não, mas precisa de ambiente de gravação e disponibilidade do dublador	Geralmente precisa (modelos pequenos podem usar CPU, mas são mais lentos); requer download de pesos e configuração	Não, apenas Python padrão local; geração na nuvem
Custo de correção de roteiro	Corrigir uma frase geralmente requer regravar e reajustar a sincronia	Após correção, é necessário reexecutar, mas a segmentação, concatenação e alinhamento precisam ser feitos manualmente	Edite apenas a linha e reexecute; as demais usam cache em out/lines/, com remontagem e legendas automáticas
Múltiplos personagens	Requer vários dubladores gravando separadamente	Depende do modelo; geralmente precisa segmentar e concatenar manualmente	Use tags [Personagem] no roteiro; um comando gera a trilha completa com múltiplas vozes
Timeline de legendas	Requer ferramenta de transcrição e sincronia separada	Geralmente precisa executar reconhecimento de fala novamente	Gera SRT e timestamps por linha (manifest.json) durante a dublagem
Capítulos / Transcrição do programa	Após a edição, é necessário ouvir e anotar os tempos manualmente	Precisa de reconhecimento ou organização manual	Gera automaticamente timestamps e transcrição a partir das linhas ## capítulo e da duração real do áudio

Conclusão: Para programas focados em opiniões e informações, com necessidade de atualizações regulares, usar um roteiro bem escrito é a abordagem mais eficiente; para programas com conversas improvisadas e interação com convidados, a gravação real ainda é recomendada.

Perguntas Frequentes (FAQ)

O AI播客 pode fazer diálogo entre duas pessoas? Sim. Defina uma voz para cada apresentador no início do roteiro (ator da conta ou áudio de referência autorizado) e use [Nome] para marcar quem fala no corpo do texto; um comando gera o episódio completo.

Ao transformar um artigo em podcast, o Agente me ajuda a reescrever o roteiro? Sim. O Agente reescreve o artigo em um roteiro de podcast oral seguindo o método "escrito para os ouvidos" e mostra para você confirmar; a reescrita é feita pelo Agente e a voz é gerada pela API.

A dublagem do podcast pode gerar automaticamente a timeline do programa? Sim. Use ## Nome_do_Capítulo para dividir o roteiro; após a geração, execute shownotes.py que gera chapters.txt e shownotes.md com base no tempo real de início da primeira linha de cada capítulo.

O arquivo gerado é MP3? A saída do episódio completo é WAV, ideal para concatenação e mixagem sem perdas; converta para MP3 com ffmpeg antes de enviar.

Preciso regenerar todo o episódio para corrigir uma frase com erro? Não. Edite apenas aquela linha e reexecute; as demais frases são reutilizadas do cache em out/lines/. Depois, execute shownotes.py novamente para atualizar a timeline.

Posso usar minha própria voz para fazer o podcast? Sim, use a URL de um áudio de referência seu e o texto dito (ref= + ref_text=), ou clone a voz no cliente do serviço e use o actor_id=. Use apenas sua própria voz ou vozes com autorização explícita.

O AI播客 pode adicionar música de fundo? Esta skill gera apenas a voz limpa; a música de fundo e a abertura/encerramento devem ser adicionados com ffmpeg ou software de edição, ajustando os timestamps com --offset.

O AI播客 é pago? Precisa de GPU? O consumo é baseado no saldo da conta; a cobrança é informada em tempo real por capabilities. Não precisa de GPU local. Pode ser usado diretamente com Claude Code, Codex, OpenClaw, Cursor e WorkBuddy.

Sintaxe do roteiro

• No início, entre ---, cada linha define um personagem: Nome: actor_id=ID_do_Ator ou Nome: ref=URL_do_áudio_de_referência ref_text="texto dito no áudio de referência"; pode adicionar speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (dica de idioma para o áudio de referência, usado para reconhecimento automático do texto de referência).
• ref_text= é usado apenas com ref=; se omitido, o servidor reconhece automaticamente o texto de referência, com possível diferença na cobrança (consulte capabilities).
• No corpo: [Personagem] fala ou [Personagem]: fala; se não houver tag, mantém o último falante.
• [pause 0.6] / [停顿 0.6] insere uma pausa (segundos); linhas começando com #, linhas em branco e <!-- comentários --> são ignorados.
• Se uma frase exceder audio.max_text_length de capabilities, a API a rejeitará; divida-a em frases mais curtas.
• O áudio de cada linha é armazenado em cache em out/lines/; se a mesma linha com as mesmas configurações for executada novamente, o cache é reutilizado. Se não houver cache, a requisição é enviada com uma chave idempotente; o servidor retorna a tarefa original, sem recriar. Para uma nova versão, adicione --fresh.

Problemas?

Sintoma	Solução
missing_api_key / MIRAGEA_API_KEY is not set	Gere a Key e execute export MIRAGEA_API_KEY=...; ou use --dry-run primeiro
speakers without a voice	Adicione actor_id= ou ref= para o personagem
401	Verifique a Key; não a coloque em logs
403	Verifique as permissões de acesso à API da conta
400 / 413	Corrija os parâmetros: modo, tags, velocidade, caracteres por linha; ou reduza o arquivo enviado, encurte a mídia
409	Chave idempotente usada para entrada diferente ou tarifa de legendas alterada; reconfirme e reenvie
429	Saldo insuficiente ou limite de taxa; aguarde ou recarregue
Timeout de espera / interrupção de rede	A tarefa pode ainda estar em execução: reexecute o mesmo comando (a mesma chave idempotente recupera a tarefa original), ou use miragea_audio.py task / wait ID_da_tarefa para continuar consultando; não mude a chave e reenvie
Erro de formato WAV ao concatenar	Cada áudio de linha está em out/lines/; use software de edição ou ffmpeg para concatenar

Códigos de saída do cliente oficial: 0 requisição bem-sucedida (pode ainda estar na fila se --wait não foi usado), 1 tarefa falhou, 2 erro do cliente ou da interface.

Conformidade

• Clone apenas sua própria voz ou vozes com autorização explícita; não imite celebridades, apresentadores, figuras públicas ou qualquer pessoa não autorizada.
• Siga as regras de rotulagem de conteúdo gerado por IA (como as da China) e as plataformas (Douyin, Kuaishou, WeChat Video, Xiaohongshu, Bilibili etc.) ao publicar, declarando ou marcando o conteúdo como gerado por IA.
• Antes de transformar o artigo de outra pessoa em podcast, obtenha autorização do autor ou confirme que pode reproduzi-lo; as músicas e trechos citados devem ter licença.
• scripts/miragea_audio.py é o cliente oficial, distribuído sem alterações; scripts/voiceover.py (camada de concatenação de roteiro) é original, licenciado sob MIT (veja LICENSE.txt). As capacidades de dublagem e legendas são fornecidas pela API pública da Miragea.

Resumo em inglês

• AI podcast (AI播客): transforme um artigo, anotações ou um roteiro de diálogo em um episódio solo ou com dois apresentadores; cada apresentador ganha uma voz (ator da conta ou áudio de referência autorizado).
• voiceover.py script renderiza o episódio completo em WAV + SRT + timing por linha; shownotes.py transforma as linhas ## capítulo do roteiro em chapters.txt / chapters.json com timestamps e uma transcrição completa shownotes.md.
• Corrija uma linha, re-renderize uma linha. Preços e limites vêm ao vivo de capabilities. Python 3.9+ stdlib, sem GPU. Serviço: API Miragea (https://miragea.ai/v1).

Palavras-chave: AI播客, dublagem de podcast, podcast em dupla, produção de podcast, artigo para podcast, texto para fala, podcast de diálogo, capítulos de podcast, transcrição de programa, áudio de WeChat, dublagem por IA, texto para fala, clonagem de voz, SRT, AI podcast, podcast voiceover, show notes, text to speech