Skill: transcrição-e-legendas-de-vídeo
Propósito
Transformar a fala de um vídeo em texto sem usar nenhum serviço em nuvem: baixar com yt-dlp, transcrever localmente com faster-whisper, gerar um SRT e, opcionalmente, gravar as legendas com ffmpeg para que apareçam em qualquer player.
Passos
1. Verificar ferramentas
which yt-dlp ffmpeg uv; nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null
uvx yt-dlp e uv run --with faster-whisper evitam instalar nada. Apenas o filtro subtitles do ffmpeg precisa de uma build real do ffmpeg com libass (ffmpeg -filters | grep subtitles); o binário empacotado do imageio-ffmpeg pode não ter esse recurso.
2. Baixar
uvx yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b" --merge-output-format mp4 -o "video.%(ext)s" --no-playlist "<url>"
uvx yt-dlp --skip-download -j "<url>" | jq '{title, uploader, upload_date, description}'
3. Transcrever para SRT
# srt.py — execute com: uv run --with faster-whisper python srt.py
from faster_whisper import WhisperModel
def ts(t):
h, r = divmod(t, 3600); m, s = divmod(r, 60)
return f"{int(h):02d}:{int(m):02d}:{int(s):02d},{int(s % 1 * 1000):03d}"
model = WhisperModel("large-v3", device="cpu", compute_type="int8") # device="cuda" se existir GPU
segments, info = model.transcribe("video.mp4", vad_filter=True, beam_size=5)
with open("video.srt", "w") as f:
for i, s in enumerate(segments, 1):
f.write(f"{i}\n{ts(s.start)} --> {ts(s.end)}\n{s.text.strip()}\n\n")
Escolha do modelo:
smallé rápido, mas distorce áudio com várias vozes, piadas e jargões. Bom para uma primeira olhada, não para legendas.large-v3é o modelo para usar de fato. É um primeiro download de ~3 GB em~/.cache/huggingface/hub/; em uma conexão lenta, isso pode levar 30 minutos ou mais. Avise e pergunte antes de iniciar;mediumtem metade do tamanho.- Execute transcrições longas em segundo plano e relate o progresso honestamente: verifique se o blob
.incompleteno cache do Hugging Face ainda está crescendo (baixando) ou se o processo está com alta CPU (transcrevendo).
4. Corrigir linhas mal interpretadas
O Whisper ainda interpreta mal nomes e palavras de domínio específico. Re-transcreva apenas o trecho problemático com dicas de vocabulário, em vez de reprocessar o arquivo inteiro:
ffmpeg -loglevel error -y -ss 53 -to 64 -i video.mp4 -vn -ac 1 -ar 16000 clip.wav
segments, _ = model.transcribe("clip.wav", beam_size=5,
initial_prompt="Lista curta de palavras esperadas: nomes de produtos, jargões, nomes de emojis.")
Em seguida, edite manualmente essas entradas do SRT (mantenha os timestamps). Capturar um quadro (ffmpeg -ss 58 -i video.mp4 -frames:v 1 f.jpg) ajuda quando o texto na tela desambigua o áudio. Informe ao usuário quais linhas ainda têm baixa confiança, em vez de apresentar um palpite como fato.
5. Gravar legendas
ffmpeg -hide_banner -loglevel error -y -i video.mp4 \
-vf "subtitles=video.srt:force_style='FontSize=20,Outline=1,MarginV=30'" \
-c:v libx264 -preset fast -crf 20 -c:a copy video_cc.mp4
Mantenha o SRT junto ao arquivo de saída, para que uma única linha possa ser corrigida e re-renderizada em menos de um minuto. Para legendas soft (alternáveis), multiplexe com ffmpeg -i video.mp4 -i video.srt -c copy -c:s mov_text video_cc.mp4.
Entregas
Vídeo original, vídeo legendado, arquivo .srt e a transcrição simples. Mencione o tamanho do modelo em cache para que o usuário possa excluí-lo.
Erros comuns
- Usar a saída do modelo
smallcomo legendas. - Iniciar o download de um modelo de vários GB sem perguntar.
- Reprocessar a transcrição completa para corrigir três linhas.
- Usar um ffmpeg sem libass e receber "No such filter: subtitles".