yyert123/legendas-video

Legendas de vídeo

Um comando transforma um arquivo de vídeo (ou áudio) em legendas agradáveis de ler e, opcionalmente, em um MP4 legendado. Segmentos brutos de reconhecimento de fala frequentemente quebram palavras no meio ("cen" / "ts") e ficam muito longos; esta skill reconstrói palavras completas e as reorganiza em quadros de legenda adequados.

Quando usar

• "Adicionar legendas a este vídeo", "criar um SRT para minha palestra", "queimar legendas".
• "Fazer legendas no estilo TikTok/Reels/Shorts" -> use --style shorts --burn.
• O usuário precisa de um .vtt para <track> em site ou upload no YouTube.

Passos

1. Verifique se MIRAGEA_API_KEY está definida (nunca a imprima). Se não estiver, diga ao usuário para criar uma chave em https://miragea.ai e export MIRAGEA_API_KEY=....

2. Execute o script no arquivo do usuário:

   python3 scripts/captions.py caminho/para/video.mp4                 # -> video.srt + video.vtt
   python3 scripts/captions.py caminho/para/video.mp4 --burn          # + video.legendado.mp4
   python3 scripts/captions.py caminho/para/short.mp4 --style shorts --burn   # legendas pop, centralizadas
   

3. Leia o JSON que ele imprime (srt, vtt, video, cues) e informe os caminhos ao usuário.

4. Se o usuário quiser corrigir o texto, edite o .srt (mantendo os timestamps) e execute novamente com --burn: a transcrição fica em cache no arquivo <arquivo>.transcript.json, então reexecuções não custam nada.

Opções

Flag	Padrão	O que faz
--style standard	sim	2 linhas x 42 caracteres, 1 a 7 s por legenda (convenções de transmissão)
--style shorts		1 a 3 palavras por legenda, MAIÚSCULAS, centralizadas quando queimadas
--burn	desligado	Gera <nome>.legendado.mp4 (H.264, áudio original copiado)
--upper	desligado	Legendas padrão em maiúsculas
--out-dir DIR	ao lado da entrada	Diretório de saída
--force	desligado	Ignorar cache de transcrição e retranscrever

Custo e limites

Apenas um áudio mono de 16 kHz é enviado (não o vídeo), até 90 minutos / 1 GB por arquivo. Miragea cobra 3 pontos por segundo de áudio; reexecuções em cache são gratuitas. Verifique taxas atualizadas com GET https://miragea.ai/v1/capabilities.

Solução de problemas

• ffmpeg não encontrado -> instale ffmpeg (brew install ffmpeg, sudo apt install ffmpeg, winget install ffmpeg).
• 401 -> chave errada; 402 -> recarregue em miragea.ai; 429 -> aguarde e execute novamente (seguro tentar de novo).
• Legendas ligeiramente adiantadas/atrasadas em clipes com muita música: execute novamente com --force após cortar introduções.

Veja examples/ para exemplos de saída.