ZJU-REAL/Easel

Legenda Automática (Fala para Legenda)

Transcreve a fala de arquivos de áudio/vídeo para legendas. Baseado no script compartilhado skills/shared/scripts/asr.py (wrapper do faster-whisper), parâmetros determinísticos e reprodutíveis, com quebra de linhas amigável para chinês. Opcionalmente, é possível queimar as legendas no vídeo (reutilizando skills/shared/scripts/video_ops.py / filtro de legendas do ffmpeg).

Apenas "fala → arquivo de legenda (+ queima opcional)". Para edição geral de vídeo, veja video-editing; para redução de ruído puro, veja audio-denoise; para corte inteligente de vídeos longos com queima de legendas, veja clipify.

Entrada

Campo	Obrigatório	Descrição
input_file	Sim	Caminho do arquivo de áudio ou vídeo (vídeo extrai faixa de áudio automaticamente)
format	Não	srt (padrão) / ass / txt / json
language	Não	auto (padrão) ou código ISO 639-1 como zh/en
model	Não	tiny/base (padrão)/small/medium/large-v3, quanto maior, mais preciso e mais lento
burn	Não	Se deve queimar a legenda no vídeo (requer entrada de vídeo)

Suporta: áudio mp3/wav/m4a/aac/flac; vídeo mp4/mkv/mov/webm.

Saída

• Arquivo de legenda colocado em outputs/nome_do_tema/ (SRT/ASS/TXT/JSON)
• Se queimado: vídeo com legenda permanente (*-sub.mp4)
• Relatório: idioma detectado, número de linhas de legenda, modelo utilizado, caminhos de saída

Pré-requisitos

• Na primeira execução, o modelo é baixado do HuggingFace, requer proxy de internet. O script lê a variável de ambiente EASEL_PROXY ou http(s)_proxy como proxy; se nenhuma estiver definida, conexão direta. Também é possível especificar com export https_proxy=... http_proxy=....
• Ambiente com CPU use o padrão --device cpu --compute-type int8.

Etapas de Execução

Caminhos dos scripts (relativos à raiz do projeto): skills/shared/scripts/asr.py, skills/shared/scripts/video_ops.py.

1. Gerar Arquivo de Legenda

# Vídeo → SRT (extrai faixa de áudio + detecta idioma automaticamente)
python skills/shared/scripts/asr.py transcribe \
  -i input.mp4 -o outputs/nome_do_tema/input.srt --language zh

# Vídeo → ASS (com estilos, **tamanho da fonte/margem adaptados automaticamente para orientação do vídeo**): entrada de vídeo detecta proporção automaticamente
python skills/shared/scripts/asr.py transcribe \
  -i input.mp4 -o outputs/nome_do_tema/input.ass --format ass --model small
# Áudio puro → ASS: não é possível detectar dimensões, padrão retrato 1080x1920; paisagem adicione --res 1920x1080
python skills/shared/scripts/asr.py transcribe \
  -i voice.mp3 -o outputs/nome_do_tema/voice.ass --format ass --res 1920x1080

• Estilos ASS adaptados automaticamente para a largura/altura do vídeo alvo: tamanho da fonte baseado no lado menor (min(w,h)*0.05, adequado tanto para retrato quanto paisagem, sem ser grande demais em paisagem), margem inferior baseada na altura, margens laterais baseadas na largura, PlayRes = largura/altura reais. Entrada de vídeo detecta automaticamente; para áudio puro use --res larguraxaltura. Para legendas duras com estilo, priorize queimar este ASS (próxima seção), mais prático do que SRT puro + preenchimento manual de force_style, e com adaptação automática.
• Chinês: padrão ~18 caracteres por linha, quebra/divisão automática para linhas muito longas; ajustável com --max-line-chars.
• Se -o não for fornecido, cria diretório do projeto baseado no nome do arquivo de entrada, ex.: talk.mp4 gera saída em outputs/talk/talk.srt; para projetos existentes, use explicitamente -o outputs/nome_do_tema/<arquivo>.<formato>.
• Veja modelos/idiomas disponíveis: python skills/shared/scripts/asr.py info.

2. (Opcional) Queimar Legenda no Vídeo

Quando o usuário quiser "legenda dura/queimada no vídeo", use o filtro subtitles (SRT) ou ass (ASS) do ffmpeg:

# Queimar SRT (estilos personalizáveis)
ffmpeg -y -i input.mp4 \
  -vf "subtitles=outputs/nome_do_tema/input.srt:force_style='FontName=Noto Sans CJK SC,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H80000000,BorderStyle=1,Outline=2'" \
  -c:a copy outputs/nome_do_tema/input-sub.mp4

# Queimar ASS (estilos já no arquivo ass, fiel)
ffmpeg -y -i input.mp4 \
  -vf "ass=outputs/nome_do_tema/input.ass" \
  -c:a copy outputs/nome_do_tema/input-sub.mp4

• Se o caminho contiver caracteres especiais, envolva o valor de subtitles= em aspas simples e escapando os dois-pontos.
• Para legendas soft (desativáveis) em vez de queimadas: ffmpeg -i in.mp4 -i sub.srt -c copy -c:s mov_text out.mp4.

3. Artefatos e Relatório

• Arquivos de legenda e vídeo com legenda são escritos em outputs/nome_do_tema/.
• Relate ao usuário: idioma detectado, número de linhas de legenda, modelo, caminhos dos arquivos; sugira que pode reexecutar com --model/--max-line-chars.

Regras

1. Vídeo primeiro extrai faixa de áudio — O script usa ffmpeg automaticamente para extrair wav mono de 16kHz, sem modificar o vídeo original.
2. Quebra de linhas amigável para chinês — Quebra com base em pontuação/comprimento, evitando linhas muito longas.
3. Nunca deletar arquivos originais — Apenas cria novos arquivos em outputs/.
4. Escolha do modelo — Para rapidez use base, para precisão use small/medium; CPU use int8.
5. Queima requer entrada de vídeo — Áudio puro não pode ser queimado, apenas gera arquivo de legenda.
6. Sem dependência de perfil — Transcrição não precisa de perfil de conta.

Referências Próprias

• SYSTRAN/faster-whisper — Inferência Whisper acelerada com CTranslate2
• openai/whisper — Modelo Whisper original e método ASR
• Filtros subtitles / ass do FFmpeg (queima de legendas)