Communitygithub.com

chenwei791129/agent-skills

Transcreva um vídeo do YouTube (ou qualquer arquivo de áudio/vídeo local) em transcrição de texto, legendas SRT e JSON usando whisper localmente. Use sempre que o usuário compartilhar uma URL do YouTube e quiser legendas, transcrições, 字幕 ou 逐字稿 — especialmente quando o vídeo não tiver legendas para baixar — ou quiser transcrever / 轉錄 um arquivo de áudio ou vídeo. Dispara em solicitações como "幫我抓這部 YouTube 的字幕/逐字稿", "transcreva este vídeo", "把這段音檔轉成文字". Executa localmente e é multiplataforma: mlx-whisper no Apple Silicon, faster-whisper nos demais.

O que é agent-skills?

Esta skill de agente de IA permite transcrição local de áudio de vídeos do YouTube ou arquivos locais, sem depender de legendas fornecidas pelo YouTube. É particularmente útil para vídeos que não possuem legendas disponíveis, como reenvios ou vídeos em chinês, onde a tentativa de baixar legendas com `yt-dlp --write-subs` falha. A habilidade contorna essa limitação baixando o áudio e transcrevendo-o utilizando um motor whisper otimizado para a plataforma (mlx-whisper no Apple Silicon, faster-whisper em outros sistemas). O script completo e autossuficiente gerencia automaticamente as dependências via `uv`, suporta opções como seleção de idioma e tamanho do modelo, e produz transcrições em formato de texto (.txt), legendas (.srt) e JSON com timestamps. É ideal para desenvolvedores que precisam de transcrições rápidas e precisas de conteúdo de áudio, especialmente quando o YouTube não oferece legendas baixáveis.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chenwei791129/agent-skills/tree/HEAD/skills/youtube-transcribe

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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-subs informa has no subtitles / has no automatic captions.
  • O usuário tem um arquivo local .m4a/.mp3/.mp4/etc. para transcrever.

Pré-requisitos

  • uv instalado (usado para executar yt-dlp e o script de transcrição sem poluir o ambiente global). O script seleciona automaticamente o motor whisper e uv instala 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).
  • Um runtime JavaScript — node, bun ou deno — 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 afconvert nativo 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 por mlx-community/whisper-large-v3 para 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ê)

  1. 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 prefixa uvx se yt-dlp não estiver instalado e adiciona --js-runtimes <node|bun|deno> para o runtime que existir.
  2. Normalizar áudio — converte para WAV de 16 kHz, mono, 16 bits com ffmpeg, ou com afconvert do macOS se o ffmpeg estiver ausente.
  3. 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 de FileNotFoundError: ffmpeg em máquinas sem ele.

Solução de problemas

  • has no subtitles mas 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 instale ffmpeg (Linux/Windows não têm alternativa nativa).
  • yt-dlp avisa sobre desafio JS / "Only images are available" — certifique-se de que node/bun/deno está no PATH; o script precisa de um para extração. Não recorra a --remote-components ejs:github para corrigir isso.
  • Saída confusa / no idioma errado — passe --language explicitamente.

Habilidades Relacionadas