renky1025/agent-skills

video-dubbing: Dublagem de Vídeo, Tradução e Sincronização de Legendas

Propósito

Localizar um vídeo completo para outro idioma: reconhecer a fala original, traduzir, gerar a dublagem no idioma de destino usando TTS, mantendo os carimbos de data/hora originais, sintetizar a trilha de áudio e queimar as legendas traduzidas no vídeo. O resultado é um único arquivo de vídeo pronto para publicação, com dublagem e legendas naturalmente sincronizadas, sem necessidade de reajuste manual.

Quando Usar

• O usuário solicita a tradução de um vídeo para outro idioma, com dublagem (não apenas legendas).
• Necessidade de adicionar dublagem + legendas sincronizadas no idioma de destino (bilíngue ou apenas traduzidas).
• Palavras-chave: tradução de vídeo, dublagem de vídeo, legendas traduzidas, narração em idioma estrangeiro, dublar um vídeo, traduzir um vídeo, narração em língua estrangeira.
• Qualquer fluxo de trabalho que envolva ASR -> tradução -> TTS -> síntese de vídeo.

Quando NÃO Usar

• Apenas transcrição, sem necessidade de tradução ou dublagem -> usar video-minutes ou Whisper diretamente.
• Apenas sintetizar texto em áudio, sem envolver vídeo -> usar mlx-tts.
• Necessidade de preservar música de fundo/efeitos sonoros e fazer mixagem profissional (separação de vozes) -> esta skill não aplica Demucs por padrão; processamento adicional é necessário.
• Vídeo sem trilha de áudio ou com qualidade muito baixa para reconhecimento de fala.

Fluxo de Trabalho

Recomenda-se usar o script de orquestração <skill>/scripts/dub.py (veja ## Scripts), que executa automaticamente todas as etapas abaixo e pausa na etapa de tradução aguardando a tradução por IA. Para execução manual, siga os passos:

1. Extrair trilha de áudio (16 kHz mono): ffmpeg -y -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le audio16k.wav

2. Transcrição ASR (com carimbos de data/hora precisos por segmento): whisper audio16k.wav --model large-v3-turbo --language <idioma_origem> --output_format srt --output_dir . Gera audio16k.srt, com timestamps naturalmente alinhados ao vídeo original. Para melhor reconhecimento de chinês, pode-se usar Qwen3-ASR (instale com pip install qwen-asr) e o script <skill>/scripts/qwen3_asr.py.

3. Traduzir legendas (feita pela IA): Ler o SRT e traduzir segmento por segmento. Cada segmento do SRT deve gerar uma linha de tradução, mantendo rigorosamente a ordem. Primeiro, conte o número de segmentos (ex.: 27 segmentos -> 27 linhas) e salve em translated.txt. Antes de prosseguir, verifique se o número de linhas coincide.

4. Gerar dublagem: python3 <skill>/scripts/dub_segments.py audio16k.srt translated.txt dubbing.wav subtitle_synced.srt --lang <idioma_destino> O script: usa o primeiro segmento como referência de timbre para garantir consistência de voz; mantém os timestamps originais para que as legendas sincronizem com o vídeo; aplica variação de velocidade (atempo 0.88–1.20) apenas nos segmentos que excedem o slot; e une intervalos adjacentes menores que 1s para tornar a audição mais natural.

5. Mesclar trilha de dublagem ao vídeo:

   ffmpeg -y -i input.mp4 -i dubbing.wav \
     -map 0:v:0 -map 1:a:0 \
     -c:v copy -c:a aac -b:a 192k -shortest output_temp.mp4
   

   Em seguida, confirme que a trilha de áudio foi substituída: ffprobe -v error -show_entries stream=codec_type -of csv=p=0 output_temp.mp4 (deve exibir video, audio).

6. Queimar legendas (hard-burn): python3 <skill>/scripts/burn_subtitles.py output_temp.mp4 subtitle_synced.srt output_final.mp4 Renderiza as legendas traduzidas permanentemente no vídeo.

7. Limpeza (opcional): Remover arquivos intermediários como audio16k.wav, audio16k.srt, translated.txt, dubbing.wav, subtitle_synced.srt, output_temp.mp4.

Regras de Decisão

• Para execução completa de uma só vez -> usar dub.py; para apenas reexecutar uma etapa (ex.: já possui SRT) -> usar dub.py --srt existing.srt para pular etapas.
• Motor ASR: padrão --asr whisper (large-v3-turbo); para reconhecimento de chinês de alta qualidade -> --asr qwen3.
• Se não precisar de legendas queimadas -> dub.py --no-burn (somente mesclagem de áudio).
• O idioma de destino é definido por --target-lang (padrão zh); o idioma TTS do dub_segments.py é definido por --lang.
• A tradução deve ser feita pela IA e deve corresponder estritamente 1:1 com os segmentos do SRT; se o número de linhas não coincidir, o script reporta erro e termina, não contorne.
• Se as legendas não aparecerem ou caracteres chineses virarem quadrados -> usar burn_subtitles.py (renderização com moviepy, que encontra automaticamente fontes chinesas). Não depender do subtitles= do ffmpeg (que pode falhar silenciosamente se libass estiver ausente).
• Se a duração da dublagem exceder o slot -> usar a variação de velocidade por segmento do script, não aplicar variação global na trilha inteira.

Restrições

• Os carimbos de data/hora devem reutilizar os resultados originais do ASR, é proibido reexecutar ASR na dublagem para obter timestamps.
• O número de linhas traduzidas deve ser igual ao número de segmentos do SRT (1:1); caso contrário, interrompa.
• Ao mesclar a trilha de áudio, deve-se usar explicitamente -map 0:v:0 -map 1:a:0, caso contrário a trilha original será mantida.
• O ASR deve usar large-v3-turbo (ou turbo), não recuar para base/tiny.
• A variação de velocidade é aplicada apenas no nível do segmento, no intervalo 0.88–1.20x; proibido atempo global.
• Por padrão, não faz separação de voz e música de fundo; se o usuário solicitar, deve-se indicar explicitamente que é necessário processamento adicional.

Verificação

Antes da entrega, verifique cada item:

• O número de linhas em translated.txt corresponde exatamente ao número de segmentos do SRT.
• dubbing.wav e subtitle_synced.srt foram gerados.
• ffprobe mostra que o vídeo final contém fluxos de vídeo e áudio, e que o áudio foi substituído.
• As legendas foram queimadas no vídeo (não são legendas externas), e caracteres chineses não aparecem como quadrados.
• A dublagem e o vídeo estão sincronizados em alguns pontos aleatórios verificados.
• Os arquivos de origem fornecidos pelo usuário não foram deletados.

Saída

• Resultado: Um arquivo de vídeo localizado (por padrão output_final.mp4, com dub.py é <nome_do_vídeo>_<idioma_destino>.mp4), contendo dublagem e legendas queimadas no idioma de destino; também pode manter subtitle_synced.srt.
• Concluído quando: A trilha de áudio foi substituída, as legendas foram queimadas, áudio e vídeo sincronizados nos pontos verificados, e a validação com ffprobe foi aprovada.
• Evidência: Caminho do arquivo final; número de segmentos SRT vs. linhas traduzidas; lista de fluxos do ffprobe; pontos de sincronia verificados.

Referências

Carregue sob demanda, não leia tudo antecipadamente:

• references/pipeline-design.md — Leia quando precisar explicar ou ajustar o comportamento do pipeline (por que manter timestamps, variação de velocidade por segmento, padrão sem separação de vozes, lista de artefatos e dependências).
• references/troubleshooting.md — Leia em caso de erros reais, dessincronia de áudio/vídeo, legendas ausentes ou caracteres chineses em quadrados.

Scripts

• <skill>/scripts/dub.py — Orquestração de ponta a ponta. Uso: python3 <skill>/scripts/dub.py input.mp4 --source-lang en --target-lang zh [--asr whisper|qwen3] [--srt existing.srt] [-o out.mp4] [--font-size 28] [--no-burn] [--keep-temp]. Durante a execução, na etapa de tradução, gera to_translate.txt e solicita que a IA traduza para translated.txt, depois continua; retorna o caminho do vídeo final e o caminho das legendas.
• <skill>/scripts/dub_segments.py — TTS segmentado + alinhamento de timestamps. Uso: python3 <skill>/scripts/dub_segments.py original.srt translated.txt out_dub.wav out_synced.srt [--lang zh] [--min-atempo 0.88] [--max-atempo 1.20] [--gap-bridge 1.0] [--keep-temp]. Retorna dubbing.wav e subtitle_synced.srt alinhados; se o número de linhas traduzidas não corresponder, aborta com código de saída 1.
• <skill>/scripts/burn_subtitles.py — Queima legendas usando moviepy. Uso: python3 <skill>/scripts/burn_subtitles.py input.mp4 subtitles.srt output.mp4 [--font <caminho>] [--font-size 28]. Retorna o vídeo com legendas queimadas; se --font não for especificado, detecta automaticamente uma fonte chinesa.
• <skill>/scripts/qwen3_asr.py — CLI compatível com Whisper usando Qwen3-ASR, com melhor reconhecimento de chinês. Uso: python3 <skill>/scripts/qwen3_asr.py audio.wav [--model 0.6B|1.7B] [--language zh] [-f srt|vtt|txt|json|tsv|all] [-o diretório_saída] [--device cuda:0|mps|cpu] [--dtype float16|bfloat16|float32]. Retorna arquivos de legenda/texto no formato especificado. Apelidos de modelo: turbo/tiny/base/small -> Qwen3-ASR-0.6B, medium/large -> Qwen3-ASR-1.7B.

Solução de Problemas

• A dublagem não foi substituída / ainda tem o áudio original -> a mesclagem com ffmpeg omitiu -map 0:v:0 -map 1:a:0.
• Legendas não aparecem ou caracteres chineses viram quadrados -> usar burn_subtitles.py e especificar --font com uma fonte chinesa.
• Número de linhas traduzidas não corresponde aos segmentos SRT -> o script reporta erro e termina; corrija para a proporção 1:1.
• Lista completa de erros em references/troubleshooting.md.

Skills Relacionadas

• mlx-tts — Fornece o mlx_audio.tts.generate subjacente, do qual esta skill depende para TTS.
• video-minutes — Para converter vídeos em atas estruturadas; use quando precisar apenas de transcrição/resumo.