screen-recording-voiceover

Narração de gravação de tela

A parte lenta de narrar uma gravação de tela não é a voz, é a sincronia: alinhar cada frase com o clique que ela descreve e corrigir os lugares onde a frase é mais longa que a ação. Esta skill faz ambos automaticamente e nunca deixa a narração derivar ou se sobrepor.

Quando usar

• "Adicione uma narração a esta demonstração / tutorial / gravação de tela."
• "Gravei minha tela silenciosamente, narre-a" ou "Não quero usar minha própria voz / sotaque."
• "Faça a narração coincidir com o que acontece na tela."

Passos

1. Verifique se MIRAGEA_API_KEY está definida (nunca a imprima). Voz: pergunte uma vez o ID da voz Miragea do usuário, ou uma URL pública de um clipe da voz dele mais as palavras exatas. Sugira export MIRAGEA_VOICE_ID=... para que nunca seja perguntado novamente. Apenas clone uma voz que o usuário possua ou tenha permissão para usar.

2. Encontre as etapas e crie um modelo de roteiro:

   python3 scripts/scenes.py demo.mp4      # -> demo.frames/*.jpg, demo.frames/steps.json, demo.script.txt
   

3. Observe os quadros em demo.frames/ (você pode ler imagens) e escreva uma frase clara por etapa no demo.script.txt após cada timestamp, substituindo o comentário # step. Mantenha-se dentro da dica ~N palavras para que a linha caiba antes da próxima etapa. Mescle, mova ou exclua etapas livremente. Se o usuário forneceu seu próprio roteiro, coloque suas frases nos timestamps correspondentes.

4. Verifique o tempo sem gastar nada:

   python3 scripts/voiceover.py demo.mp4 demo.script.txt --dry-run
   

   Encurte qualquer linha marcada como will freeze se o usuário quiser zero quadros congelados.

5. Renderize:

   python3 scripts/voiceover.py demo.mp4 demo.script.txt --voice VOICE_ID            # legendas como arquivos
   python3 scripts/voiceover.py demo.mp4 demo.script.txt --burn --music bed.mp3      # legendas incorporadas + música com redução
   

6. Forneça ao usuário os caminhos do JSON impresso: video (MP4 narrado), voice_track (WAV para o editor dele), srt/vtt. Mencione frozen_seconds se for maior que zero.

7. Para alterar uma linha, edite o roteiro e execute o passo 5 novamente: linhas inalteradas vêm do cache gratuitamente.

Formato do roteiro

[00:00] Bem-vindo à Acme. Aqui está o painel que você vê após fazer login.
[00:04] Clique em Novo Projeto, digite um nome e escolha a equipe que deve possuí-lo.
[01:02.5] É isso. Seu projeto está pronto.

Timestamps aceitos: [mm:ss], [h:mm:ss], mm:ss.s, 12.5s. Linhas começando com # são comentários.

Como a sincronia funciona

• Cada linha começa exatamente no seu timestamp; 0,25 s de margem são mantidos antes da próxima etapa.
• Uma linha mais longa que seu espaço é acelerada, no máximo --max-speed (padrão 1.15x, ainda natural).
• Se ainda assim não couber, o vídeo segura o último quadro daquela etapa até a frase terminar, então continua. Linhas posteriores são deslocadas pela mesma quantidade, então a sincronia nunca é perdida.
• As legendas são temporizadas a partir do comprimento real falado de cada linha (máximo 2 linhas x 42 caracteres).
• O volume é normalizado para aproximadamente -16 LUFS (padrão YouTube/web). Música, se fornecida, tem volume reduzido sob a fala.

Opções

Flag	Padrão	O que faz
--voice ID / --ref-url URL --ref-text TEXT	env	Voz Miragea salva, ou clone a partir de um clipe público (texto exato = tarifa 1x mais barata)
--model	expressive	ou standard
--max-speed	1.15	Aceleração máxima antes de congelar quadros
--burn	desligado	Incorporar legendas no vídeo
--music FILE	nenhum	Música de fundo, em loop e com redução automática
--keep-audio	desligado	Manter o som original da gravação, baixo, sob a voz
--dry-run		Mostrar o plano de slots com uma taxa de fala estimada; sem chamadas de API
-o FILE	VIDEO.voiceover.mp4	Caminho de saída; o original nunca é modificado

Custo e limites

A fala é cobrada por caractere pela Miragea (1x com uma voz salva ou texto de referência exato; taxas ao vivo em GET https://miragea.ai/v1/capabilities). Uma demonstração de 3 minutos geralmente tem 2.000-3.000 caracteres. Cada linha deve ter menos de 2.000 caracteres. Clipes de referência devem ser URLs públicas até que o endpoint de upload da Miragea seja lançado.

Solução de problemas

• no timestamp / not after the previous line -> corrija a linha do roteiro mencionada no erro.
• no voice chosen -> passe --voice ou defina MIRAGEA_VOICE_ID.
• 401 chave errada, 402 recarregue em miragea.ai, 429 aguarde e execute novamente (linhas em cache não são cobradas novamente).
• Muitas ou poucas etapas do scenes.py -> --threshold 0.02 (mais) / 0.08 (menos), --min-gap.

Veja examples/ para um roteiro real, o JSON do plano e as legendas que ele produziu.