YouTube Bilingual Hardburn
Transforma um vídeo em língua estrangeira num vídeo com legendas "hardburn" chinês-inglês. As etapas determinísticas são scripts; a etapa de tradução é feita pelo agente (LLM) e é onde reside todo o risco.
LEI DE FERRO: UMA linha em chinês por linha em inglês. NUNCA dividir uma linha inglesa em duas chinesas (nem fundir duas numa só). Após cada lote de tradução, execute verify_align.py. Um único desalinhamento desloca cada legenda subsequente — e você nem notará até que o vídeo seja queimado.
Quando a fonte tem pontuação vs. quando não tem
- As legendas automáticas do YouTube (e a maioria dos ASR) quase não têm pontuação → a abordagem de "dividir por
.!?" falha (colapsa tudo numa única legenda). Esta habilidade resolve isso fundindo frases até um limite de caracteres. Este é o caminho padrão. - Se a fonte já tiver legendas bem pontuadas, o mesmo pipeline ainda funciona.
Pré-requisitos
yt-dlp(download),ffmpeg(hardburn),python3(scripts). Não são necessários pacotes Python.- Uma fonte CJK instalada. macOS:
PingFang SC(padrão). Linux: passe--font "Noto Sans CJK SC". Windows:--font "Microsoft YaHei". SCRIPTS=o caminho absoluto para o diretórioscripts/desta habilidade. Defina uma vez e reutilize.
Fluxo de trabalho
Progresso do Bilingual Hardburn:
- [ ] Passo 1: Obter o vídeo + legendas ⚠️ OBRIGATÓRIO
- [ ] Passo 2: Extrair + re-segmentar legendas em linhas legíveis
- [ ] Passo 3: Traduzir cada linha (1:1) — a parte cuidadosa ⚠️ OBRIGATÓRIO
- [ ] Passo 4: verify_align.py == OK ⛔ BLOQUEANTE (não pode prosseguir até passar)
- [ ] Passo 5: Construir .ass bilíngue + confirmar estilo num ÚNICO frame de teste ⚠️ OBRIGATÓRIO
- [ ] Passo 6: Hardburn do vídeo completo (codificação longa) + verificação de frames
Passo 1: Obter o vídeo + legendas ⚠️ OBRIGATÓRIO
yt-dlp -o "%(upload_date)s_%(title)s.%(ext)s" \
-f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]/best[height<=1080]/best" \
--merge-output-format mp4 --write-subs --write-auto-subs --sub-langs "en" \
--no-mtime "<URL>"
- Se
--write-auto-subsnão produzir nenhum arquivo de legenda (alguns vídeos não têm), você deve transcrever o áudio primeiro (ex.: whisper) para.vtt/.srt, depois continuar. - Anote os dois arquivos de saída:
VIDEO.mp4eVIDEO.en.vtt.
Passo 2: Extrair + re-segmentar ⚠️
python3 "$SCRIPTS/extract_phrases.py" "VIDEO.en.vtt" > phrases.json
python3 "$SCRIPTS/merge_lines.py" phrases.json lines.json # --max-chars 95 --gap 12
Isto produz lines.json ([{start,end,en}]) e lines_en.txt (um arquivo numerado idx<TAB>English). Traduza lines_en.txt. Ajuste depois, se necessário:
- legendas parecem longas demais na tela → reduza
--max-chars(ex.: 70) - deseja quebras em pausas naturais → reduza
--gap(ex.: 2.5) — resulta em mais linhas, mais curtas
Passo 3: Traduzir cada linha (1:1) ⚠️ OBRIGATÓRIO — esta é a parte cuidadosa
Leia lines_en.txt (numerado de 0..N-1). Produza um arquivo ZH em texto simples: exatamente uma linha em chinês para cada linha em inglês, mesma ordem. Escreva texto separado por nova linha (NÃO JSON — as aspas chinesas quebram o escape JSON).
Regras que evitam a violação da Lei de Ferro:
- Uma linha de entrada → uma linha de saída. Traduza a linha inglesa como sua própria unidade. Se uma linha quebrar no meio da frase (é normal para ASR), deixe o chinês quebrar no mesmo lugar. Não "corrija" estendendo o fluxo entre linhas.
- Trabalhe em lotes de ~120–150 linhas. Após CADA lote, escreva seu arquivo e execute imediatamente
verify_align.pyno resultado acumulado. - Mantenha nomes próprios na forma correta (ChatGPT, OpenAI, Claude, Gemini, Grok, DeepSeek…). O ASR os distorce ("chpd"→ChatGPT, "grock"→Grok, "ha cou"→haiku) — corrija para o nome real.
- Chinês natural falado, não tradução rígida. Combine com o registro do falante.
Concatene todos os arquivos de lote num único zh.txt (uma linha ZH por linha EN, em ordem).
Passo 4: verify_align.py ⛔ BLOQUEANTE
python3 "$SCRIPTS/verify_align.py" lines.json zh.txt
- Imprime
OK→ prossiga. - Imprime
MISMATCH+ uma tabela lado a lado → encontre a linha onde os significados EN e ZH param de corresponder. Essa linha é uma divisão (uma linha EN tornou-se duas ZH) ou uma fusão. Corrija (fundir as duas ZH de volta numa, ou dividir uma em duas), depois reexecute. Não prossiga até OK.
Passo 5: Construir .ass + confirmar num ÚNICO frame de teste ⚠️ OBRIGATÓRIO
python3 "$SCRIPTS/build_bilingual_ass.py" lines.json zh.txt styled.ass
# Chinês em cima (branco 44px) + inglês em baixo (cinza 30px), centro-inferior.
# Linux/Windows: adicione --font "Noto Sans CJK SC" / --font "Microsoft YaHei"
Renderize UM frame num timestamp conhecido por ter legenda, e VEJA antes da codificação longa:
ffmpeg -ss 60 -i "VIDEO.mp4" -copyts -vf "ass=styled.ass" -frames:v 1 -y test_frame.png
Confirme com o usuário: o chinês renderiza (sem caixas □□□), o layout de dois níveis parece correto, tamanho/posição aceitáveis. Ajuste --zh-size/--en-size/--margin/--font e reconstrua se necessário. Não inicie a codificação completa até que o frame de teste pareça correto.
Passo 6: Hardburn do vídeo completo + verificação
ffmpeg -y -i "VIDEO.mp4" -vf "ass=styled.ass" \
-c:v libx264 -preset fast -crf 22 -c:a copy -sn "VIDEO_中英双语.mp4"
Um vídeo 1080p de 2 horas leva ~15–40 min — execute em segundo plano. Quando terminar, capture frames no início, meio e perto do fim para confirmar que as legendas permanecem sincronizadas durante todo o percurso:
for t in 600 3900 7200; do ffmpeg -ss $t -i "VIDEO_中英双语.mp4" -frames:v 1 -y "chk_$t.png"; done
Se um frame parecer desalinhado, reconfirme a legenda do mesmo timestamp em lines.json+zh.txt para garantir que é a mesma linha de origem antes de assumir um bug (frames de baixa resolução são fáceis de ler mal).
Anti-Padrões
- Dividir/fundir linhas durante a tradução — a #1 causa de dessincronização do vídeo completo. Uma linha EN = uma linha ZH, sempre.
- Escrever traduções como JSON — as aspas chinesas curvas “ ” e 「」 quebram silenciosamente a análise JSON. Use texto simples separado por nova linha.
- Confiar nos tempos FIM da legenda para ordenação — as FIMs das legendas rolantes se sobrepõem;
merge_lines.pyordena apenas pelo INÍCIO. Não reordene pelo FIM. - Pular o frame de teste — queimar 2 horas e depois descobrir caixas □□□ ou uma fonte errada desperdiça toda a codificação.
- Re-codificar o áudio — use
-c:a copy. Apenas a faixa de vídeo muda. - Usar o antigo
build_bilingual.pyda habilidade de download de vídeo em legendas automáticas — ele divide por pontuação e colapsa toda a transcrição numa única legenda. Esta habilidade o substitui.
Lista de Verificação Pré-Entrega
-
verify_align.pyimprimiuOK(contagem EN == contagem ZH) antes de construir o .ass - Frame de teste inspecionado: chinês renderiza, sem caixas □, layout/tamanho corretos
- Verificados frames de início/meio/fim do mp4 final — legendas sincronizadas
- Saída nomeada claramente (ex.:
<titulo>_中英双语.mp4); vídeo original intacto - Nomes próprios corrigidos (sem "chpd"/"grock"/"ha cou" no chinês)
Multiplataforma (OpenAI Codex, etc.)
Todos os scripts são python3 puro + ffmpeg/yt-dlp — sem dependência específica do Claude. Para executar este fluxo de trabalho sob Codex (ou qualquer agente com capacidade de shell), carregue references/codex-usage.md.