Communitygithub.com

dub-studio

Duble um vídeo nesta máquina, traduzindo e regravando a voz, mantendo música e efeitos sonoros, sem serviços pagos. Transcreve localmente com faster-whisper (ou lê um SRT/VTT), permite traduzir linha por linha em JSON com orçamento de tempo por linha, remove a voz original com Demucs (ou fallback), narra cada linha com uma voz sintética Kokoro integrada, ajusta as linhas aos seus slots (aceleração, pausas, ou flag), remixa em um volume definido (-16 LUFS padrão) e gera um MP4, SRT/VTT bilíngue, relatório de tempo e uma planilha.

O que é dub-studio?

O dub-studio é uma ferramenta de agente de IA para dublagem local de vídeos, capaz de traduzir e regravar a fala mantendo música e efeitos sonoros, sem depender de serviços externos pagos. Ele suporta transcrição local via faster-whisper (ou entrada de legendas SRT/VTT), remoção de voz com Demucs, e narração com vozes sintéticas Kokoro integradas, com suporte para inglês, espanhol, francês, italiano, português brasileiro, hindi e mandarim (experimental). O fluxo de trabalho é estruturado: prepare transcreve e prepara as linhas, lint verifica erros de tradução, build gera o vídeo dublado, e verify confirma qualidade com reconhecimento de fala. A ferramenta impõe regras rigorosas de direitos autorais e etiquetagem de voz sintética, proíbe clonagem de voz, e oferece relatórios detalhados e uma planilha visual (sheet.png) para revisão de sincronia.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/dub-studio/tree/HEAD

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que dub-studio faz?

Pipeline: vídeo -> áudio -> faster-whisper (ou legendas do usuário) -> linhas de origem temporizadas -> sua tradução (JSON, uma linha cada, dentro de um orçamento de tempo) -> Demucs remove a voz -> Kokoro narra cada linha traduzida -> ajuste de tempo (atempo, pausas, flags) -> mixagem com o fundo -> loudness -> MP4 + legendas + relatório.

Pasta da skill (escrita $D abaixo): esta pasta. Cada comando é $D/dub <comando> ...; $D/dub help lista todos.

Regras (leia primeiro)

  • Direitos. --rights é a declaração do usuário; a ferramenta registra, mas não pode verificar. Dubles apenas vídeos que o usuário fez ou possui (--rights own), tem permissão por escrito ou licença para dublar (licensed), ou cuja fala já é uma voz sintética que pode substituir (synthetic). Pergunte se não estiver claro. Se o vídeo mostra ou dá voz a uma pessoa real que não concordou, não duble. Nunca faça ninguém parecer dizer algo que não disse.
  • Sem clonagem. A nova voz é sempre uma das vozes integradas do Kokoro, escolhida por nome. Nunca tente imitar o falante original ou qualquer pessoa real, e nunca passe uma gravação como voz (a ferramenta recusa).
  • Rotule. Os metadados do MP4 de saída, os arquivos VTT e out/<lang>/README.md dizem que a dublagem usa uma voz sintética. Mantenha esse rótulo ao entregar os arquivos e diga ao usuário para mantê-lo na publicação.
  • Qualidade da tradução. Você escreve a tradução. Diga que é tradução automática e sugira que um falante fluente a revise antes da publicação.

Idiomas

Execute $D/dub languages para a lista ao vivo. Medido nesta máquina (Kokoro v1.0 via kokoro-onnx, fonemas espeak-ng), verificado lendo a voz com reconhecimento de fala:

códigoidiomastatus
en-us, en-gbInglêssuportado
esEspanholsuportado
fr-frFrancêssuportado
itItalianosuportado
pt-brPortuguês brasileirosuportado
hiHindirazoável: compreensível, algumas palavras erradas
cmnChinês mandarimexperimental: a maior parte não é compreendida na leitura; recusado sem --experimental
jaJaponêsnão funciona com kokoro-onnx (kanji são lidos como "letra chinesa")
msMalaionão suportado: Kokoro não tem voz para malaio

Qualquer outro (alemão, coreano, indonésio, árabe...) não é suportado: diga isso claramente e não substitua por voz de outro idioma. Qualquer idioma que o faster-whisper conheça pode ser a origem.

Fluxo de trabalho

  1. $D/dub check. Corrija qualquer linha MISS (check_env.sh imprime os comandos). Demucs é opcional; sem ele, o fundo usa fallback (veja abaixo).
  2. Confirme os direitos e os idiomas de destino com o usuário.
  3. $D/dub prepare <vídeo> --out <projeto> --to es,fr-fr --rights own [--from en]
    • Adicione --srt subs.srt (ou .vtt) com --from <idioma> quando o usuário tiver um script ou legendas corretos: isso pula o reconhecimento de fala e usa esses tempos de cue como as linhas.
    • A entrada deve ter um stream de vídeo e uma faixa de áudio. --from deve ser um código de idioma simples (en, pt-BR).
    • Executar prepare novamente na mesma pasta é recusado, porque source.json pode conter correções. --force substitui source.json e recria os arquivos de tradução.
    • Sem ele, faster-whisper small roda na CPU (--model base é mais rápido, medium mais preciso). Leia source.json e corrija quaisquer palavras mal interpretadas antes de traduzir (mantenha ids e tempos).
    • --voice es=em_alex escolhe uma voz; --max-tempo 1.2 reduz o limite de aceleração; --target -23 define o loudness de transmissão.
  4. Traduza. Abra cada translations/<lang>.json. Para cada linha, escreva a tradução de source em text:
    • Uma linha de entrada, uma linha de saída: nunca mescle, divida, reordene ou descarte linhas, nunca mude id.
    • Fique dentro de budget.ideal caracteres (cabe na velocidade normal). budget.max é o limite máximo (falado na aceleração máxima). Mais curto é melhor do que mais rápido: remova palavras de preenchimento, use a frase natural mais curta.
    • Traduza significado, não palavras. Registro natural falado. Mantenha nomes, nomes de produtos e números. Não adicione fatos.
    • Somente texto simples: sem colchetes, direções de palco, marcação ou emoji.
  5. $D/dub lint <projeto>: corrija todo ERROR (muito longo, vazio, faltando). Leia os WARNINGs (linhas longas tomam emprestada a pausa seguinte; números perdidos; linhas não traduzidas) e encurte onde puder.
  6. $D/dub build <projeto> [--separation ...]: fundo, voz, ajuste, mixagem, loudness, mux. Imprime o MP4 de cada idioma, loudness e quantas linhas foram aceleradas, deslocadas ou sinalizadas. Uma linha FLAG significa que a tradução é muito longa mesmo com as pausas: encurte e construa novamente (as vozes são armazenadas em cache, apenas as linhas alteradas são regravadas). Linhas que foram empurradas para depois são relatadas como delayed, não sinalizadas: corrija a linha sinalizada, não elas.
  7. Veja o resultado. Leia out/<lang>/sheet.png: a linha da voz dublada deve ficar dentro dos slots das linhas de origem; azul (deslocamento) é aceitável, vermelho (estouro) e roxo (atrasado) não. Leia out/<lang>/report.md.
  8. $D/dub verify <projeto> --asr: verifica duração, loudness (medido com ffmpeg ebur128: dentro de 0.5 LU do alvo, pico verdadeiro no máximo 0.5 dB acima do teto, pois a codificação AAC pode adicionar um pouco), flags e o rótulo de voz sintética no MP4, e lê a dublagem com reconhecimento de fala. Você não pode ouvir o resultado: essa pontuação de leitura é como você verifica se a voz diz as palavras corretas. Linhas abaixo de 60% são listadas; verifique-as.
  9. Entrega: os caminhos dos MP4s, arquivos de legenda e relatórios, o loudness medido, as pontuações de leitura e a frase do rótulo.

O que vai onde

  • dub.json: configurações e declaração de direitos. fit.maxTempo (1.25), fit.gap (0.12 s entre linhas), fit.maxEarly (0.3 s uma linha pode começar antes), loudness.target (-16 LUFS) e ceiling (-1.5 dBTP), mix.background / mix.voice (dB), mix.duck (dB, para o fallback duck), keepOriginal (true mantém o áudio original como uma segunda faixa não padrão), separation.
  • source.json: as linhas de origem temporizadas. translations/<lang>.json: suas traduções.
  • out/<lang>/: <nome>.<lang>.mp4, <nome>.<lang>.srt|vtt (apenas dublagem), <nome>.<lang>+<src>.srt|vtt (bilíngue), report.md|json, sheet.png, README.md.
  • work/: cache (áudio extraído, fundo, linhas narradas), indexado pelo arquivo de origem exato, método de fundo e nível de duck. Seguro de excluir; verify --asr então precisa de dub build novamente, porque lê de work/<lang>/voice.wav.

Fundo (música e efeitos)

separation em dub.json ou --separation:

  • demucs (padrão quando instalado): htdemucs na CPU, cerca de 15 a 25 s para um clipe de 20 s aqui. Melhor resultado. Os pesos são baixados de uma revisão fixa do Hugging Face como safetensors e verificados contra valores SHA-256 fixos; o fallback pickle do demucs nunca é usado.
  • center: remove o que é centralizado (geralmente a voz). Apenas para estéreo real; também remove baixo centralizado e instrumentos mono.
  • duck: mantém o áudio original e o reduz (mix.duck, -18 dB) enquanto a voz original fala. A voz original permanece ligeiramente audível: informe o usuário.
  • none: apenas voz. auto escolhe demucs, senão centre (estéreo com conteúdo lateral real), senão duck, e o relatório diz qual foi usado.

Solução de problemas

  • Erros "muito longo": encurte a linha; não aumente maxTempo acima de cerca de 1.3, soa apressado.
  • Linhas atrasam (shift s cresce no relatório): uma linha anterior estourou; encurte-a.
  • Palavras mal interpretadas em source.json: edite o texto diretamente lá (mantenha ids e tempos) e não execute prepare novamente (ele recusa, e --force substituiria suas edições e as traduções). dub lint então avisa em cada tradução cujo source não corresponde mais: atualize essas traduções.
  • O vídeo tem texto ou legendas queimadas no idioma de origem: eles permanecem. Diga isso; a dublagem substitui apenas o som.
  • As bocas na tela não vão coincidir: esta é uma dublagem no estilo narração, não lip-sync.
  • dub prepare recusa: leia a mensagem (direitos, idioma, áudio ausente, legendas ruins) e corrija isso; não tente contornar a verificação de direitos.

Habilidades Relacionadas