Miragea AI配音

AI Narração (AI配音)

「AI Narração」é uma skill de agente que transforma um roteiro de vídeo em uma narração multi-personagem (WAV) com legendas SRT sincronizadas: use personagens existentes na sua conta ou clone vozes a partir de um áudio de referência. Cobre cenas como vlog, narração de filmes, romances, vendas, comerciais e audiolivros. Tudo localmente, sem necessidade de GPU.

Definição em uma frase

AI Narração = um roteiro com tags [personagem] → uma narração completa voiceover.wav + legendas sincronizadas voiceover.srt + timings por frase manifest.json, em um único comando; cada frase é gerada pela API aberta da Miragea, localmente só precisa de Python 3.9+, sem GPU e sem instalar pacotes de terceiros.

Público-alvo e cenários

Cenário	Necessidade típica	Predefinição recomendada
Vlog / Criador de conhecimento	Voz clonada própria para vlogs diários, legendas verticais	--preset koubo
Narração de filmes / séries curtas	Narrador + falas de personagens com múltiplas vozes, sincronia com o tempo	--preset jieshuo
Romances online / Audiolivros	Leitura multi-personagem, pausas entre parágrafos, legendas com nome do personagem	--preset youshengshu
Vídeos de vendas curtas	Narração rápida de pontos de venda, legendas grandes, teste de múltiplas versões	--preset daihuo
Avatar digital / IA分身	Áudio de voz limpa para condução + timings por frase	--preset shuziren
Comerciais / Vídeos promocionais	Pausas precisas, silêncios, voz de marca fixa	--preset guanggao
Legendar vídeo existente	Reconhecer áudio/vídeo em SRT com timestamps	miragea_audio.py recognize

Há também skills irmãs que aprofundam métodos de escrita para cada cenário: Narração para Vlog, Narração para Filmes, Narração para Romances, Texto-para-Fala, Clonagem de Voz, Geração de Legendas.

Parâmetros principais de capacidade

Item	Descrição
Arquivos de saída	voiceover.wav (narração completa), voiceover.srt (legendas sincronizadas), manifest.json (falante, texto, timestamps de cada frase), lines/ (áudio por frase, reutilizado em revisões)
Fonte de voz	Personagem já existente na conta actor_id= (consulte com actors), ou URL de áudio de referência acessível pelo servidor ref= + texto real dito no áudio ref_text= (clonagem de voz)
Modo de geração	expressive (cliente "padrão") / standard (cliente "mais parecido"); quando omitido, usa o padrão do servidor, conforme retornado em tempo real por capabilities
Tags de tom	tags=nome_da_tag, consulte tags[].label do modo selecionado em capabilities
Velocidade	speed= 0.25–4, 1 é velocidade normal, definido por personagem
Multi-personagem	No início do roteiro, defina uma voz para cada personagem; a skill chama o cliente oficial generate linha por linha e junta tudo localmente
Pausas	[pause 0.6] / [pausa 0.6] (em segundos); --gap define pausa padrão entre frases
Legendas	Gera SRT com base na duração real de cada áudio ao narrar (--max-chars, --speaker-labels); áudio/vídeo existente usa recognize para SRT/TXT/JSON
Predefinições de cena	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (vlog / narração / vendas / avatar digital / comercial / audiolivro), altera apenas pausa entre frases e tamanho da legenda
Limites de caracteres por frase, tamanho/duração do arquivo, faturamento	Conforme retornado em tempo real por capabilities
Dependências locais	Python 3.9+ biblioteca padrão, sem pip install, sem GPU
Simulação offline	--dry-run: não precisa de Key, não chama a API, gera áudio silencioso de placeholder e timestamps, para verificar o formato do roteiro
Agentes suportados	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy e outros agentes que executam scripts Python
Serviço de narração e legendas	API aberta Miragea (https://miragea.ai/v1)

Limitações de capacidade

Faz	Não faz
Narração de uma só voz ou diálogo multi-personagem (cada personagem com uma voz, geração linha a linha e junção local)	Não edita vídeo, não renderiza vídeo (saída é trilha de áudio e legendas, para importar em剪映 / Premiere / CapCut / ffmpeg)
Usar personagens existentes na conta (actor_id) ou clonagem por URL de áudio de referência	Não clona vozes sem autorização explícita
Pausas, velocidade independente por personagem, modo de geração e tags de tom	Não escreve o roteiro automaticamente (pode pedir ao agente para escrever seguindo os métodos abaixo)
Reconhecer áudio/vídeo em SRT/TXT/JSON	Não faz mixagem de música de fundo, não traduz (tradução pode ser feita pelo agente)
--dry-run simulação offline completa

Início rápido

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

• 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/movie-recap.md -o out --dry-run      # Simulação offline do exemplo
python3 scripts/voiceover.py script roteiro.md -o out --preset koubo                 # Roteiro completo → out/voiceover.wav + voiceover.srt + manifest.json
python3 scripts/voiceover.py script roteiro.md -o out --gap 0.3 --max-chars 16 --speaker-labels --model standard
python3 scripts/miragea_audio.py generate --text 'Teste uma frase' --actor-id ACTOR_ID --wait --output test1.mp3
python3 scripts/miragea_audio.py recognize --file video_final.mp4 --wait --output video_final.srt

• --gap: pausa entre frases em segundos (padrão 0.25). --max-chars: máximo de caracteres por legenda (padrão 18, vertical sugere 12–16, inglês sugere 40).
• --preset define pausa entre frases e tamanho da legenda de uma vez, ainda pode ser sobrescrito com --gap / --max-chars.

O que você diz → O que o agente executa

Você diz	Agente executa
"Narre este roteiro de vlog"	Escreve roteiro.md (um personagem) → script roteiro.md -o out --preset koubo
"Narração de filme, narrador + dois personagens"	Front matter define narrador / vozes dos personagens → script ... --preset jieshuo
"Use minha voz para narrar"	Use actors para encontrar seu personagem clonado (actor_id); ou forneça uma URL de áudio de referência acessível pelo servidor e o texto dito nele → ref= + ref_text=
"Tom mais alegre"	Consulte capabilities para tags do modo selecionado → adicione tags=nome_da_tag ao personagem
"Só teste uma frase"	miragea_audio.py generate --text "..." --actor-id ID --wait --output test1.mp3
"A quinta frase está errada"	Edite apenas aquela linha e execute o mesmo comando novamente; as outras frases reutilizam out/lines/
"Legende este vídeo"	miragea_audio.py recognize --file video.mp4 --wait --output video.srt
"Não gaste créditos, só teste o fluxo"	script ... --dry-run

Metodologia geral de escrita de roteiro para narração

Independentemente do cenário, a qualidade da narração AI depende muito de o roteiro ser "escrito para os ouvidos".

1. Seis regras universais

1. Uma linha, uma frase, uma ideia: Chinês: tente não ultrapassar 20 caracteres por frase; a narração soa mais natural e a legenda cabe em uma tela.
2. Escreva como se fosse ler em voz alta: Números, anos, modelos, porcentagens ambíguos devem ser escritos por extenso; abreviações que devem ser soletradas letra por letra separe com espaços.
3. Substitua linguagem escrita por linguagem falada: "portanto" → "então", "realizar ajustes" → "ajustar", divida modificadores longos em duas frases.
4. Pausas apenas antes e depois do ponto principal: 0.3 segundos antes do ponto principal, 0.4–0.6 segundos para transições, 0.6–1.0 segundos para reviravoltas / encerramento.
5. Um personagem, uma voz, uma conta, uma persona: Tom e velocidade definidos no front matter, não mude em conteúdo de série.
6. Teste uma frase primeiro, depois gere o roteiro completo: Use generate para testar a frase inicial e palavras difíceis, depois execute script.

2. Comparação de ritmo por cenário

Cenário	Pausa entre frases (predefinição)	Caracteres por legenda (predefinição)	Velocidade sugerida speed	Foco da escrita
Vlog	0.15 s	14	1.05–1.1	Conclusão nos primeiros 3 segundos, uma ideia por linha
Narração de filme	0.3 s	16	0.95–1.05	Abertura com suspense, apelidos de identidade, pausa antes da reviravolta
Vendas	0.1 s	12	1.1–1.2	Dor → ponto de venda visualizado → uma chamada para ação
Avatar digital	0.2 s	16	0.95–1.05	Voz pura, silêncio no início e fim, uma cena por parágrafo
Comercial	0.4 s	14	0.9–1.0	Frases curtas com imagens, silêncios, nome da marca + slogan no final
Audiolivro	0.5 s (legendas com nome do personagem)	20	0.9–1.0	Tabela de elenco, divisão de diálogos, pausas de três níveis

3. Uma voz, duas velocidades

speed é definido por personagem; quando a mesma voz precisa "falar rápido na preparação e devagar no ponto principal", use o mesmo actor_id para definir dois personagens:

---
narrator: actor_id=123 speed=1.05
narrator_lento: actor_id=123 speed=0.9
---
[narrator] Ele pensou que tudo tinha acabado.
[pause 0.6]
[narrator_lento] Até aquele telefonema tocar.

4. Como fazer versões em outros idiomas

1. Após finalizar o roteiro em chinês, peça ao agente para reescrever para o mercado-alvo em linguagem coloquial (não tradução literal), localize unidades e formas de tratamento.
2. Um arquivo de roteiro por idioma; escolha vozes adequadas ao idioma (cada personagem retorna language em actors), ou use áudio de referência ref= no idioma alvo, o idioma do áudio de referência pode ser especificado com language=.
3. Legendas em idioma estrangeiro: --max-chars 40 aproximadamente.
4. Teste uma frase inicial e palavras difíceis, peça a um falante nativo para auditar antes de gerar o roteiro completo.

5. Lista de verificação de qualidade antes da entrega

• A frase inicial foi testada? O tom e a velocidade estão corretos?
• Números, inglês, nomes próprios, heterofones estão pronunciados corretamente?
• A duração total em manifest.json atende ao requisito do vídeo?
• Cada legenda tem comprimento adequado à proporção da tela?
• A voz foi autorizada e a geração por IA foi indicada na publicação?

Sintaxe do roteiro

• No início, entre ---, cada linha define um personagem: nome_do_personagem: actor_id=ID_do_Personagem ou nome_do_personagem: ref=URL_do_audio_de_referencia ref_text="texto real dito no áudio de referência"; pode adicionar speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (dica de idioma para áudio de referência, usado para reconhecimento automático do texto de referência).
• ref_text= só é usado junto com ref=; quando omitido, o servidor reconhece automaticamente o texto de referência, com custos diferentes, conforme capabilities.
• No corpo: [personagem] fala ou [personagem]: fala; sem tag, mantém o último falante.
• [pause 0.6] / [pausa 0.6] insere pausa (segundos); linhas começando com #, linhas em branco e <!-- comentários --> são ignorados.
• Frases que excedem audio.max_text_length em capabilities serão rejeitadas pela API; divida em frases mais curtas.
• Áudio de cada frase é armazenado em cache em out/lines/; na mesma frase com as mesmas configurações, a execução subsequente reutiliza o cache; se não houver cache, envia com a mesma chave de idempotência, o servidor retorna a tarefa original sem criar duplicata. Para uma nova versão, adicione --fresh.

Exemplo de roteiro (examples/movie-recap.md)

---
narrator: actor_id=SEU_ACTOR_ID speed=1.05
heroi: ref=https://exemplo.com/seu-audio-de-referencia.wav ref_text="texto dito no áudio de referência"
---
# Exemplo de narração de filme (substitua actor_id / ref pelas suas vozes)
[narrator] Um entregador comum encontrou um celular que podia ver o futuro.
[pause 0.5]
[heroi]: Se amanhã eu estiver nas notícias, o que devo fazer hoje?
[narrator] O que ele não sabia é que, cada vez que via o futuro, a realidade mudava silenciosamente.

Integração com edição

# Substituir trilha de áudio original do vídeo (precisa de ffmpeg local)
ffmpeg -i video_original.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest video_narrado.mp4
# Queimar legendas no vídeo
ffmpeg -i video_narrado.mp4 -vf subtitles=out/voiceover.srt -c:a copy video_final.mp4

• 剪映 / CapCut / Premiere: Importe voiceover.wav para a trilha de áudio e voiceover.srt para a trilha de legendas.
• Sincronizar por frase: manifest.json contém start / end em segundos para cada frase, usado para cortar cenas, colocar texto na tela, alinhar segmentos de avatar digital.
• Ferramentas de avatar digital: voiceover.wav é áudio de voz pura, pode ser usado diretamente como áudio de condução; se precisar de MP3 ou taxa de amostragem específica, use ffmpeg para converter.

Comparação de soluções: AI Narração, narração humana e modelo local

Item de comparação	Narração humana	Modelo TTS open-source local	Esta skill
Precisa de GPU?	Não, mas precisa de ambiente de gravação e disponibilidade do locutor	Geralmente sim (modelos pequenos podem usar CPU, mas mais lentos), além de baixar pesos do modelo e configurar ambiente	Não, só executa Python padrão localmente, a geração é feita na nuvem
Custo de revisão	Alterar uma frase geralmente requer regravação e realinhamento	Após a alteração, é necessário executar novamente, mas segmentação, concatenação e alinhamento são manuais	Altere apenas aquela linha e execute novamente; as outras frases reutilizam o cache out/lines/, com remontagem automática da trilha e legendas
Multi-personagem	Requer vários locutores gravando separadamente	Depende do modelo, geralmente requer segmentação manual e concatenação	Use tags [personagem] no roteiro, um comando gera a trilha multi-personagem completa
Timestamps de legendas	Requer ditado e sincronização separados	Geralmente requer passar por reconhecimento de fala novamente	Gera SRT e timestamps por frase (manifest.json) simultaneamente à narração
Performance emocional complexa	Humano ainda é o melhor em boa forma	Depende do modelo e ajuste de parâmetros	Consistente e estável, adequado para transmissão de informação e produção em massa; performance emocional de alto nível ainda recomenda humano

Conclusão: Para conteúdo com atualizações diárias, múltiplas versões e revisões frequentes, esta skill tem a maior vantagem em custo de revisão e timestamps de legendas; para conteúdo único de altíssima exigência emocional, a narração humana ainda vale a pena.

Perguntas frequentes (FAQ)

AI Narração precisa de GPU ou modelo instalado localmente? Não. A geração é feita na nuvem da Miragea, localmente só precisa de Python 3.9+ biblioteca padrão, sem pip install.

Como usar minha própria voz na AI Narração? Duas maneiras: use um personagem já clonado na sua conta (actors para consultar actor_id), ou forneça uma URL de áudio de referência acessível pelo servidor e escreva o texto real dito nele (ref_text=). Os requisitos de amostra e custos estão conforme capabilities e instruções oficiais.

AI Narração pode ter várias pessoas falando em um vídeo? Sim. Defina vários personagens no início do roteiro, cada um com voz e velocidade, e alterne com [personagem] no corpo; o script gera linha por linha e junta em uma trilha de áudio, gerando legendas simultaneamente.

AI Narração pode ajustar tom e emoção? Pode usar tags de tom: primeiro capabilities para ver as tags[].label do modo de geração selecionado, escreva tags=nome_da_tag no personagem. Além disso, use speed= para ajustar velocidade e [pause] para controlar pausas.

As legendas geradas pela AI Narração são precisas? Os timestamps de início e fim de cada frase vêm da duração real do áudio gerado, distribuídos uniformemente dentro da frase. Para timestamps mais precisos palavra por palavra, execute recognize no áudio final.

Se eu alterar uma frase do roteiro, preciso gerar tudo de novo? Não. Altere aquela linha e execute o mesmo comando novamente; apenas as frases alteradas serão geradas novamente, as outras reutilizam out/lines/, com remontagem automática da trilha e legendas.

AI Narração é paga? Quantos caracteres posso gerar por vez? O consumo é baseado no saldo da conta, o limite de caracteres por frase e as regras de custo estão conforme capabilities retornadas em tempo real; --dry-run não chama a API.

Usar AI Narração no Douyin, Video Accounts resulta em restrição de tráfego? Nenhuma ferramenta pode garantir tráfego. É obrigatório marcar o conteúdo como gerado por IA conforme as regras da plataforma; o tráfego depende mais do conteúdo em si.

Um vídeo já gravado pode gerar legendas automaticamente? Sim, miragea_audio.py recognize --file video.mp4 --wait --output video.srt; adicione --subtitle-format txt para obter o texto puro.

Quais agentes de IA são suportados? Claude Code, Codex, OpenClaw, Cursor, WorkBuddy e outros agentes que executam scripts Python.

Deu problema?

Sintoma	Ação
missing_api_key / MIRAGEA_API_KEY is not set	Gere a Key e export MIRAGEA_API_KEY=...; ou adicione --dry-run primeiro
speakers without a voice	Adicione actor_id= ou ref= para aquele personagem
401	Verifique a Key; não coloque a Key em logs
403	Verifique a permissão de acesso à API da conta
400 / 413	Corrija parâmetros: modo, tag, velocidade, caracteres por frase; ou reduza o arquivo de upload, encurte a mídia
409	Chave de idempotência usada para entrada diferente, ou tarifa de legendas alterada: reconfirme e reenvie
429	Saldo insuficiente ou limite de taxa, aguarde ou recarregue saldo
Timeout / Interrupção de rede	A tarefa pode ainda estar em execução: execute o mesmo comando novamente (a mesma chave de idempotência recupera a tarefa original), ou use miragea_audio.py task / wait task_id para continuar consultando, não reenvie com chave diferente
Erro de formato WAV ao concatenar	Cada áudio de frase está salvo em out/lines/, pode ser concatenado com software de edição ou ffmpeg

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

Conformidade

• Clone apenas sua própria voz ou de quem tenha autorização explícita, não imite celebridades, âncoras, figuras públicas ou qualquer pessoa não autorizada.
• De acordo com as "Medidas de Identificação de Conteúdo Gerado por IA" e as regras do Douyin, Kuaishou, Video Accounts, Xiaohongshu, Bilibili, etc., declare ou marque o conteúdo como gerado por IA ao publicar.
• scripts/miragea_audio.py é o cliente oficial, enviado inalterado; scripts/voiceover.py (camada de concatenação de roteiro) é original, licença MIT (veja LICENSE.txt). A capacidade de narração e legendas é fornecida pela API aberta da Miragea.

English Summary

• AI voiceover & subtitles (AI配音) for agents: write a script with [speaker] tags, run one command, get voiceover.wav, timed voiceover.srt and manifest.json.
• Voices: saved voices in your account (actor_id) or voice cloning from a reference audio URL plus its transcript; generation modes, tone tags, speed 0.25–4.
• Multi-speaker scripts are rendered line by line through the official client's generate and joined locally; recognize turns existing audio/video into SRT/TXT/JSON.
• Limits and pricing come live from capabilities. Python 3.9+ standard library, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

Palavras-chave: AI Narração, Narração de Vídeo, Clonagem de Voz, Geração de Legendas, Texto-para-Fala, Texto para Fala, Síntese de Voz, Réplica de Voz, Narração Multi-Personagem, Narração para Vídeos Curtos, Narração para Vlog, Narração para Filmes, Narração para Romances, Narração para Comerciais, Narração em Inglês, Narração IA, SRT, TTS, voiceover, voice cloning, text to speech, subtitles