xieyuhai/video-zh-dubbing

Dublagem de Vídeo para Chinês

Use o pipeline Python integrado para produzir um vídeo completo dublado em chinês. Não forneça apenas um fluxo de trabalho sugerido quando o usuário forneceu uma URL e pediu o artefato final: execute o pipeline se a execução no terminal estiver disponível e o usuário tiver autorizado as ações de rede/download necessárias.

Requer Python 3.10+, FFmpeg/ffprobe, acesso à rede para downloads de URL e um modelo faster-whisper local. Tradução e fala online são opcionais; use o backend local CosyVoice quando for necessário mandarim natural sem uma API de fala paga.

Resolva <skill-root> como o diretório que contém este SKILL.md; não assuma que o diretório de trabalho atual do chamador é o diretório da skill. Prefira <skill-root>/.venv/bin/python no macOS/Linux ou <skill-root>/.venv\Scripts\python.exe no Windows quando esse ambiente virtual existir; caso contrário, use o interpretador Python ativo. Os comandos abaixo assumem que o diretório atual foi alterado para <skill-root>.

Início rápido

1. Verifique os pré-requisitos:

   python3 scripts/check_environment.py
   

2. Instale o FFmpeg e as dependências Python. Consulte o README.md para comandos no macOS, Windows e Linux.

3. Para tradução natural sem API paga, use um modelo Ollama já instalado com --translation-provider ollama --ollama-model MODEL. O pipeline executa a tradução localmente em duas passadas e valida cada ID de segmento; revise termos técnicos e tempo antes da entrega. Se nenhum modelo local estiver disponível, use --translation-provider google somente com permissão como rascunho online e ajuste manualmente os segmentos com carimbo de data/hora, ou passe o JSON revisado via --segments-file. Use OPENAI_API_KEY ou DEEPSEEK_API_KEY apenas quando explicitamente permitido; nunca mude para uma API não autorizada.

4. Converta uma URL de vídeo (Bilibili, YouTube ou qualquer site suportado pelo yt-dlp):

   python3 scripts/translate_video.py "https://www.youtube.com/watch?v=VIDEO_ID" \
     --translation-provider ollama --ollama-model MODEL --output-dir ./output
   

   URLs do Bilibili podem incluir um parâmetro de parte como ?p=2; passe a URL alvo completa.

5. Ou processe um vídeo local:

   python3 scripts/translate_video.py ./input.mp4 \
     --translation-provider ollama --ollama-model MODEL --output-dir ./output
   

Padrões e Opções

• O idioma de origem padrão é o inglês (--source-language en); use auto para detectá-lo.
• A voz chinesa padrão é zh-CN-XiaoxiaoNeural; use --voice zh-CN-YunxiNeural para uma voz masculina mais jovem ou --voice zh-CN-YunyangNeural para uma voz masculina de narração.
• Para fala natural sem taxa por chamada, prefira um Fun-CosyVoice3-0.5B instalado localmente no modo zero-shot quando houver um clipe de referência e uma transcrição exata explicitamente autorizados. Caso contrário, use CosyVoice-300M-SFT com um locutor embutido (por exemplo 中文女). Nunca clone uma voz sem permissão. O modelo é carregado uma vez para todos os segmentos, escreve clipes WAV PCM16 e faz checkpoint do progresso. Consulte o README.md para as flags.
• Se o Edge TTS estiver inacessível, defina DASHSCOPE_API_KEY e use --tts-provider dashscope --voice Cherry para o Qwen3 TTS. O texto transcrito traduzido é enviado para DashScope.
• A tradução padrão é auto, que usa apenas um OLLAMA_MODEL local explicitamente configurado e, caso contrário, para antes da tradução. Selecione --translation-provider openai ou google explicitamente antes que qualquer transcrição seja enviada a um tradutor externo. O Ollama requer seu serviço local e um modelo instalado; a skill nunca baixa um automaticamente. Use --translation-context "tópico do vídeo e termos-chave" quando o nome do arquivo não identificar claramente o assunto; caso contrário, o título ou nome do arquivo é usado.
• --audio-mode replace substitui o áudio original pela fala em chinês (padrão, confiável). --audio-mode mix mantém a faixa original em volume baixo sob a voz chinesa. --audio-mode background tenta separar os vocais originais com o Demucs opcional e, em seguida, mistura a voz chinesa com o fundo restante. Se o Demucs não estiver disponível ou falhar, o script relata o problema e retrocede com segurança para a substituição de áudio.
• --subtitle-mode soft incorpora legendas chinesas selecionáveis no MP4 e também escreve um SRT externo (padrão). Inspecione os quadros de origem primeiro: se as legendas já estiverem queimadas na imagem, mantenha soft para evitar sobreposição de texto duplicado. burn queima as legendas na imagem e requer uma compilação do FFmpeg com o filtro subtitles/libass e uma fonte chinesa utilizável. none omite as legendas do MP4, mas ainda escreve um SRT lateral para revisão.
• Ajuste o ASR com --model small (padrão equilibrado), --model medium ou --model large-v3. Modelos maiores precisam de mais memória e levam mais tempo. A primeira execução baixa o modelo selecionado.
• Use --cookies-from-browser chrome somente se você estiver conectado e o site exigir sua própria sessão do navegador. Isso lê cookies do navegador local; não é ativado por padrão.
• Use --keep-intermediates para reter o áudio fonte baixado, arquivos WAV e clipes de fala gerados para solução de problemas.
• Use --segments-file path/to/translated.segments.json para reutilizar traduções revisadas após uma falha de TTS sem repetir o reconhecimento e a tradução.
• Use --reuse-tts-dir path/to/tts_segments com um conjunto existente de clipes gerados para ajustar o tempo e renderizar novamente sem chamar o serviço de fala novamente.

Verificações de Saída Obrigatórias

O script deve verificar se o MP4 existe, não está vazio, possui um fluxo de vídeo e um fluxo de áudio e tem uma duração próxima à entrada. Ele emite um SRT, um JSON de segmentos traduzidos e um relatório de processamento ao lado do MP4 final. Qualquer etapa com falha deve interromper o pipeline e fornecer um erro útil em vez de fingir que a saída está completa.

Antes da entrega, inspecione o JSON/SRT traduzido quanto a nomes e termos mal transcritos, frases não naturais palavra por palavra e segmentos que foram acelerados ou cortados. Inspecione também um quadro renderizado: rejeite caixas de glifos ausentes, legendas fora da tela e legendas queimadas duplicadas. Para o CosyVoice, ouça uma amostra curta antes de renderizar um vídeo longo; verifique a pronúncia real de decimais, nomes de código e termos em inglês, não apenas seu texto escrito. Um segmento revisado pode adicionar spoken_text para soletrar um número ou nome de arquivo naturalmente, enquanto zh_text permanece como a legenda exata. Seus significados devem corresponder. Evite enviar fala cortada ou aceleração perceptível.

Fluxo de Trabalho

1. Resolva URL vs. arquivo local. Para URLs, baixe apenas o vídeo solicitado usando yt-dlp (--no-playlist). Se uma página do Bilibili retornar 412, o script pode usar a API pública do Bilibili somente quando o vídeo estiver explicitamente marcado como baixável; preserve a parte ?p= solicitada. Nunca burle DRM, paywalls ou restrições de conta.
2. Use ffprobe para inspecionar streams e duração. Extraia áudio PCM mono de 16 kHz.
3. Transcreva com faster-whisper, mantendo os carimbos de data/hora de origem. Falhe claramente se nenhuma fala for detectada.
4. Traduza com contexto do tópico e da fala vizinha e, em seguida, refine em mandarim conciso e idiomático. Preserve IDs, ordem, significado, números, nomes e termos técnicos. Verifique erros de reconhecimento de origem em relação ao tópico do vídeo.
5. Gere cada segmento de voz chinesa através do serviço de fala selecionado. Ajuste-o conservadoramente à sua janela de carimbo de data/hora; avise no relatório quando um segmento precisar de aceleração ou truncamento agressivo.
6. Construa uma faixa de voz chinesa de duração total. Aplique o modo de áudio solicitado; a separação opcional do Demucs é um aprimoramento, não uma dependência rígida.
7. Escreva o SRT chinês e o JSON traduzido. Multiplexe ou queime as legendas conforme solicitado, exporte um MP4 H.264/AAC amplamente compatível e verifique o resultado.
8. Relate os caminhos exatos de saída, as configurações selecionadas, avisos e quaisquer necessidades de revisão restantes.

Exemplos

# URL do YouTube; tradução via API; voz feminina chinesa; voz sobre fundo extraído
OPENAI_API_KEY="$OPENAI_API_KEY" python3 scripts/translate_video.py "https://youtu.be/VIDEO_ID" \
  --translation-provider openai --audio-mode background --subtitle-mode soft --output-dir ./output

# Bilibili parte 2; use uma chave LLM configurada para tradução natural
python3 scripts/translate_video.py "https://www.bilibili.com/video/BV1NAuq6uE8t/?p=2" \
  --translation-provider openai --translation-context "desenvolvimento orientado a especificações SDD e programação de agentes" \
  --voice zh-CN-YunyangNeural --audio-mode mix --output-dir ./output

# Queime legendas chinesas na imagem
python3 scripts/translate_video.py ./input.mp4 --subtitle-mode burn --output-dir ./output

# Fala totalmente local usando CosyVoice3 e uma referência autorizada; sem APIs pagas
python3 scripts/translate_video.py ./input.mp4 --segments-file ./reviewed.segments.json \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/Fun-CosyVoice3-0.5B \
  --cosyvoice-mode zero-shot --cosyvoice-prompt-audio ./reference.wav \
  --cosyvoice-prompt-text-file ./reference.txt --subtitle-mode burn --output-dir ./output

# Transcrição local, tradução com Ollama e narração com CosyVoice
python3 scripts/translate_video.py ./input.mp4 --translation-provider ollama --ollama-model MODEL \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/CosyVoice-300M-SFT \
  --cosyvoice-mode sft --output-dir ./output

Segurança e Direitos

Processe apenas vídeos que você possui, está licenciado para adaptar ou está autorizado a baixar e transformar. Respeite os termos e direitos autorais da plataforma de origem. Nunca burle DRM ou controles de acesso técnico. --cookies-from-browser é opcional e deve usar apenas a sessão autenticada do próprio usuário. Não publique um derivado dublado sem confirmar os direitos aplicáveis.

O projeto é para aprendizado, pesquisa e intercâmbio técnico. Não o use para atividades ilegais, clonagem de voz não autorizada, fraude, personificação ou conteúdo enganoso. Consulte o aviso legal no README.md; os usuários são responsáveis pelo uso e distribuição do conteúdo gerado de acordo com a lei aplicável.