Communitygithub.com

dsh-auto-subtitle

Transforme qualquer arquivo de áudio ou vídeo em legendas totalmente offline, com detecção automática de idioma entre 99 línguas, transcrição com timestamps a nível de palavra, segmentação em falas legíveis, tradução para chinês e geração de legendas bilíngues (original+chinês) em SRT/ASS, com opção de queima direta no vídeo.

O que é dsh-auto-subtitle?

Esta skill permite converter qualquer arquivo de áudio ou vídeo em legendas automaticamente, funcionando 100% offline no próprio computador do usuário, sem necessidade de API keys ou serviços externos. Ela utiliza o modelo whisper.cpp (via babelscribe) para transcrição com reconhecimento automático de 99 idiomas e timestamps por palavra, re-segmenta as falas em legendas curtas e legíveis (≤20 caracteres para chinês, ≤48 para inglês), e traduz o conteúdo para chinês, gerando legendas bilíngues. Suporta múltiplos formatos de entrada (MP3, WAV, MP4, MKV, MOV, AVI, etc.) e produz arquivos SRT e ASS (com layout otimizado para queima e visualização em players). A skill também lida com casos problemáticos: insere pontuação automaticamente em transcrições de chinês e japonês (que o whisper geralmente omite), permite reexecução rápida com parâmetros ajustados (como `--accurate` para áudio com ruído ou sotaque), e oferece verificação de integridade para garantir que cada legenda tenha tradução correspondente. É ideal para usuários que desejam gerar legendas para vídeos ou áudios em qualquer idioma, especialmente falantes de chinês que precisam de legendas bilíngues ou apenas chinesas, sem depender de serviços online.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add hangzhouspark/dsh-auto-subtitle

Perguntar na sua IA favorita

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

Documentação

Auto Subtitle

Transforme qualquer arquivo de áudio ou vídeo em legendas. Por padrão gera legendas bilíngues (idioma original + chinês), tudo processado localmente, sem necessidade de API Key.

Como acionar

Dois cenários principais:

  1. Zero instrução: o usuário apenas envia um arquivo de áudio/vídeo sem dizer o que fazer → a skill já assume que ele quer legendas e inicia o processo sem perguntar.
  2. Comando direto: frases como "转字幕", "生成字幕", "做个字幕", "加个字幕", "翻译这段音频" acompanhadas do arquivo.

A única situação que requer pergunta adicional: se o usuário pedir explicitamente apenas chinês (sem a linha do idioma original), aí deve-se adicionar --mono. Nos demais casos, a skill executa o fluxo bilíngue padrão.

Ambiente

Três dependências, todas precisam estar no PATH:

DependênciaFunçãoComando de verificação
Python 3.10+Executa os scripts da skillpython --version
babelscribeMotor de transcrição (wrapper do whisper.cpp)babelscribe devices
ffmpegConversão de áudio e queima de legendas (com --burn)ffmpeg -version

Instale o motor: pip install babelscribe.

Não é necessário baixar modelos manualmente: na primeira execução, o babelscribe baixa automaticamente o ggml-large-v3-turbo.bin (∼1,6 GB) para ~/.babelscribe/models/. Na primeira execução para um idioma específico ou ao usar --accurate, pode baixar modelos adicionais — isso é normal, não é travamento.

Se houver placa NVIDIA, o backend Vulkan é selecionado automaticamente, sem necessidade de compilar CUDA. O comando babelscribe devices lista todos os dispositivos disponíveis e mostra qual será usado pelo modo auto. Testado: RTX 3050 Ti Laptop (4 GB VRAM) processa 48 segundos de áudio em cerca de 20 segundos; 51 minutos de replay em cerca de 13 minutos.

Os scripts da skill estão na pasta scripts/ no mesmo nível do SKILL.md.

No Windows, execute com $env:PYTHONIOENCODING='utf-8' para evitar caracteres chineses corrompidos no console.

Fluxo de trabalho

Passo 1 · Transcrição + re-segmentação

$env:PYTHONIOENCODING='utf-8'
python scripts/make_subtitles.py "<caminho ou URL do áudio/vídeo>" --outdir "<diretório de saída>"

Leia os valores KEY=VALUE no final do stdout:

ChaveSignificado
SOURCE_LANGIdioma identificado automaticamente, ex: en, zh, ja
STEMNome base dos arquivos gerados, usado nos passos seguintes
CUES_JSONPacote de falas para tradução, entrada do passo 3
SOURCE_SRTLegenda no idioma original (já re-segmentada, não a versão original do whisper)
NEEDS_TRANSLATIONyes = precisa traduzir para chinês; no = o áudio já é em chinês
PUNCTUATION_LOSTyes = qualidade de segmentação insuficiente, vá para o passo 2
TRANSCRIPT_TXTTexto sem pontuação (só aparece se PUNCTUATION_LOST=yes), entrada do passo 2

Por que re-segmentar? Os segmentos nativos do whisper costumam ter 7-8 segundos e centenas de caracteres, ficando poluídos como legenda. O script usa timestamps por palavra e corta em frases curtas com base em pontuação e pausas: ≤20 caracteres (chinês) / ≤48 caracteres (inglês).

Passo 2 · Inserção de pontuação para chinês/japonês (apenas se PUNCTUATION_LOST=yes)

O whisper insere pontuação apenas esporadicamente em chinês e japonês, deixando o resto com cortes baseados em pausas. Em chinês, frases podem ser cortadas como "转成文 / 字"; em japonês é pior — o idioma não tem espaços entre palavras, e os parágrafos do whisper se unem, dificultando até pausas. O resultado são legendas cortadas exatamente a cada 20 caracteres, gerando coisas como "申 / し訳ない" ou "くま / るさん". A solução é alinhar as legendas com pontuação real:

  1. Leia TRANSCRIPT_TXT (texto puro e sem pontuação).
  2. Insira apenas pontuação, não altere nenhum caractere. Mesmo palavras claramente erradas — se o ASR ouviu "击翻" em vez de "机翻", ou "おやすい" em vez de "おやすみ" — mantenha-as. Alterar caracteres faz o realinhamento falhar e a pontuação não será aplicada.
  3. Escreva o arquivo <STEM>.punct.txt (UTF-8).
  4. Execute novamente o passo 1 com --punct-file (reutiliza <STEM>.raw.json, conclui em segundos sem retranscrever):
python scripts/make_subtitles.py "<entrada>" --outdir "<diretório de saída>" --punct-file "<STEM>.punct.txt"

A densidade de pontuação é o único indicador realmente importante neste passo. Como o limite da legenda é de 20 caracteres, a pontuação precisa ser mais densa que em texto escrito: a cada 8-18 caracteres deve haver um "、" ou "。". Densidade insuficiente ainda resulta em cortes arbitrários — teste com 51 minutos de áudio em japonês:

Densidade de pontuaçãoNúmero de legendasFinal com pontuação
Sem correção82125%
∼32 caracteres/pontuação (muito espaçado)100576%
8-18 caracteres/pontuação108198%

"、" deve ser usado em quebras de grupo de palavras, pausas curtas após partículas, pausas de fala — serve para quebrar linhas da legenda, sendo mais frequente que no japonês escrito (isso não é um erro de formatação). Apenas 。 、 ! ? … são permitidos; 「」 etc. não estão na tabela de pontuação do script e serão ignorados.

Após a correção, cada legenda no SOURCE_SRT terminará com pontuação. Se aparecer WARN: ... taxa de falha de alinhamento NN%, significa que caracteres foram alterados — volte e insira apenas pontuação.

Como corrigir áudios longos? Um áudio de 51 minutos tem 14000+ caracteres, impossível corrigir de uma vez. Divida em blocos de ∼1500 caracteres, envie cada bloco para um agente paralelo (com 200 caracteres de contexto antes e depois, mas o agente só produz o bloco atual) e, ao final, use um script para verificar "removendo toda a pontuação, o texto coincide caractere por caractere com o original" antes de concatenar. Essa verificação é obrigatória — não confie na autoavaliação do agente: em 10 blocos, 2 podem afirmar "verificação caractere por caractere passou" mas terem removido ou alterado caracteres.

Mudar a densidade é barato: como o raw.json é reutilizado, o custo de tentativa e erro é quase zero. Se após a primeira correção apenas 76% terminam com pontuação, basta refazer a correção.

Passo 3 · Tradução (apenas se NEEDS_TRANSLATION=yes)

Leia CUES_JSON, que contém {"cues": [{"id":1,"start":...,"end":...,"text":"..."}]}.

  • Primeiro leia o bloco inteiro para entender o contexto, depois distribua a tradução em chinês para cada cue. Traduzir cada cue isoladamente pode quebrar frases que cruzam múltiplas cues (ex: "replacing people." isolado seria traduzido como "取代人们" perdendo o contexto anterior).
  • Cada legenda em chinês deve ter no máximo 16 caracteres e deve caber na duração da cue (velocidade de leitura em chinês ∼4-5 caracteres/segundo; uma cue de 1,2s com 18 caracteres é impossível de ler).
  • Escreva o resultado em <STEM>.zh.json, formato {"1": "primeira tradução", "2": "..."}, com id correspondente aos cues.
  • Mantenha consistência terminológica; nomes próprios mantenha o original ou use tradução consagrada.

Passo 4 · Geração dos produtos finais

python scripts/merge_bilingual.py "<STEM>.cues.json" "<STEM>.zh.json"

Parâmetros opcionais:

  • --mono — apenas a tradução, sem o texto original (quando o usuário quer legenda só em chinês)
  • --order zh-first — chinês em cima (padrão: original em cima)
  • --burn "<caminho do vídeo>" — queima as legendas bilíngues diretamente no vídeo, gerando <STEM>.bilingual.burned.mp4. Use apenas se o usuário forneceu um vídeo e realmente precisa de legendas embutidas (queimar é lento e irreversível).

Produtos:

  • <STEM>.bilingual.srt — legenda bilíngue SRT, compatível com qualquer player/plataforma
  • <STEM>.bilingual.ass — chinês grande, original pequeno, ideal para queima ou players profissionais

Passo 5 · Relatório final

Ao final, forneça uma conclusão em uma frase com números-chave (idioma, duração, número de legendas, caminhos dos arquivos). Mostre 2-3 exemplos de legendas prontas para que o usuário veja a qualidade. Não exiba logs extensos.

Parâmetros comuns

CenárioParâmetro
Áudio com ruído, sotaque pesado ou terminologia específica--accurate (troca para large-v3 + beam search, 2-3x mais lento mas mais preciso)
Idioma detectado incorretamente--lang zh (ou en, ja, th...)
Legendas mais curtas ou mais longas--max-chars 16 (para chinês conta em caracteres)
URL de vídeoPasse a URL diretamente, o script usa yt-dlp internamente
Reexecutar com nova pontuação/segmentação--punct-file <arquivo> (reutiliza <STEM>.raw.json, instantâneo) ou --from-raw <STEM>.raw.json

Cuidados

  • Não use a saída .srt nativa do babelscribe como produto final — cada linha é um segmento do whisper sem controle de tamanho. O script da skill já re-segmentou corretamente.
  • Não altere o texto transcrito para "corrigir" erros de digitação. Se precisar corrigir, faça na camada de tradução.
  • Arquivos de música pura ou silêncio retornarão ERROR: transcrição vazia — não é um bug, apenas informe o usuário.
  • Áudios longos (>30 min) geram muitos cues no passo 3. Traduza em lotes, mas mantenha correspondência de IDs. Um agente que retorna ok não garante que o arquivo foi realmente escrito — em 20 lotes de tradução, 1 retornou status: ok sem gravar o arquivo e outro retornou null. Antes de finalizar, use um script para verificar se cada cue id tem tradução correspondente — não confie na autoavaliação do agente.
  • Não use python -c "..." no PowerShell para scripts com aspas — as aspas podem ser removidas causando SyntaxError. Escreva o script em um arquivo .py e execute.
  • Na primeira execução para um idioma específico ou ao usar --accurate, pode baixar modelos adicionais — isso é normal, não é travamento.

Autoteste

Após alterar o script, use os arquivos fixos em examples/ para regressão:

powershell -NoProfile -ExecutionPolicy Bypass -File "examples\gen_fixtures.ps1"
python scripts/make_subtitles.py "examples\audio\zh.wav" --outdir "examples\out"
python scripts/make_subtitles.py "examples\audio\en.wav" --outdir "examples\out"

examples\zh.txt / examples\en.txt são lidos pelo Windows SAPI para gerar examples\audio\zh.wav / en.wav (requer voz chinesa Microsoft Huihui Desktop, presente no Windows em chinês). Resultados esperados:

  • Chinês: 9 legendas sem pontuação, cerca de 6 sem pontuação no final (PUNCTUATION_LOST=yes); após correção de pontuação, 10 legendas, todas terminando com pontuação
  • Inglês: 19 legendas, no máximo ≤48 caracteres

Habilidades Relacionadas