Transcrição de YouTube / Áudio
Transforme um vídeo do YouTube — ou qualquer arquivo de áudio/vídeo local — em uma transcrição sem depender de legendas fornecidas pelo YouTube. Muitos vídeos (especialmente reenvios e alguns vídeos em chinês) não possuem legendas e não possuem legendas automáticas, portanto baixar legendas com yt-dlp --write-subs não retorna nada. Esta skill contorna isso baixando o áudio e transcrevendo-o localmente com um motor whisper escolhido pela plataforma.
Quando usar esta skill
- O usuário fornece uma URL do YouTube e deseja as legendas / 字幕 / 逐字稿 / transcrição / captions.
yt-dlp --list-subsinformahas no subtitles/has no automatic captions.- O usuário tem um arquivo local
.m4a/.mp3/.mp4/etc. para transcrever.
Pré-requisitos
uvinstalado (usado para executaryt-dlpe o script de transcrição sem poluir o ambiente global). O script seleciona automaticamente o motor whisper euvinstala apenas o que sua plataforma precisa:- Mac Apple Silicon →
mlx-whisper(MLX/Metal, acelerado por GPU). - Mac Intel / Linux / Windows →
faster-whisper(CTranslate2, CPU ou NVIDIA CUDA).
- Mac Apple Silicon →
- Um runtime JavaScript —
node,bunoudeno— no PATH. O yt-dlp recente precisa de um para extrair do YouTube; o script detecta automaticamente qual está presente. - ffmpeg recomendado, mas não obrigatório: se ausente, o script usa o
afconvertnativo do macOS (em sistemas que não sejam macOS, instale o ffmpeg).
Uso
Todo o pipeline é um único script autossuficiente. Execute-o com uv run para que as dependências sejam provisionadas automaticamente:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py \
"https://www.youtube.com/watch?v=VIDEO_ID" \
--output-dir /tmp/whisper_out
Opções comuns:
--language zh— força um idioma em vez de detecção automática (mais rápido, evita erros de detecção em introduções bilíngues).--model mlx-community/whisper-large-v3-turbo— o padrão; boa relação velocidade/qualidade no Apple Silicon. Substitua pormlx-community/whisper-large-v3para máxima qualidade ou um modelo menor para velocidade.--output-name meu-video— nome base para os arquivos de saída (o padrão é o id do vídeo).--formats txt,srt— escolha quais saídas escrever (o padrão étxt,srt,json).
Um arquivo local funciona da mesma forma — basta passar o caminho em vez de uma URL:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py /caminho/para/palestra.m4a --language en
A primeira execução baixa o modelo whisper (~1,6 GB para o turbo) no cache do Hugging Face; execuções posteriores o reutilizam.
Saídas
Escritas em --output-dir (o padrão é o diretório atual), nomeadas de acordo com o id do vídeo (ou --output-name):
<nome>.txt— transcrição em texto puro (um bloco único).<nome>.srt— legendas com timestamps.<nome>.json— resultado completo incluindo timestamps por segmento e idioma detectado.
Após a transcrição
A saída bruta do whisper reflete o idioma falado exatamente como é. Se o áudio for em mandarim, o whisper emite Chinês Simplificado. De acordo com a regra global do usuário, ao apresentar a transcrição no chat, converta-a para 正體中文 (Tradicional) e corrija erros óbvios de interpretação de nomes próprios / termos técnicos (nomes de modelos, IDs CVE, nomes de ferramentas). Ofereça um resumo organizado e dividido em seções, em vez de despejar um bloco enorme de texto, e informe ao usuário onde os arquivos completos estão localizados.
Como funciona (e por quê)
- Baixar áudio —
yt-dlp -f "bestaudio[ext=m4a]/bestaudio". O formato 140 (m4a de 128 kbps) é baixado sem resolver o desafio "n" do player JS do YouTube, então evitamos--remote-components ejs:github(ele busca e executa código remoto e geralmente é bloqueado pela sandbox). O script prefixauvxseyt-dlpnão estiver instalado e adiciona--js-runtimes <node|bun|deno>para o runtime que existir. - Normalizar áudio — converte para WAV de 16 kHz, mono, 16 bits com ffmpeg, ou com
afconvertdo macOS se o ffmpeg estiver ausente. - Transcrever — lê o WAV em um array numpy float32 e o passa diretamente para o motor (
mlx_whisper.transcribe(...)no Apple Silicon,faster_whisper.WhisperModel.transcribe(...)nos demais). Ambos produzem a mesma estrutura de resultado normalizada (text/language/segments). Entregar um array decodificado ao whisper significa que ele nunca chama o ffmpeg internamente — que é a causa usual deFileNotFoundError: ffmpegem máquinas sem ele.
Solução de problemas
has no subtitlesmas você ainda quer texto — é exatamente para isso que esta skill serve; prossiga para transcrever o áudio.FileNotFoundError: ffmpeg— não deve acontecer com este script (ele converte primeiro), mas se você chamar o motor whisper diretamente em um m4a, converta para WAV primeiro.- Em sistemas que não sejam Apple Silicon e a conversão falhar —
afconverté exclusivo do macOS, então instaleffmpeg(Linux/Windows não têm alternativa nativa). - yt-dlp avisa sobre desafio JS / "Only images are available" — certifique-se de que
node/bun/denoestá no PATH; o script precisa de um para extração. Não recorra a--remote-components ejs:githubpara corrigir isso. - Saída confusa / no idioma errado — passe
--languageexplicitamente.