Legendas em Chinês para Vídeos — traduzir e queimar
Recebe um vídeo em inglês já existente no disco e produz uma versão com legendas hardcoded em chinês simplificado, além de um arquivo SRT correspondente.
O download está deliberadamente fora do escopo. Presuma que o MP4 de origem já está disponível.
O pipeline é independente do assunto — foi construído com base em um vídeo de 22 minutos sobre movimentação no Apex, mas nada nos scripts sabe ou se importa com o conteúdo do vídeo. O que varia por vídeo é o glossário e a posição da faixa de legendas.
Como é uma boa saída
A pessoa que usa esta skill se preocupa com uma aparência específica, já definida. Não se trata de padrões a serem reconsiderados a cada vez — eles foram alcançados iterando sobre resultados reais, e alterá-los silenciosamente será tratado como uma regressão:
- Apenas chinês simplificado. Nunca misturado com tradicional. Verifique antes de entregar.
- Uma linha por legenda, sempre. Legendas de duas linhas são a reclamação mais comum. Se uma linha for muito longa, divida-a em duas inserções sequenciais, em vez de quebrar.
build_srt.pyimpõe isso. - Legendas são curtas. "Uma linha" não é licença para uma linha muito larga. Aponte para no máximo ~1100px de largura renderizada (cerca de 57% do quadro em 1080p).
- Sem caixa de fundo. Texto branco, contorno preto forte, sombra preta suave.
- 思源黑体 / Source Han Sans Bold (incluído em
assets/NotoSansSC-Bold.ttf). Reta e pesada, com glifos latinos fortes — este estilo de vídeo está repleto de jargões em inglês inseridos em frases chinesas, e uma fonte decorativa lida mal com isso. - Jargão que a comunidade realmente diz em inglês permanece em inglês. Quais termos são esses é uma questão por assunto, e é isso que os glossários respondem.
- Cards de capítulo queimados recebem uma linha em chinês abaixo, não acima.
Fluxo de trabalho
1. Analisar a origem e escolher um glossário
ffprobe -v error -show_entries format=duration -show_entries stream=codec_type,codec_name,width,height,r_frame_rate -of default=nw=1 source.mp4
Anote a duração e o fps exatamente — cada etapa posterior depende deles.
Em seguida, descubra sobre o que é o vídeo e leia references/glossaries/README.md, que direciona para o arquivo correto e informa quais seções ler. Leia a seção 字幕使用原则 do glossário correspondente por completo antes de traduzir — é curta e é onde as convenções para aquele jogo estão armazenadas.
Inclusos: Apex Legends, Warframe, osu!, Minecraft 速通/MCSR, StarCraft 星际争霸, Counter-Strike 反恐精英, ARC Raiders.
Se não houver glossário para este vídeo, esse é o caso normal. Traduza com base em nomes oficiais verificáveis em chinês simplificado, mantenha uma lista dos termos que você precisou decidir e entregue essa lista ao final. Se um termo não tiver nome oficial em chinês, use uma tradução descritiva e indique que não é oficial — não apresente um palpite como definitivo. Nunca invente um nome para algo que já tem um nome.
2. Obter uma transcrição em inglês com marcações de tempo
Se o vídeo veio do YouTube, suas legendas automáticas são uma base utilizável: yt-dlp --write-auto-subs --sub-langs "en.*" --skip-download. São legendas contínuas com marcações de tempo a nível de palavra, então deduplique-as em segmentos de frase.
Legendas automáticas distorcem jargões gravemente e você precisa corrigi-los durante a tradução. O ASR transcreve foneticamente com base em um modelo de inglês geral, então todo termo de domínio que não é uma palavra comum volta como uma palavra plausível, mas incorreta. Exemplos reais de um vídeo de movimentação no Apex: "forward rez/raft/raz" → RAS, "Neor strafe" → Neo strafe, "pedo strafe" → Pito strafe, "mantel boost" → "mantle boost", "alerts" → "lurches", "my VO was so high" → "my velo (velocity)", "I couldn't attach out of that" → "couldn't tap-strafe out of that". Espere o mesmo tipo de dano em qualquer vídeo denso em jargão — o glossário é o que permite reconhecê-lo.
Onde a fala for genuinamente irrecuperável — trechos de música, gritos sobrepostos — deixe zh vazio para aquele segmento para que seja descartado e informe ao usuário quais timestamps foram descartados. Inventar uma linha plausível é pior do que nenhuma linha.
3. Traduzir para um JSON de segmentos
[{"i": 1, "start": 0.24, "end": 4.90,
"en": "Seeing movement players pull off tricks like these is super cool and all, but",
"zh": "看身法玩家秀出这种操作确实很酷，但真正的问题是"}]
Mantenha en — não é decorativo. build_srt.py o usa para distinguir uma continuação de frase de uma fala separada ao decidir se duas inserções podem ser mescladas, o que evita junções incorretas como 算了好 ou 是，长官你好啊.
4. Construir o SRT
python scripts/build_srt.py segments.json sub.srt --font assets/NotoSansSC-Bold.ttf
Ele imprime um relatório. Trate valores não zero em overlaps, multiline, latin_cjk_runons ou term_split_across_cues como bugs a corrigir antes da codificação. Algumas inserções com under_0.35s são aceitáveis quando são interjeições de 1 a 3 caracteres — verifique, mas não presuma.
5. Encontrar e traduzir cards de capítulo queimados
python scripts/find_chapters.py source.mp4
Os criadores frequentemente queimam cards de capítulo no vídeo em vez de usar capítulos do YouTube, então os metadados não mostram nenhum. Este script relata janelas candidatas; extraia um quadro de cada uma e leia o texto real do card antes de escrever a tradução. Gere chapters.json: [{"start":42,"end":46,"zh":"第 1 章：定义 lurch 组合"}].
6. Verificar locais onde legendas colidiriam com texto na tela
Os cards de encerramento são o infrator mais comum — legendas na posição normal caem sobre as redes sociais do criador. Extraia um quadro, encontre a lacuna e declare-a:
[{"from": 1334.0, "to": 100000, "bottom": 820}]
A faixa de legendas padrão fica acima de um HUD típico de FPS. Um jogo diferente, ou filmagem não relacionada a jogos, pode colocar seus próprios elementos ali — um minimapa de MOBA, a linha de julgamento de um jogo rítmico, um terço inferior de uma palestra. Extraia um quadro e observe antes de aceitar o padrão.
7. Construir a sobreposição e codificar
python scripts/build_overlay.py sub.srt ov --font assets/NotoSansSC-Bold.ttf \
--duration 1354.351 --chapters chapters.json --avoid avoid.json
python scripts/burn_in.py source.mp4 ov/concat.txt out.mp4
Verifique se o desvio reportado da sobreposição é de alguns milissegundos, não centenas.
Antes de se comprometer com uma codificação de ~20 minutos, componha um PNG de sobreposição sobre um quadro real no PIL e observe-o. Isso custa segundos e detecta erros de posição e fonte que, de outra forma, só apareceriam 20 minutos depois.
8. Verificar
python scripts/verify.py out.mp4 --expect-frames <frames> \
--contact-sheet sheet.jpg --at 75 300 660 945 1340
Observe a folha. Confirme: linhas únicas, legíveis sobre quadros claros, linhas de capítulo sob seus cards, nada colidindo com HUD ou texto de encerramento.
9. Correções posteriores — emende, não recodifique
Quando o usuário pedir para alterar algumas linhas (o que acontecerá), reconstrua o SRT, compare-o com o anterior para encontrar quais inserções mudaram, então:
python scripts/splice.py out.mp4 source.mp4 sub.srt out_fixed.mp4 \
--font assets/NotoSansSC-Bold.ttf --change-from 310 --change-to 316 \
--duration 1354.351 --chapters chapters.json --avoid avoid.json
python scripts/verify.py out_fixed.mp4 --expect-frames <frames> --seams 310 316
15 segundos em vez de 20 minutos. A contagem de quadros deve sair idêntica.
Entregáveis
Junto com out.mp4, entregue o SRT (diálogo mais linhas de capítulo, mescladas e renumeradas) para que as legendas possam ser editadas posteriormente sem refazer o trabalho. Ofereça também um título e uma descrição em chinês — se o vídeo for uma republicação, levante que a descrição original em primeira pessoa implica autoria, e que os blocos de atribuição musical devem permanecer em seu inglês original porque a licença exige essa forma exata.
Se você precisou definir termos que não estavam em um glossário, liste-os. Um termo decidido uma vez e registrado vale mais do que a mesma decisão tomada de forma diferente na próxima vez; references/glossaries/README.md informa como transformar uma lista como essa em um arquivo de glossário.
Material de referência
references/glossaries/README.md— qual glossário ler, quais seções dele e o que fazer quando o vídeo não tem nenhum. Comece por aqui.references/glossaries/*.md— os próprios glossários. Grandes. Leia a seção de princípios e as seções relevantes; usegreppara termos individuais.references/pipeline.md— notas técnicas e as armadilhas específicas deste pipeline. Leia antes de depurar qualquer coisa que pareça um problema de sincronismo, emenda ou renderização; a maioria já foi diagnosticada uma vez.