haoyiyin/easy-subtitle

Quando Usar

Use esta skill quando o usuário precisar:

• Gerar legendas SRT a partir de um arquivo de áudio ou vídeo (offline, sem chamadas de API)
• Detectar automaticamente o idioma falado em um arquivo de mídia
• Corrigir erros de transcrição do Whisper usando um roteiro original fornecido (原口播文本)
• Processar arquivos de mídia em lote para gerar legendas

NÃO use para:

• Transcrição em tempo real/ao vivo (faster-whisper é offline/em lote)
• Formatos de saída diferentes de SRT (apenas SRT é suportado)
• Transcrição baseada em nuvem (este recurso é apenas local)

Procedimento

1. Instale as dependências: pip install faster-whisper. Instale o ffmpeg para seu sistema operacional:
   • macOS: brew install ffmpeg
   • Linux: sudo apt install ffmpeg (Debian/Ubuntu) ou sudo dnf install ffmpeg (Fedora)
   • Windows: choco install ffmpeg (Chocolatey) ou scoop install ffmpeg (Scoop), ou faça o download em https://ffmpeg.org
2. Certifique-se de que o pacote easy-subtitle está instalado: pip install -e . a partir da raiz do projeto.
3. Transcrição básica: Execute easy-subtitle -i video.mp4 para gerar video.srt com idioma detectado automaticamente.
4. Especificar idioma: Execute easy-subtitle -i audio.wav -l zh se você souber o idioma (mais rápido e preciso que a detecção automática).
5. Corrigir com roteiro original: Execute easy-subtitle -i video.mp4 --original-text script.txt para alinhar e corrigir a transcrição usando o roteiro fornecido.
6. Ajustar tamanho do modelo: Use -m small para velocidade ou -m large-v3 para precisão. O padrão é medium.
7. Ajustar VAD: Use --vad-min-silence 1000 para uma divisão de silêncio mais agressiva (conteúdo mais silencioso). Use --no-vad para desativar.

Armadilhas

• Na primeira execução, o modelo é baixado (~1,5 GB para o medium) — reserve tempo e espaço em disco extras.
• A detecção automática de idioma do Whisper pode ser imprecisa para clipes muito curtos (<5 segundos) — use -l para especificar manualmente.
• O alinhamento com roteiro original funciona melhor quando o roteiro corresponde exatamente ao áudio. Ad-libs, pausas e improvisações permanecem como saída do Whisper.
• O faster-whisper usa quantização INT8 por padrão na CPU — isso é rápido, mas ligeiramente menos preciso que FP16 na GPU.
• O ffmpeg deve ser instalado separadamente (não é um pacote Python).
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg
  • Windows: choco install ffmpeg ou download em https://ffmpeg.org

Verificação

1. Execute easy-subtitle --version para confirmar a instalação.
2. Teste a transcrição básica: easy-subtitle -i test_audio.mp3 -m tiny deve produzir um arquivo .srt rapidamente.
3. Verifique a saída SRT: abra em um player de vídeo ou confira se contém blocos numerados com timestamps no formato HH:MM:SS,mmm --> HH:MM:SS,mmm.
4. Teste o alinhamento com roteiro original: forneça um roteiro que corresponda ao áudio — a saída deve conter o texto exato do roteiro, não a transcrição do Whisper.