YouTube Subtitle Translator
Baixe vídeos do YouTube, extraia e processe legendas (corrigir + pontuar + traduzir) e, em seguida, renderize-as de volta no vídeo. Lida com legendas geradas automaticamente e uploads manuais, com fallback para ASR quando não houver legendas.
Regras Rígidas
- Use no máximo 3 subagentes simultâneos para o processamento de blocos de legendas. Quando houver mais de 3 blocos, execute-os em ondas e inicie o próximo bloco somente após um subagente terminar.
- A contagem de blocos não é concorrência. Você pode dividir em 10 blocos, mas não deve iniciar 10 processos/subagentes do Codex de uma só vez; execute no máximo 3 workers ativos a qualquer momento.
- Sempre baixe apenas a faixa de legenda de origem: inglês quando disponível, caso contrário, o idioma original do vídeo. Não baixe as legendas traduzidas automaticamente pelo YouTube para o idioma de destino; traduza a partir da legenda de origem.
- Nunca use uma faixa de legenda no idioma de destino fornecida pelo YouTube como atalho, mesmo para vídeos longos e mesmo que
zh-Hansou outro idioma de destino esteja listado emautomatic_captions. - O download do vídeo padrão é 1080p. Se 1080p não estiver disponível, baixe a melhor versão disponível abaixo de 1080p.
- A tradução deve ser realizada por subagentes sobre os arquivos de bloco. Não use helpers de modelo local para tradução.
- Antes de escrever SRT/ASS, remova caracteres ilegais de legendas do texto, especialmente barras invertidas soltas (
\) que aparecem visivelmente no vídeo.
Visão Geral do Fluxo de Trabalho
Fase 1: Download → Obter informações do vídeo, baixar vídeo, extrair legendas
Fase 2: Preparar → Se não houver legendas: extrair áudio → executar ASR
Fase 3: Processar → Dividir em blocos → correção + tradução paralela por agente
Fase 4: Mesclar → Combinar blocos → gerar arquivos SRT/ASS
Fase 5: Renderizar → Gravar legendas no vídeo usando ffmpeg
Fase 1: Download
1.1 Obter Informações do Vídeo
Use a ferramenta MCP do YouTube para buscar metadados:
youtube_get_video_info(videoId="...", detail="standard")
Registre: título, duração, canal, se as legendas estão disponíveis.
1.2 Criar Diretório de Saída
Nomeie o diretório com o título do vídeo. Sanitize para o sistema de arquivos:
mkdir -p "/caminho/saída/<Título do Vídeo>"
1.3 Baixar Vídeo
youtube_download(videoId="...", outputPath="<dir>/video.mp4", quality="1080p", force=true)
Se usar yt-dlp, prefira 1080p e recorra ao melhor formato abaixo de 1080p:
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]/best" --merge-output-format mp4 \
-o "<dir>/video.%(ext)s" "<url>"
1.4 Extrair Apenas Legendas de Origem
youtube_get_transcript(videoId="...", language="<idioma-de-origem>")
Se o resultado exceder os limites de token, ele será salvo em um arquivo de resultados da ferramenta — leia-o em blocos.
Esta é uma política de legenda de origem não negociável:
- Prefira legendas/legendas em inglês quando disponíveis.
- Se o inglês não estiver disponível, use o idioma falado original do vídeo.
- Ignore
zh-Hans,zh-Hante qualquer outra faixa de idioma de destino mostrada pelo YouTube, incluindo faixas traduzidas automaticamente. - Não solicite, tente novamente, mescle ou renderize uma faixa de legenda no idioma de destino fornecida pelo YouTube.
- As legendas no idioma de destino devem ser produzidas apenas pela tradução do subagente a partir da legenda de origem.
Se uma ferramenta retornar uma lista como en-orig, zh-Hans, escolha apenas en-orig. Não inclua zh-Hans em nenhum comando de download.
Se usar yt-dlp, escreva apenas a legenda de origem:
yt-dlp --skip-download --write-auto-subs --write-subs \
--sub-langs "en.*" --sub-format srt --convert-subs srt \
-o "<dir>/video.%(ext)s" "<url>"
Errado, não execute:
yt-dlp --write-auto-subs --sub-langs "en-orig,zh-Hans" ...
Se o download da legenda em inglês/original for bem-sucedido, mas uma solicitação de idioma de destino falhar com HTTP 429, não tente novamente a solicitação de idioma de destino. Essa solicitação não deveria ter sido feita; continue a partir da legenda de origem e traduza-a através da Fase 3.
Se as legendas existirem: Salve os segmentos brutos como JSON, prossiga para a Fase 3. Se NÃO houver legendas (404/erro): Prossiga para a Fase 2 (fallback ASR).
Salve os dados brutos:
raw_segments.json— todos os segmentos com texto/offset/duraçãoraw_subtitles.srt— conversão SRT inicial
Fase 2: Fallback ASR (Nenhuma Legenda Disponível)
Quando o vídeo não tem legendas/transcrições:
-
Extrair áudio do vídeo usando ffmpeg:
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav -
Executar ASR — usuário especificou qwen3-asr, mas qualquer modelo compatível com whisper funciona:
qwen3-asr audio.wav --output-format srt > raw_subtitles.srtOu use a abordagem integrada através do comando de transcrição da skill hyperframes-media.
-
Analise a saída SRT de volta para o formato JSON de segmento esperado pela Fase 3.
Fase 3: Correção e Tradução Paralela
Esta é a etapa mais demorada para vídeos longos. A estratégia: dividir em blocos e processá-los com subagentes, com um limite rígido de 3 subagentes simultâneos.
Execute esta fase mesmo para vídeos muito longos. A duração não é motivo para baixar ou usar legendas automáticas no idioma de destino do YouTube. O atalho correto para vídeos longos é dividir em blocos mais a concorrência de 3 subagentes, não a reutilização de legendas de destino.
3.1 Dividir Segmentos em Blocos
Use a lógica inversa de scripts/merge-chunks.py — divida raw_segments.json em N arquivos de bloco:
# Dividir em blocos dimensionados para revisão/tradução.
n = len(segments)
chunk_count = min(10, max(1, (n + 75) // 76))
chunk_size = n // chunk_count + 1
for i in range(0, n, chunk_size):
save_chunk(i, segs[i:i+chunk_size])
Salve como chunk_00.json, chunk_01.json, etc. Cada um contém {"chunk_id", "start_idx", "end_idx", "segments": [...]}.
3.2 Iniciar Agentes Paralelos
Para cada bloco, inicie um subagente em segundo plano. Inicie no máximo 3 subagentes ao mesmo tempo. Se houver 10 blocos, inicie os blocos 00, 01 e 02 primeiro; quando um terminar, inicie o próximo bloco pendente. Nunca inicie todos os 10 blocos de uma vez. Dê a cada agente:
- O caminho para seu
chunk_XX.json - Instruções para ler references/subtitle-proofreading.md para a especificação completa
- Caminho de saída:
result_XX.jsonno mesmo diretório
O agente deve:
- Ler cada segmento em seu bloco
- Revisar o inglês (corrigir erros de ASR, adicionar pontuação)
- Traduzir para chinês simplificado natural (manter termos técnicos em inglês)
- Salvar como array JSON com
{index, start, end, en, zh}por segmento - Remover caracteres ilegais de legendas de
enezh, especialmente barras invertidas soltas (\), caracteres de controle e chaves brutas de substituição ASS.
Importante: A concorrência máxima é de 3 subagentes/processos. Se houver mais de 3 blocos, execute-os em ondas. Não inicie 10 processos filhos do Codex para 10 blocos.
3.3 Aguardar a Conclusão
Monitore quais arquivos result_XX.json aparecem. Não prossiga até que todos os blocos sejam concluídos.
Fase 4: Mesclar e Gerar Arquivos de Saída
Execute o script de mesclagem:
python3 scripts/merge-chunks.py <diretório_saída>
Isso descobre automaticamente todos os arquivos result_*.json e produz:
| Arquivo | Conteúdo |
|---|---|
final_subtitles.json | JSON mesclado, ordenado por timestamp |
subtitles_bilingual.srt | Linhas em inglês + chinês |
subtitles_zh.srt | Apenas chinês |
subtitles_en.srt | Apenas inglês |
4.2 Validar a Qualidade dos Dados
Antes de renderizar, sempre valide os dados mesclados. O processamento paralelo do agente pode produzir corrupção de timestamp:
# Verificar durações anormais (>120s = quase certamente corrompido)
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
print(f'Durações anormais: {len(bad)} / {len(segs)}')
for s in bad: print(f' [{s[\"index\"]}] {s[\"start\"]:.1f}->{s[\"end\"]:.1f} ({s[\"end\"]-s[\"start\"]:.0f}s)')
"
Se algum for encontrado, corrija-o (limite end em start + 6) e regenere SRT/ASS. Tanto merge-chunks.py quanto srt-to-ass.py incluem detecção automática e correção automática para esse problema.
Verifique a saída: verifique se as primeiras e últimas entradas têm timestamps corretos e texto legível.
Também verifique a sanitização do texto:
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if '\\\\' in s.get('en','') or '\\\\' in s.get('zh','')]
print(f'Artefatos de barra invertida: {len(bad)}')
for s in bad[:10]: print(s['index'], s.get('en',''), s.get('zh',''))
"
Fase 5: Renderizar Legendas no Vídeo
NÃO use o ffmpeg do sistema diretamente — veja as Armadilhas abaixo.
5.1 Executar o Script de Renderização
bash scripts/render-subtitles.sh <video.mp4> <subtitles_bilingual.srt> [output.mp4]
O script lida com tudo:
- Detecta/constrói ffmpeg nativo para ARM64 com suporte a libass
- Converte SRT → ASS com configuração de fonte CJK adequada
- Copia arquivos para /tmp para evitar problemas com caracteres especiais no caminho
- Renderiza com o filtro ass do ffmpeg
- Valida a saída
5.2 Verificar a Saída
Verifique se:
- O arquivo de saída existe e tem > 10 MB (não apenas áudio)
- A duração corresponde ao vídeo original (use ffprobe)
- Reproduza o primeiro e último minuto para confirmar que as legendas aparecem
Armadilhas e Lições Aprendidas
Estas são lições difíceis obtidas do uso real. Siga-as para evitar perder horas.
Incompatibilidade de Arquitetura do ffmpeg (CRÍTICO)
Problema: O ffmpeg do Homebrew no macOS é compilado SEM libass, libfreetype e fontconfig. Os filtros ass, subtitles e drawtext simplesmente não existem.
Pior: As compilações estáticas do ffmpeg do evermeet.cx são binários x86_64 (Intel). Em Macs Apple Silicon, eles são executados através da emulação Rosetta 2 com ~8-10x mais lentidão. Um vídeo de 1,5h levou mais de 2 horas.
Solução: Use scripts/ensure-ffmpeg.sh. Ele detecta esses problemas e compila o ffmpeg nativo para ARM64 a partir do código-fonte com todas as bibliotecas necessárias. A primeira compilação leva ~5 minutos; as reconstruções subsequentes são instantâneas (arquivos de objeto em cache).
Flags de configuração necessárias para suporte completo a legendas:
--enable-libass --enable-libfreetype --enable-fontconfig --enable-libdav1d
Decodificação AV1 Ausente
Problema: Muitos vídeos modernos do YouTube são codificados em AV1 (codec_name: av1). Um ffmpeg compilado sem --enable-libdav1d falhará com erros "Function not implemented" durante a decodificação, produzindo um arquivo de apenas áudio de 68 MB.
Solução: Sempre inclua --enable-libdav1d ao compilar o ffmpeg.
Caracteres Especiais no Caminho Quebram os Filtros do ffmpeg
Problema: Quando o caminho do vídeo ou legenda contém caracteres como travessões (—), aspas inteligentes ou caracteres não ASCII, o analisador de filtros do ffmpeg falha com erros "No option name near...". Isso acontece mesmo com aspas adequadas no shell.
Solução: Copie os arquivos de legenda para /tmp/subs_<pid>.ass antes de passar para o ffmpeg. O script de renderização faz isso automaticamente.
Conflitos de API TextClip do moviepy (EVITAR)
Problema: O TextClip do moviepy 2.x tem conflitos de parâmetros entre argumentos posicionais e kwargs (font aparece duas vezes internamente). Várias variantes de erro, nenhuma óbvia pela mensagem de erro.
Recomendação: Não use moviepy para renderização de legendas em produção. Use o filtro ass do ffmpeg — é mais rápido, mais confiável e lida com fontes CJK adequadamente através do libass/fontconfig.
SRT vs ASS para ffmpeg
Problema: O filtro subtitles do ffmpeg (que lê SRT diretamente) também sofre de problemas de análise de caminho em algumas compilações. O filtro ass é mais confiável.
Solução: Converta SRT → ASS primeiro usando scripts/srt-to-ass.py, depois use o filtro ass. O formato ASS também oferece controle fino sobre fonte, tamanho, posicionamento e estilo.
Caracteres Ilegais em Legendas
Problema: O texto da legenda bruto ou traduzido pode conter barras invertidas soltas (\) ou caracteres de substituição ASS. Na renderização ASS, uma barra invertida literal pode aparecer na tela ou interagir acidentalmente com a sintaxe de escape ASS.
Solução: Sanitize o texto da legenda antes de escrever SRT/ASS:
- Remova barras invertidas do texto de legenda visível ao usuário
- Remova caracteres de controle, exceto espaços em branco normais
- Remova chaves
{e}brutas do texto da legenda - Deixe
srt-to-ass.pyadicionar apenas as sequências de controle ASS que ele possui, como\Nentre linhas bilíngues
Durações Anormais de Legendas do Processamento Paralelo de Agentes
Problema: Ao processar legendas em blocos paralelos (Fase 3), agentes individuais podem produzir entradas com timestamps corrompidos — especificamente, valores end muito maiores que start (por exemplo, duração de 2600s ou 4800s em vez de ~6s). Isso faz com que essas linhas de legenda permaneçam visíveis na tela durante a maior parte do vídeo, sobrepondo-se a todo o outro conteúdo.
Causa raiz: Os agentes às vezes atribuem mal os tempos finais ao consolidar segmentos ASR fragmentados nos limites dos blocos. O problema está no nível dos dados, não é um problema de renderização — portanto, não será detectado por erros do ffmpeg.
Solução: Três camadas de defesa:
scripts/srt-to-ass.pydetecta automaticamente entradas com duração > 120s e as limita a 6s com um aviso- Validação da Fase 4: Após mesclar os blocos, sempre verifique se há entradas onde
(end - start) > 120segundos - Verificação pré-renderização: Antes de executar o ffmpeg, grep o arquivo ASS em busca de linhas Dialogue suspeitamente longas
# Verificação rápida pré-renderização: encontrar qualquer legenda com duração > 2 minutos
python3 -c "
import json, sys
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
if bad: print(f'AVISO: {len(bad)} durações anormais encontradas!'); sys.exit(1)
else: print('Verificação de duração aprovada')
"
Ajuste de Tamanho da Fonte
Problema: Os tamanhos de fonte padrão (16-20px) podem ser muito pequenos em vídeos de alta resolução 1080p+, especialmente ao visualizar em telas menores ou à distância.
Solução: Use o sinalizador --font-size para ajustar. Tamanhos de base recomendados:
- Vídeo 1080p:
--font-size 24(bilíngue) ou--font-size 28(único idioma) - Vídeo 4K:
--font-size 36ou maior - O script
render-subtitles.shpassa isso parasrt-to-ass.py
Dependências
- Ferramentas MCP do YouTube:
mcp__plugin_youtube_youtube__*(download de vídeo, transcrição, informações) - ffmpeg: Auto-compilado por
scripts/ensure-ffmpeg.sh - Python 3: scripts fornecidos em
scripts/ - Modelo ASR: qwen3-asr ou qualquer modelo compatível com whisper
- Subagentes: Até 3 simultâneos para processamento de blocos de legendas