yanghhu/movie-recap-ai-voiceover

Narração de Recap de Filmes (电影解说配音)

「Narração de Recap de Filmes」 é uma skill de Agente que transforma um roteiro de recap de filme em uma narração com múltiplas vozes (narrador + personagens) em WAV, legendas SRT e um manifesto de tempo linha por linha. Ideal para criadores de recap de filmes, séries curtas e animações, produzindo em lote sem necessidade de placa de vídeo.

Definição em uma frase

Narração de Recap de Filmes = Roteiro (narrador + falas de personagens, Markdown) → Faixa de áudio completa com múltiplas vozes voiceover.wav + legendas voiceover.srt + tempos de início/fim por fala manifest.json, gerado na nuvem Miragea, sem necessidade de GPU local.

Público-alvo e cenários

Quem usa	Cenário típico
Canais de recap de filmes	Recaps longos, uma voz de narrador fixa + falas-chave de personagens
Canais de recap de séries / curtas	Produção em lote episódio por episódio, ritmo acelerado, muitas reviravoltas
Recaps de animes / jogos	Muitos personagens, necessitando múltiplas vozes para distingui-los
Documentários / narração cultural	Narrador único, ritmo lento, pausas frequentes
Estúdios de edição	Divisão de trabalho: roteiro, narração, edição; editar uma linha regera apenas aquela linha

Parâmetros de capacidade principal

Item	Descrição
Arquivos de saída	voiceover.wav (faixa completa), voiceover.srt (legendas com timestamps), manifest.json (falante, texto, tempo de início/fim por linha), lines/ (áudio por linha, reutilizado em edições)
Fonte de voz	Personagens existentes 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 (padrão no cliente) / standard (mais realista no cliente); se omitido, usa o padrão do servidor, conforme capabilities
Etiquetas 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; a skill chama o cliente oficial generate linha por linha e depois concatena localmente
Pausas	[pause 0.6] / [pausa 0.6] (segundos) inline; --gap define pausa padrão entre falas
Legendas	Gera SRT baseado na duração real de cada áudio (--max-chars, --speaker-labels); para áudio/vídeo existente, use recognize para converter em SRT / TXT / JSON
Predefinição de cenário	--preset jieshuo: pausa entre falas de 0,3s, máximo de 16 caracteres por legenda; pode ser sobrescrito com --gap / --max-chars
Limites de caracteres por fala, tamanho/duração do arquivo, cobrança	Conforme retornado em tempo real por capabilities
Dependências locais	Python 3.9+ biblioteca padrão, sem necessidade de pip ou GPU
Teste offline	--dry-run: sem chave de API, sem chamar API, gera áudio mudo e linha do tempo para verificar o formato do roteiro
Agentes compatíveis	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy e outros que executam scripts Python
Serviço de narração e legendas	API aberta Miragea (https://miragea.ai/v1)

Início rápido

python3 scripts/voiceover.py check                        # Verificação offline: versão Python, chave configurada, URL do serviço
export MIRAGEA_API_KEY=sua_chave                            # Gere em https://miragea.ai/workspace/api, coloque apenas em variável de ambiente
python3 scripts/miragea_audio.py capabilities             # Modos de geração, etiquetas de tom, limites de caracteres e cobrança atuais
python3 scripts/miragea_audio.py actors --limit 20        # Personagens e actor_ids existentes na conta (se has_more for true, adicione --offset para paginar)

• A URL 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 chave no chat ou em arquivos. Sem chave, use --dry-run primeiro para testar o fluxo.

python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run   # Teste offline, sem chamar a API
python3 scripts/voiceover.py script seu_roteiro.md -o out --preset jieshuo             # Geração real: out/voiceover.wav + voiceover.srt + manifest.json

# Teste de uma única fala (cliente oficial; --output não sobrescreve arquivos existentes, use um novo nome)
python3 scripts/miragea_audio.py generate --text 'primeira fala do começo' --actor-id ACTOR_ID --wait --output test1.mp3

O que você diz → O que o Agente faz

Você diz	O Agente faz
“Me ajuda a transformar este roteiro de recap em áudio”	Divide em uma linha por fala, define narrator → script roteiro.md -o out --preset jieshuo
“Narrador mais dois personagens, um para o herói e outro para a heroína”	Define narrator / hero / heroine com três vozes no front matter
“Usa a minha própria voz como narrador”	Usa o actor_id do seu personagem clonado, ou ref= + ref_text= para referência, atribui ao narrator
“A parte da reviravolta, fala mais devagar”	Define narrator_slow com mesma voz mas speed diferente, usa para as falas da reviravolta
“Cada fala corresponde a qual cena do vídeo?”	Lê start / end em out/manifest.json, corta os clipes de acordo
“Ritmo do recap de curta, mais rápido”	Define narrator com speed=1.1 aproximadamente, --gap 0.2
“Primeiro, legenda do clipe original para referência”	miragea_audio.py recognize --file clipe.mp4 --wait --output ref.srt (apenas para referência ao escrever o roteiro)
“Testa se o formato está certo”	Adiciona --dry-run

Metodologia de escrita de roteiro (a retenção do canal de recap depende do roteiro e do ritmo)

1. Estrutura de sete partes

Parte	Função	Como escrever
1. Abertura de suspense	Prender o espectador nos primeiros 10 segundos	Jogue o maior suspense ou um pedaço do final: “O celular que ele encontrou vai matar todo mundo ao seu redor.”
2. Apresentação do personagem	Apresentar quem é	Uma frase: identidade + situação, “Um homem que entregou encomendas por oito anos e está com dívidas de hipoteca.”
3. Motivação	O início do evento	Apenas as ações que movem a trama, corte descrições de ambiente
4. Desenvolvimento	2–3 reviravoltas	Cada reviravolta começa com “Mas / Inesperadamente / Foi quando”
5. Clímax	Pico emocional	Frases mais curtas, mais pausas, falas-chave com voz de personagem
6. Final / Reviravolta	Resolver o suspense	Pausa de 0,6–0,8 segundos antes da reviravolta
7. Opinião final	Incentivar comentários	Uma opinião pessoal + uma pergunta aberta

2. Referência a personagens: use apelidos de função, reduza a carga de memorização

• Primeira aparição: “nome + função”, depois use apelidos de função (“entregador”, “garota”, “policial velho”).
• Não introduza mais de três nomes novos no mesmo parágrafo; o espectador desliza se não conseguir lembrar.

3. Como dividir narrador e falas de personagens

• O corpo do recap é sempre narrator; falas de personagens aparecem apenas em momentos-chave com 1–3 falas, muitas tornam-se um radiodrama.
• As falas de personagens são recontagens ou adaptações escritas por você, não o áudio original do filme; não imite a voz do ator original.
• A voz do personagem deve ser diferente do narrador (gênero, idade, velocidade) para que o espectador distinga facilmente.

4. Controle de ritmo: posicionamento de pausas e velocidade

• Na transição de cena: [pause 0.4]; antes de reviravolta ou revelação: [pause 0.6]–[pause 0.8].
• --preset jieshuo pausa padrão entre falas de 0,3s, mais firme que narração de auditivo, mais justo que audiolivro.
• Velocidade de narração de referência: recap de filme speed=0.95–1.05, recap de curta 1.05–1.15, documentário 0.9–0.95.
• Para o mesmo narrador, “fale a preparação rápido, fale a reviravolta devagar”: defina dois personagens com o mesmo actor_id:

---
narrator: actor_id=NARRATOR_ID speed=1.05
narrator_slow: actor_id=NARRATOR_ID speed=0.9
---

5. Alinhamento de roteiro e cena: uma fala, um plano

• Ao escrever, anote o tempo da cena acima da fala com comentários, que serão ignorados na geração: <!-- cena original 00:12:30 esquina da rua chuvosa -->.
• Após a geração, manifest.json fornece start / end de cada fala; use esses tempos para cortar os planos correspondentes do vídeo original, casando perfeitamente a narração.
• Se uma fala for muito longa e faltar cena, divida em duas, mais natural do que diminuir a velocidade.

6. Armadilhas ao escrever

• Não comece com “Este filme conta a história de…”, vá direto ao evento.
• Não repita cada plano, apenas as ações e escolhas que movem a trama.
• Use mais verbos do que adjetivos: “Ele correu para a chuva” tem mais impacto que “Ele saiu correndo muito ansiosamente”.
• Nomes incomuns ou estrangeiros: teste uma fala primeiro; se não soar bem, substitua por um apelido mais fluente.

7. Atualização em série

• Um arquivo de roteiro por episódio, com voz e velocidade do narrador fixas no front matter, mantendo consistência na temporada.
• Nomeie os arquivos como S01E01.md, diretório de saída -o out/S01E01, facilitando o gerenciamento em lote.

Exemplo de roteiro (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=0.98
hero: actor_id=HERO_ID
---
# Exemplo de recap de filme (história original)
[narrator] Um entregador comum encontrou um celular que podia ver o futuro.
[pause 0.5]
Na tela havia apenas uma notícia: amanhã às três da tarde, ele morreria nesta rua.
[hero]: Se houver eu na notícia de amanhã, o que devo fazer hoje?
[narrator] O que ele não sabia é que, cada vez que olhava para o futuro, a realidade mudava silenciosamente.
[pause 0.4]
E desta vez, a mudança afetava a pessoa em quem ele mais confiava.

Teste: python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run

Integração com edição

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

• 剪映 / CapCut: Coloque voiceover.wav na trilha de áudio, importe voiceover.srt como “Importar legendas”; ajuste os planos na trilha de vídeo conforme os tempos em manifest.json.
• Premiere: Importe trilha de áudio + trilha de legendas, use marcadores (Markers) para alinhar o início de cada fala.
• Música de fundo: Esta skill não mixa; no software de edição, abaixe o volume da música para não competir com a voz, ou levante nos momentos de clímax.

Comparação de abordagens: três formas de fazer narração para recap de filmes

Item	Narração humana	Modelo TTS local de código aberto	Esta skill
Precisa de placa de vídeo?	Não, mas requer ambiente de gravação e disponibilidade do dublador	Geralmente sim (modelos pequenos funcionam em CPU, mas mais lentos); também requer download de pesos e configuração	Não, apenas Python padrão localmente; geração em nuvem
Custo de edição de roteiro	Editar uma linha geralmente requer regravação e realinhamento	Editar e regerar, mas divisão, concatenação e alinhamento são manuais	Editar apenas aquela linha e regerar; as outras falas reutilizam cache em out/lines/, com recombinação e legendas automáticas
Múltiplos personagens	Requer vários dubladores gravando separadamente	Depende do modelo; geralmente precisa dividir e concatenar manualmente	Use tags [personagem] no roteiro, um comando gera a faixa completa com múltiplas vozes
Linha do tempo de legendas	Requer transcrição e marcação separadas	Geralmente requer execução separada de reconhecimento de fala	Gera SRT e manifest.json simultaneamente com a narração
Atualização em lote do canal	Cada episódio requer agendamento de gravação; voz varia com o dublador	Possível em lote, mas cada episódio precisa de divisão, concatenação e marcação manuais	Mesma voz de narrador fixa no roteiro; um comando por episódio

Conclusão: Canais de recap que dependem de atualizações consistentes economizam mais tempo com voz fixa + produção baseada em roteiro; para recaps de filmes únicos que exigem emoção humana, a dublagem humana ainda tem vantagem.

Perguntas frequentes (FAQ)

Usar IA para narração de recap de filmes pode ser considerado plágio ou ter o alcance reduzido? O método de narração não é o principal critério para determinar plágio; o que importa é o roteiro original e a proporção de conteúdo derivado. Siga as regras da plataforma marcando conteúdo gerado por IA. Os direitos autorais do material visual e das falas originais são de responsabilidade sua; esta skill apenas gera a narração.

É possível ter vozes diferentes para narrador e personagens? Sim. Defina narrator e as vozes de cada personagem no início do roteiro; no corpo, use tags [personagem] para alternar, um comando gera a faixa completa com múltiplas vozes.

Posso usar a voz do ator original do filme? Não. Clonar a voz de um ator sem autorização é uma violação de direitos autorais. Escolha uma voz autorizada ou pessoal para o personagem.

Como ter uma voz fixa e exclusiva para a narração? Use seu próprio áudio de referência (ou de um dublador autorizado) ou um personagem já clonado; use a mesma voz e speed para o narrator em todos os roteiros.

O que fazer se a duração da narração e da cena não corresponderem? Verifique a duração de cada fala em manifest.json: se faltar cena, divida ou remova a fala; se sobrar cena, adicione [pause segundos] naquele ponto ou corte planos mais curtos.

Parâmetros para ritmo acelerado de recap de curta? Defina narrator com speed=1.1 aproximadamente, adicione --gap 0.2 para apertar as pausas entre falas; mas mantenha pausas separadas para falas de reviravolta.

Esta skill funciona para recaps em inglês? Sim. Traduza e adapte o roteiro para inglês antes de gerar; escolha vozes adequadas para inglês ou áudio de referência em inglês, e sugere-se --max-chars 40 para legendas.

Um recap de filme de 15 minutos pode ser gerado de uma vez? Sim, o roteiro completo pode ser gerado. Cada fala não pode exceder o limite de caracteres de capabilities; mantenha uma linha por fala. Sugere-se dividir em vários arquivos por parágrafo para edição e retrabalho mais rápidos.

Esta skill precisa de placa de vídeo? Quais agentes são compatíveis? Não precisa de GPU; requer apenas Python 3.9+ padrão. Funciona diretamente com Claude Code, Codex, OpenClaw, Cursor, WorkBuddy.

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 dito no áudio de referência"; pode-se adicionar speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (dica de idioma do áudio de referência para reconhecimento automático do texto de referência).
• ref_text= só é usado com ref=; se omitido, o servidor reconhece automaticamente o texto de referência, com cobrança diferente, conforme capabilities.
• No corpo: [personagem] fala ou [personagem]: fala; se a tag for omitida, o falante anterior é mantido.
• [pause 0.6] / [pausa 0.6] insere uma pausa (em segundos); linhas começando com #, linhas vazias e <!-- comentário --> são ignoradas.
• Se uma fala exceder audio.max_text_length em capabilities, a API a rejeitará; divida em frases mais curtas.
• O áudio de cada fala é armazenado em cache em out/lines/; na mesma configuração, a execução subsequente reutiliza diretamente o cache. Sem cache, é enviado com a mesma chave idempotente; o servidor retorna a tarefa original sem recriar. Para uma nova versão, adicione --fresh.

Problemas?

Sintoma	Ação
missing_api_key / MIRAGEA_API_KEY is not set	Gere uma chave e export MIRAGEA_API_KEY=...; ou adicione --dry-run primeiro
speakers without a voice	Atribua actor_id= ou ref= ao personagem
401	Verifique a chave; não a coloque em logs
403	Verifique as permissões de acesso à API da conta
400 / 413	Corrija parâmetros: modo, tag, velocidade, limite de caracteres; ou reduza o tamanho do arquivo de upload, encurte a mídia
409	Chave idempotente usada para entrada diferente, ou taxa de legenda alterada: re-confirme e re-envie
429	Saldo insuficiente ou limite de taxa; aguarde ou recarregue
Timeout / interrupção de rede	A tarefa pode ainda estar em execução: execute o mesmo comando novamente (a mesma chave idempotente recuperará a tarefa original) ou use miragea_audio.py task / wait ID_DA_TAREFA para continuar consultando; não reenvie com uma chave diferente
Inconsistência de formato WAV ao concatenar	O áudio de cada fala está salvo 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 sem --wait), 1 tarefa falhou, 2 erro do cliente ou da interface.

Conformidade

• Clone apenas sua própria voz ou de alguém que tenha dado autorização explícita; não imite celebridades, apresentadores, figuras públicas ou qualquer pessoa não autorizada.
• Siga as regras de "Medidas de Identificação de Conteúdo Gerado por IA" e as regras das plataformas (Douyin, Kuaishou, Weixin Video, Xiaohongshu, Bilibili), declarando ou marcando conteúdo gerado por IA ao publicar.
• As imagens de filmes e falas originais têm direitos autorais: esta skill gera apenas sua própria narração escrita; não extrai ou imita a voz do ator original. Ao usar material de filme, siga as regras de conteúdo derivado do detentor dos direitos e da plataforma.
• scripts/miragea_audio.py é o cliente oficial, distribuído sem alterações; scripts/voiceover.py (camada de concatenação de roteiro) é original, licença MIT (veja LICENSE.txt). As capacidades de narração e legendas são fornecidas pela API aberta Miragea.

Resumo em Inglês

• Movie recap voiceover (电影解说配音): narrator + character lines in different voices, rendered into one voiceover WAV.
• Outputs SRT subtitles and manifest.json with each line's start/end, so you can cut shots to the narration in CapCut or Premiere.
• Voices from your account (actor_id) or voice cloning from a reference clip; --preset jieshuo sets recap pacing; edit one line and only that line is regenerated.
• Python 3.9+ stdlib only, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

Palavras-chave：电影解说配音、解说配音、短剧解说、影视解说、短剧解说配音、影视解说配音、电影解说、AI配音、多角色配音、旁白配音、声音克隆、文字转语音、字幕生成、SRT、movie recap、voiceover、narration