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:
- 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.
- 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ência | Função | Comando de verificação |
|---|---|---|
| Python 3.10+ | Executa os scripts da skill | python --version |
| babelscribe | Motor de transcrição (wrapper do whisper.cpp) | babelscribe devices |
| ffmpeg | Conversã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:
| Chave | Significado |
|---|---|
SOURCE_LANG | Idioma identificado automaticamente, ex: en, zh, ja |
STEM | Nome base dos arquivos gerados, usado nos passos seguintes |
CUES_JSON | Pacote de falas para tradução, entrada do passo 3 |
SOURCE_SRT | Legenda no idioma original (já re-segmentada, não a versão original do whisper) |
NEEDS_TRANSLATION | yes = precisa traduzir para chinês; no = o áudio já é em chinês |
PUNCTUATION_LOST | yes = qualidade de segmentação insuficiente, vá para o passo 2 |
TRANSCRIPT_TXT | Texto 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:
- Leia
TRANSCRIPT_TXT(texto puro e sem pontuação). - 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.
- Escreva o arquivo
<STEM>.punct.txt(UTF-8). - 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ção | Número de legendas | Final com pontuação |
|---|---|---|
| Sem correção | 821 | 25% |
| ∼32 caracteres/pontuação (muito espaçado) | 1005 | 76% |
| 8-18 caracteres/pontuação | 1081 | 98% |
"、" 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": "..."}, comidcorrespondente 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ário | Parâ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ídeo | Passe 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
.srtnativa 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
oknão garante que o arquivo foi realmente escrito — em 20 lotes de tradução, 1 retornoustatus: oksem 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 causandoSyntaxError. Escreva o script em um arquivo.pye 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