youtube-transcript-cli

name

youtube-transcript-cli

description

Obtém transcrições de vídeos do YouTube via linha de comando (CLI/npx). Use esta skill sempre que o usuário compartilhar uma URL do YouTube e quiser ler, resumir, analisar, transcrever ou extrair informações do vídeo — e não houver uma ferramenta MCP transcript_yt disponível, ou o agente tiver acesso a terminal/bash. Exemplos de trigger: "transcreve esse vídeo", "o que esse vídeo fala?", "me dá um resumo", "quais os pontos principais?", colar uma URL do YouTube sem mais contexto quando a intenção implica entender o conteúdo. Aciona também quando o usuário pede para responder perguntas sobre o conteúdo de um vídeo.

O que esta skill faz

Usa a CLI youtube-transcript-mcp (via npx ou local) para buscar a transcrição (legendas) de qualquer vídeo do YouTube e processa o resultado de acordo com o que o usuário precisa.

Esta skill é uma alternativa à ferramenta MCP transcript_yt — use quando não houver MCP configurado mas houver acesso a terminal (bash/Node 18+).

Pré-requisitos

• Node.js 18+ instalado (para uso via npx ou node)
• Acesso a internet (o CLI faz fetch do YouTube)

Nenhuma instalação permanente é necessária — npx baixa o pacote sob demanda.

Como invocar

Via npx (recomendado — sem instalação)

npx -y --package=github:lucasliet/youtube-transcript-mcp#main youtube-transcript-mcp --videoUrl "URL_DO_VIDEO" --preferredLanguages "pt-BR,en"

Via instalação local no projeto

npm i github:lucasliet/youtube-transcript-mcp#main
npx youtube-transcript-mcp --videoUrl "URL_DO_VIDEO" --preferredLanguages "pt-BR,en"

Via node direto (clone do repositório)

node src/cli.js --videoUrl "URL_DO_VIDEO" --preferredLanguages "pt-BR,en"

Parâmetros

Parâmetro	Obrigatório	Descrição
--videoUrl	sim	URL do vídeo (watch?v=, youtu.be/, embed/, v/, live/)
--preferredLanguages	não	Lista ordenada de idiomas em CSV, ex: "pt-BR,en". Default: automático

Saída

O CLI imprime JSON no stdout. Não há logs extras no stdout — qualquer log vai para stderr.

Sucesso — array de segmentos:

[
  { "text": "Intro...", "startInMs": 0, "duration": 2300 },
  { "text": "Próximo segmento", "startInMs": 2300, "duration": 1800 }
]

Falha — imprime null no stdout e detalhes categorizados no stderr.

Sempre faça JSON.parse do stdout para obter o resultado. Se o resultado for null, o vídeo não tem legendas disponíveis ou é inacessível (privado, sem legendas, bloqueado).

Fluxo de trabalho

1. Identificar a intenção do usuário

Antes de chamar o CLI, entenda o que o usuário quer fazer com a transcrição:

• Transcrição completa: mostrar o texto com timestamps, fiel ao vídeo
• Resumo: síntese estruturada do conteúdo
• Pontos principais / bullet points: lista dos tópicos abordados
• Responder perguntas: buscar informação específica dentro do conteúdo
• Análise: extrair insights, opiniões, dados mencionados

Se não estiver claro, assuma que o usuário quer uma transcrição formatada com resumo.

2. Definir preferências de idioma

• Se o usuário pediu em português: --preferredLanguages "pt-BR,pt,en"
• Se o usuário pediu em inglês: --preferredLanguages "en,pt-BR,pt"
• Se não foi especificado: use "pt-BR,pt,en" como padrão

3. Executar o CLI e tratar o resultado

Execute o comando via bash e faça JSON.parse do stdout:

• Se null: informe que o vídeo não tem legendas disponíveis
• Se array vazio: trate igual ao null
• Se bem-sucedido: processe conforme o modo solicitado

4. Converter timestamps

Converta startInMs para o formato legível mm:ss (ou h:mm:ss para vídeos longos):

startInMs / 1000 = segundos totais
h = Math.floor(segundos / 3600)
m = Math.floor((segundos % 3600) / 60)
s = segundos % 60

Use h:mm:ss somente quando o vídeo tiver mais de 1 hora.

Formatos de saída

Transcrição completa

## Transcrição — [Título inferido ou "Vídeo"]

[0:00] Texto do segmento aqui
[0:05] Próximo segmento
[1:23] Segmento com mais de um minuto
...

Agrupe segmentos consecutivos curtos em blocos de ~5-10 segundos para melhor legibilidade. Não liste cada segmento individualmente se eles tiverem menos de 3 palavras.

Resumo

## Resumo — [Assunto do vídeo]

**Sobre o vídeo:** [1-2 frases descrevendo o tema central]

**Pontos principais:**
- ...
- ...

**Conclusão:** [O que o vídeo conclui ou recomenda]

Pontos principais

Lista de bullets diretos, sem introduções longas. Cada ponto deve ser autoexplicativo.

Resposta a perguntas

Busque nas transcrições os trechos relevantes, cite o timestamp, e responda diretamente. Se a informação não estiver no vídeo, diga claramente.

Boas práticas

• Seja fiel ao conteúdo: não invente informações que não estão na transcrição
• Cite timestamps quando responder perguntas específicas — ajuda o usuário a verificar
• Vídeos longos: para vídeos com mais de 30 minutos, ofereça um resumo mesmo se o usuário pediu transcrição completa, e pergunte se quer ver tudo
• Qualidade da transcrição: legendas automáticas (ASR) podem conter erros — mencione isso se perceber que o texto está confuso
• Idioma do output: responda no mesmo idioma que o usuário usou na pergunta, independentemente do idioma da transcrição
• Tratamento de erro: se o CLI falhar (retornar null), verifique se a URL é válida e se o vídeo tem legendas ativadas antes de reportar o problema ao usuário