boyingliu01/bilingual-video-subtitles

Bilingual Video Subtitles 培训视频双语字幕

Pipeline completo em scripts/pipeline.py (entrada única, etapas com cache e suporte a retomada).

Atenção ao ambiente host: Esta skill foi adaptada para múltiplos ambientes, selecionando automaticamente o backend de transcrição (gateway Omni original da sandbox / API compatível com OpenAI / bridge whisper). Sem gateway Omni e sem API configurada, o pipeline opera em modo agente — as etapas transcribe/translate são pausadas com código de saída 3 e escrevem um manifesto. Após completar a transcrição/tradução correspondente, execute build novamente para continuar. Leia o protocolo de operação e configuração de backend em references/host-adaptation.md. Se o pipeline sair com código 3, não é uma falha. Complete o trabalho indicado no manifesto e execute novamente.

Fluxo de Trabalho Padrão

1. Obter entrada: arquivo de vídeo + documentos de referência/regulamentos (.docx/.txt/.md).
2. Ler os documentos de referência e criar um glossário glossary.txt (uma linha por entrada: Chinês = English, 10~40 itens). O glossário determina a consistência da tradução em todo o vídeo. Cubra: nomes de regulamentos/normas, papéis e abreviações (ex.: PM=Project Manager), formulários de negócios ou nomes de documentos, nomes de sistemas internos.
3. Executar a construção (em primeiro plano, com timeout adequado; um vídeo de 50 minutos leva de 15 a 25 minutos para o fluxo completo):

python3 scripts/pipeline.py build \
  --video <caminho_do_video> --doc <caminho_do_documento> \
  --work <diretorio_de_trabalho> --out <diretorio_de_saida> \
  --glossary <glossary.txt> \
  --hotwords "安全红线,需求单,变更单,PM,QA,SRE" \
  --preview 90

4. Ordem de geração (cada etapa possui cache; se falhar, execute o mesmo comando novamente para retomar): setup (dividir áudio) → transcribe (transcrição palavra por palavra com Qwen3-Omni) → timing (linha do tempo com whisper) → align (alinhamento Pinyin) → clean (remover fala informal/quebrar frases) → translate (tradução chinês-inglês em lote) → package (arquivo de projeto + SRT + ASS) → render (visualização + versão completa).
5. Primeiro, use a visualização gerada com --preview para confirmar o resultado com o usuário (pode usar media-read para verificar a renderização das legendas), depois entregue a versão completa do vídeo, SRT e arquivo de projeto de legendas.

Descrição dos Entregáveis

Arquivo	Uso
<nome>_中英双语字幕_完整版.mp4	Vídeo com legendas embutidas (linha superior em chinês branco, linha inferior em inglês azul claro, ambas com fundo preto semitransparente, legível em qualquer fundo)
<nome>_中英双语字幕.srt	Arquivo de legendas bilíngues (importável para players/plataformas)
<nome>_字幕工程.json	Dados principais: contém todas as linhas do tempo + texto bilíngue. Apenas este arquivo é modificado em ajustes anuais
Diretório --work	Cache de artefatos intermediários (transcrição, linha do tempo do whisper). Manter evita retranscrição

Ajuste Anual (Atualizar Legendas Após Revisão de Regulamentos)

Quando pequenas alterações nos regulamentos afetam poucas frases, não é necessário retranscrever:

1. Peça ao usuário para apontar os trechos/períodos que precisam de modificação, ou edite diretamente o texto zh/en no arquivo <nome>_字幕工程.json do ano anterior (não mexa em start/end se a linha do tempo não mudar).
2. Renderizar novamente:

python3 scripts/pipeline.py render --project <projeto.json> [--video <novo_video>] [--srt-only]

Se o novo vídeo tiver frases adicionadas/removidas nos capítulos correspondentes: execute build --stage transcribe no novo vídeo para obter a nova transcrição, compare manualmente e substitua as entradas correspondentes no arquivo de projeto com o novo texto, depois renderize.

Dividir Vídeos Curtos por Tópico/Papel (Aprendizado Fragmentado)

Divida o vídeo completo com legendas já adicionadas (mantendo as legendas bilíngues).

1. Localizar limites de capítulo nos dados de legenda: use a lista de papéis/capítulos do documento de referência como palavras-chave para pesquisar em zh_lines.json (diretório de trabalho) as frases de transição de capítulo. Padrões típicos: "O papel X é Y", "Acima estão as responsabilidades de X, os requisitos são", "A situação de violação de X é", etc. Use o tempo de início da frase de transição como ponto de corte (essa frase pertence ao próximo episódio).
2. Restrições: cada episódio ≤ 10 minutos (limite superior absoluto de 15 minutos); se o capítulo exceder o limite, divida dentro do capítulo em quebras naturais (como entre "responsabilidades/ações de violação/métodos de determinação"); não combine papéis diferentes.
3. Escreva o plano de divisão JSON e execute:

{"base": "nome_do_video", "lead_in": 0.35,
 "chapters": [{"start": 0, "end": 288.4,
               "title": "01_开篇_目的与概述", "note": "descricao_do_conteudo"}]}

python3 scripts/pipeline.py split --plan plan.json \
  --video <video_completo_com_legendas.mp4> --out <diretorio_de_saida>

4. Saída para <diretorio_de_saida>/<nome_do_video>_拆分视频/: episódios nomeados automaticamente + 00_拆分目录.txt (nome do vídeo, intervalo de tempo, duração, descrição do conteúdo).
5. Verificação por amostragem: extraia quadros do início de cada episódio (use ffmpeg para PNG e visualize) para confirmar que o ponto de corte cai exatamente na frase de abertura do tópico correspondente.

Convenções de Implementação Críticas (Não Desviar)

• O backend qwen-omni deve injetar o texto completo do documento de referência no prompt como contexto de terminologia, com --timeout 900 --max-tokens 8192 (já embutido no script); backends ASR dedicados (como mimo-asr) não aceitam prompt de texto, a correção terminológica depende da etapa clean que compara com o documento.
• O whisper é usado apenas para a linha do tempo; seu texto reconhecido é sempre descartado (a qualidade do texto em chinês é ruim, mas os timestamps são precisos).
• O alinhamento deve ser global usando strings Pinyin (erros de homófonos são automaticamente resolvidos no nível Pinyin); alinhamento ganancioso frase por frase causará desvio geral.
• Qualidade do alinhamento: saída align com qual mean ≥ 0.75 é normal; < 0,6, verifique primeiro a cobertura de fala do whisper (veja references/troubleshooting.md).
• Tarefas de CPU longas (whisper/render) devem considerar a política de limpeza de tarefas em segundo plano do host; execute em primeiro plano se necessário.
• Restrições de rede: HuggingFace precisa de mirror. O script já define HF_ENDPOINT=hf-mirror.com e HF_HUB_DISABLE_XET=1, não remova.

Solução de Problemas

Veja references/troubleshooting.md: tratamento de timeout de upload, transcrição de linhas longas, qualidade de alinhamento baixa, fontes corrompidas, falha de renderização, etc.