Video-to-Text Skill (Vídeo para Texto)

Transforme a fala de vídeos/áudios em texto escrito. Aqui estão as regras testadas em batalha — siga a ordem estritamente, não tente pular o Passo 0.

Regra de Ferro (A Mais Importante, Memorize)

Sempre procure legendas existentes primeiro; use a transcrição por áudio apenas quando não houver alternativa. A maioria das palestras sérias, conferências e podcasts são enviados para o YouTube, e quase todos os vídeos do YouTube têm legendas automáticas — um comando baixa em segundos, é gratuito, não requer download do vídeo inteiro e não consome GPU.

Hoje mesmo, por não seguir este atalho, baixei um vídeo de 450 MB, processei por 30 minutos na CPU para transcrever e ainda recebi um texto cheio de erros. Não pise neste erro novamente.

Passo 0: Ao Obter um Link, Separe Duas Coisas, Depois Decida a Ordem

Transcrever (obter o texto da fala) e Investigar a Origem (quem falou, quando foi o original, se é completo) são coisas diferentes; não as misture. A abordagem antiga de "ao ver X, vá direto para o YouTube" está errada — o próprio X frequentemente tem legendas, então a ida ao YouTube é desnecessária.

Transcrever: sempre explore primeiro o link atual, não presuma que precisa ir ao YouTube.

1. Execute grab.py diretamente — o script tentará extrair as legendas do próprio link (X frequentemente tem legendas en/es etc.). Se conseguir, o trabalho está feito — este é o caminho mais rápido.
2. Só vale a pena ir ao YouTube procurar a versão original em dois casos:
   • O X não tem legendas (o YouTube provavelmente terá);
   • O X é um clipe — o texto menciona um vídeo mais longo, mas o post no X tem apenas um ou dois minutos (baixar isso renderia apenas um trecho; para o vídeo completo, vá ao original). Como procurar: pesquise "palestrante + tema/título + nome do evento" no YouTube para encontrar a versão original e use-a no Passo 1.

Duração é o espelho da verdade: primeiro use yt-dlp --no-download --print "%(duration_string)s" para verificar. Se o clipe do X tiver duração próxima ao que o texto descreve (ex.: diz "28 minutos", e o vídeo tem 27min) = é uma cópia completa; baixe diretamente. Se for muito mais curto = é um clipe; procure a versão original.

Investigar a Origem (quem/quando/completo) é uma tarefa separada; só faça se o usuário pedir, não é etapa obrigatória para transcrição. E pare quando tiver informação suficiente para responder à pergunta do usuário; não insista em precisão de data, versão oficial etc. que o usuário não solicitou (já pisei nesse erro em 2026-07-22).

Passo 1: Execute o Script com Um Comando (Ele Decide se Usa Legenda ou Transcrição por Áudio)

python "C:/Users/Administrator/.claude/skills/视频转文字/scripts/grab.py" "<link ou arquivo local>" "<nome da pasta de saída>" [idioma]

O terceiro parâmetro [idioma] é opcional: para vídeos em chinês, use zh (forçará saída em chinês simplificado); para inglês, use en; se omitido, o script detecta automaticamente.

Lógica interna do script (já codificada):

• Tenta extrair legendas existentes → se bem-sucedido, gera 完整文字稿.txt (texto limpo) em segundos. Fim.
• Se não encontrar legendas → extrai o áudio automaticamente e usa a GPU para transcrição (não a CPU).
• Os resultados são salvos na área de trabalho, na pasta <nome da pasta de saída>: 完整文字稿.txt (texto limpo) + arquivos de legenda originais.

Após a execução, informe ao usuário o local do arquivo 完整文字稿.txt e a contagem de palavras.

Bilibili / Sites Nacionais (Diferente do YouTube, Memorize Separadamente)

• Download: A ferramenta de download suporta Bilibili (B站) e vários sites nacionais; baixar vídeo/áudio funciona.
• Mas a opção de "extrair legendas existentes" é praticamente inútil: Bilibili não tem legendas automáticas em todo o site como o YouTube; apenas alguns criadores enviam legendas CC manualmente. Comentários flutuantes (弹幕) não são legendas (são comentários do público, não o texto falado). Não tente extrair comentários.
• Portanto, para a maioria dos vídeos do Bilibili, vá direto para transcrição por GPU. Para vídeos em chinês, lembre-se de passar o terceiro parâmetro como zh:

  python ".../grab.py" "<link do Bilibili>" "<nome da pasta>" zh
  

• Precisão do chinês: Atualmente usamos o modelo small; para chinês, ele capta apenas o "sentido geral" e pode conter erros de caractere. Para maior precisão, seria necessário trocar para o modelo medium (~1,5 GB, download único, ainda não instalado). O usuário em 2026-07-21 optou por "usar o small por enquanto"; para mais precisão, instale o medium e altere --model small para medium no script.
• Login: Vídeos exclusivos para membros do Bilibili, em alta qualidade ou que exigem login precisam de cookie da conta. Pergunte ao usuário antes de usar, nunca acesse a conta sem autorização.

Vídeos sem Link Acessível (WeChat Video / Páginas Pagas Criptografadas / Qualquer Conteúdo Apenas na Tela) → Grave o Áudio da Tela

Ferramentas de download não alcançam esses vídeos (WeChat Video está dentro do app, páginas pagas têm criptografia). A única solução universal: reproduza o vídeo e grave o áudio do sistema ao mesmo tempo, depois transcreva. O ambiente local já possui capacidade de gravação interna (biblioteca soundcard, sem necessidade de drivers ou configurações).

Três passos:

1. Inicie a gravação (roda em segundo plano até você pará-la):

   python "C:/Users/Administrator/.claude/skills/视频转文字/scripts/record.py" "<nome da pasta de saída>"
   

2. Reproduza o vídeo do início ao fim (gravação em tempo real; um vídeo de 3 horas exigirá 3 horas de reprodução, sem adiantamento).
3. Pare o processo de gravação (interromper a tarefa em segundo plano do agente = parada forçada, mas é seguro). Em seguida, alimente o arquivo 录音.pcm diretamente para o grab.py (ele reconhece PCM; para chinês, adicione zh):

   python "C:/Users/Administrator/.claude/skills/视频转文字/scripts/grab.py" "<caminho da área de trabalho>/<pasta>/录音.pcm" "<pasta>" zh
   

• A gravação é feita diretamente em disco; mesmo se for interrompida abruptamente, o arquivo PCM não é perdido (não depende de nenhum passo de "finalização").
• Se houver link, não use gravação: download leva minutos; a gravação exige esperar o tempo real do vídeo. A gravação de tela só deve ser usada quando realmente não for possível obter um link.

Passo 2: Coisas para se Preocupar Apenas ao Usar Transcrição por Áudio

• Deve usar a GPU: Esta máquina tem uma NVIDIA GTX 1060 (5 GB de VRAM); o script usará a GPU automaticamente por padrão. Se um dia os logs mostrarem "CPU", significa que a versão do torch com suporte a GPU foi substituída pela versão CPU; siga a seção [Fundação da GPU] abaixo para corrigir.
• Para vídeos longos (>20 minutos), a lentidão é normal, mas com GPU deve levar minutos; se demorar 30 minutos, é sinal de que caiu para CPU.
• Transcrição por áudio inevitavelmente tem erros de caractere/palavras faltando; é "aproxidamente o que foi dito", com precisão menor que legendas nativas. Se puder extrair legendas, não use transcrição.

Fundação da GPU (Necessária para Transcrição por Áudio; Siga para Reparar se Quebrada)

Para usar a GPU na transcrição, é necessário ter a versão do torch com suporte a CUDA. Verifique:

C:/Users/Administrator/portable-python311/runtime/python.exe -c "import torch;print(torch.__version__, torch.cuda.is_available())"

• Se mostrar ...+cu126 True = normal, GPU funcionando.
• Se mostrar ...+cpu False = caiu para CPU apenas; reinstale:

C:/Users/Administrator/portable-python311/runtime/python.exe -m pip install --force-reinstall torch==2.11.0 --index-url https://download.pytorch.org/whl/cu126

(Direcionado para CUDA 12.6 → use o índice cu126. Esta GPU de 5 GB é suficiente para reconhecimento de fala, OCR e modelos pequenos/médios; não suporta modelos grandes que exigem 8 GB ou mais de VRAM.)

Comandos Manuais Comuns (Fora do Script, para Consulta)

• Verificar quais idiomas de legenda estão disponíveis: yt-dlp --no-download --list-subs "<url>"
• Baixar apenas legendas em inglês sem baixar o vídeo: yt-dlp --skip-download --write-auto-subs --sub-langs "en-orig,en.*" --convert-subs srt -o "%(title)s.%(ext)s" "<url>"
• Verificar duração/data de publicação: yt-dlp --no-download --print "%(title)s | %(duration_string)s | %(upload_date)s" "<url>"