# Habilidade do Agente de Transcrição do YouTube

> Baixe transcrições, legendas e imagens de capa de vídeos do YouTube por URL ou ID do vídeo. Suporta vários idiomas, tradução, capítulos e identificação de orador para melhorar a acessibilidade do conteúdo. Comece gratuitamente em segundos.

- Canonical: https://nanoskill.ai/pt/skills/youtube-transcript
- Markdown: https://nanoskill.ai/pt/skills/youtube-transcript.md
- Author: JimLiu
- Published: 2026-06-03T05:58:31.787Z
- Updated: 2026-07-15T13:36:15.347Z
- Language: pt
- Source type: github
- Popularity signal: 1040

## Sources

- https://github.com/JimLiu/baoyu-skills

## Install

```shell
npx skills add https://github.com/JimLiu/baoyu-skills/tree/main/skills/baoyu-youtube-transcript
```

## About

A Habilidade de Download de Transcrição do YouTube fornece uma solução robusta para extrair informações abrangentes de vídeos do YouTube. Esta habilidade permite que os usuários baixem facilmente transcrições completas do YouTube, legendas e até imagens de capa, simplesmente fornecendo um URL ou ID do vídeo. Foi projetada para criadores de conteúdo, pesquisadores e qualquer pessoa que precise converter conteúdo falado em texto, oferecendo recursos como suporte a vários idiomas, capacidades de tradução e opções avançadas de estruturação.

Aproveitando o acesso direto à API InnerTube do YouTube e um fallback inteligente para o \`yt-dlp\`, a habilidade garante uma recuperação de dados confiável e eficiente sem a necessidade de chaves de API pessoais. Oferece formatos de saída flexíveis, incluindo Markdown para análise detalhada com marcadores de tempo e capítulos, e SRT para integração padrão de legendas. Além disso, suporta segmentação de capítulos a partir de descrições de vídeos e fornece um fluxo de trabalho para identificação de orador com IA, entregando texto altamente organizado e com atribuição.

Com cache inteligente, a habilidade minimiza solicitações de rede redundantes, tornando as operações subsequentes no mesmo vídeo excepcionalmente rápidas. Quer você precise analisar o conteúdo do vídeo, criar legendas acessíveis, traduzir material para um público global ou simplesmente extrair metadados e miniaturas de vídeos, esta habilidade simplifica o processo, fornecendo uma ferramenta poderosa para gerenciamento de conteúdo do YouTube.

## Key features

- **Acesso Direto ao YouTube**: Acessa a API InnerTube do YouTube diretamente para uma rápida obtenção de transcrições, recorrendo automaticamente ao \`yt-dlp\` se a API direta estiver bloqueada, garantindo acesso confiável sem chaves de API.
- **Suporte a Vários Idiomas e Tradução**: Especifique idiomas preferidos para as transcrições e traduza-as para um idioma alvo, tornando o conteúdo acessível a um público global.
- **Segmentação de Capítulos e Identificação de Locutores**: Segmenta automaticamente as transcrições por capítulos do vídeo e oferece suporte ao pós-processamento por IA para identificação de locutores, fornecendo texto estruturado e atribuído.
- **Formatos de Saída Flexíveis**: Gera transcrições em Markdown com marcas de tempo ou arquivos de legenda SRT, adequados para várias finalidades, desde análise de conteúdo até players de vídeo.
- **Cache Inteligente para Eficiência**: Armazena em cache dados brutos do vídeo, metadados e transcrições segmentadas, permitindo uma rápida reformatação e reduzindo chamadas de rede em solicitações subsequentes para o mesmo vídeo.

## Use cases

- **Gerar Transcrições do YouTube para Análise de Conteúdo**: Criadores de conteúdo e pesquisadores podem obter rapidamente transcrições completas do YouTube, incluindo marcas de tempo e marcadores de capítulos, para analisar o conteúdo do vídeo, extrair informações-chave ou transformar o conteúdo falado em artigos de texto.
- **Criar Arquivos de Legenda para Acessibilidade**: Editores de vídeo e especialistas em acessibilidade podem gerar arquivos de legenda SRT de vídeos do YouTube, garantindo que o conteúdo seja acessível para públicos com deficiência auditiva ou aqueles que preferem consumir conteúdo silenciosamente.
- **Traduzir Conteúdo de Vídeo para Alcance Global**: Profissionais de marketing e educadores podem traduzir transcrições do YouTube para vários idiomas, ampliando o alcance de seu conteúdo de vídeo para falantes não nativos e melhorando o engajamento global.
- **Extrair Metadados e Imagens de Capa**: Os usuários podem extrair facilmente metadados de vídeo e imagens de capa de alta qualidade, úteis para catalogação, promoção em mídias sociais ou criação de recursos visuais relacionados ao conteúdo do vídeo.

## Result preview

Explore um relatório profissional de análise de vídeo alimentado por esta Habilidade.

![A presentation cover slide featuring a TED Talk analysis titled 'This Is How Kids Should Be Learning with AI'. The slide uses a bold red background with large white headline text centered prominently across the page. Beneath the title, the speaker and event are identified as 'Priya Lakhani | TEDNext 2025', accompanied by the subtitle 'TED Talk Analysis & Knowledge Report'. The lower portion of the slide contains a thumbnail image from the TED presentation showing the speaker on stage alongside the text 'AI Isn't a Shortcut to Learning'. A teal horizontal accent bar runs along the bottom edge, creating visual contrast. The overall design resembles a professional report or presentation cover summarizing key insights from a TED Talk about artificial intelligence and education.](https://file.nanoskill.ai/youtube-transcript-outcome1.png)

![A report page titled '\[ Executive Summary \]' from a TED Talk analysis on artificial intelligence and education. The page summarizes key arguments presented by education entrepreneur Priya Lakhani at TEDNext 2025, discussing the impact of AI in classrooms, the risks of students using AI to avoid learning, and the importance of productive struggle in effective education. Several paragraphs explain how neuroscience-informed AI systems can support deeper learning when designed to challenge rather than replace student effort. A section titled 'Key Statistics at a Glance' highlights major findings using four large color-coded statistic cards. The statistics include 20% of UK students leaving secondary school without adequate reading and writing skills, 74% of teachers considering leaving the profession within three years due to workload, one in five students using AI to complete all homework assignments, and over 40 billion data points collected on how children learn. The layout uses a clean report style with a red section header, structured text blocks, and colorful infographic-style data highlights to emphasize key educational challenges and opportunities.](https://file.nanoskill.ai/youtube-transcript-outcome2.png)

![A report page titled '\[ The Four Pillars of Learning \]' that presents four evidence-based learning principles supported by cognitive science and educational research. The page is organized into four color-coded sections: Retrieval Practice, Spacing, Generation, and Reflection. Each section includes a concise explanation of the learning principle and a highlighted 'Classroom Applications' box containing practical implementation examples. Retrieval Practice emphasizes recalling information from memory through activities such as flashcards, self-testing, and closed-book quizzes. Spacing focuses on distributing learning over time using spaced repetition and interleaved study sessions. Generation encourages learners to produce answers themselves through prediction, fill-in-the-blank exercises, and open-ended questioning. Reflection highlights structured self-assessment and feedback processes that help students evaluate progress, identify learning goals, and address knowledge gaps. The page uses a clean educational report layout with colored headers, explanatory text, and application callout boxes to summarize effective learning strategies for classrooms and AI-supported education.](https://file.nanoskill.ai/youtube-transcript-outcome3.png)

![A report page from a TED Talk analysis featuring two major sections: 'Neuroscience: The London Taxi Study' and 'AI in Education: Well-Designed vs. Poorly Used.' The first section explains a neuroscience study of London black cab drivers who memorize thousands of city streets to pass 'The Knowledge' exam. It describes how brain scans revealed that experienced drivers developed a larger hippocampus, demonstrating that sustained mental effort and navigation challenges can physically strengthen the brain. A highlighted key insight box emphasizes that mental effort is essential for durable learning, expertise development, and human creativity rather than being a flaw in the learning process. The second section presents a side-by-side comparison of educational AI usage. The left panel, labeled 'AI Well-Designed,' lists benefits such as identifying learning patterns, predicting forgetting, encouraging answer generation, providing targeted feedback, personalizing instruction, supporting teachers, and reducing workload. The right panel, labeled 'AI Poorly Used,' outlines risks including students using AI to complete all work, avoiding genuine learning, replacing thinking with shortcuts, creating false confidence, confusing fluency with understanding, and reducing productive struggle. The layout uses contrasting green and red comparison panels, educational report styling, and structured visual hierarchy to highlight the difference between AI that supports learning and AI that undermines it.](https://file.nanoskill.ai/youtube-transcript-outcome4.png)

## Result walkthrough

### Instalar

Adicione a Habilidade de Agente de Transcrição do YouTube ao seu agente de IA.

![A screenshot showing the installation process of the 'baoyu-youtube-transcript' AI agent skill from a GitHub repository using an NPX command. At the top, a blue command banner displays the installation command for adding the skill from the GitHub repository. Below, a conversational interface explains the installation workflow, including handling an interactive installation prompt, detecting that the process did not complete automatically, rerunning the command with a '-y' flag to bypass prompts, and explicitly targeting the Hermes Agent environment. The log then describes creating a symbolic link from the agent skills directory to the Hermes skills directory so the skill can be recognized by the Hermes Agent. A final confirmation states that the 'baoyu-youtube-transcript' skill was successfully installed, linked, and is available for use through a skill invocation command. The interface uses a clean chat-style layout with gray response panels, dark blue command highlighting, and monospaced code snippets for file paths and terminal commands.](https://file.nanoskill.ai/youtube-transcript-install.png)

### Fornecer Conteúdo

Compartilhe um link do YouTube e especifique o formato de saída desejado.

![A screenshot showing a prompt and response workflow for a YouTube transcript analysis skill. The top section contains a dark blue prompt panel describing an AI-powered content research and knowledge extraction system designed to analyze YouTube videos and transform them into structured knowledge assets. The prompt outlines requirements such as extracting complete transcripts, metadata, chapter structures, timestamps, speaker distinctions, key topics, major insights, statistics, examples, and actionable takeaways. It also lists supported output formats including executive summaries, study notes, blog articles, social media content, newsletter drafts, and research reports. Additional instructions emphasize transcript quality evaluation, improved readability, information hierarchy, redundancy removal, and generating a polished final deliverable. The requested output is a visually engaging PDF report with chapter navigation, highlighted takeaways, and presentation-ready layouts. Beneath the prompt, a gray response panel shows the AI acknowledging that the skill has been loaded successfully but explaining that a YouTube URL is still required before transcript extraction and report generation can begin. The interface uses a clean chat-style layout with large rounded panels, white text on a dark blue background, and structured instructional formatting.](https://file.nanoskill.ai/youtube-transcript-task.png)

### Extrair Insights

Gerar transcrições estruturadas, resumos, principais conclusões e conteúdo reutilizável.

![A presentation cover slide for a TED Talk analysis and knowledge report. The slide features a bold red background with a teal accent bar running along the bottom edge. Centered at the top is the large white title 'This Is How Kids Should Be Learning with AI.' Below the title, the speaker attribution reads 'Priya Lakhani | TEDNext 2025,' followed by the subtitle 'TED Talk Analysis & Knowledge Report' in italicized white text. In the center of the slide is a thumbnail image from the TED Talk showing Priya Lakhani on stage. The thumbnail includes the prominent message 'AI Isn't a Shortcut to Learning' alongside the TED logo. The overall design resembles a professional research report cover, using strong typography, high contrast colors, and a clean layout to introduce an educational analysis focused on artificial intelligence, learning science, and the future of education.](https://file.nanoskill.ai/youtube-transcript-outcome.png)

## Skill definition

# Transcrição do YouTube

Baixa transcrições (legendas/closed captions) de vídeos do YouTube. Funciona tanto com transcrições criadas manualmente quanto com as geradas automaticamente. Não requer chave de API ou navegador — usa a API InnerTube do YouTube diretamente e recorre automaticamente ao `yt-dlp` quando o YouTube bloqueia o caminho direto da API.

Busca metadados do vídeo e imagem de capa na primeira execução, armazena em cache os dados brutos para uma reformatação rápida.

## Diretório do Script

Scripts no subdiretório `scripts/`. `{baseDir}` = caminho do diretório deste SKILL.md. Resolver o runtime `${BUN_X}`: se `bun` estiver instalado → `bun`; se `npx` estiver disponível → `npx -y bun`; caso contrário, sugerir a instalação do bun. Substituir `{baseDir}` e `${BUN_X}` pelos valores reais.

| Script | Finalidade |
|--------|------------|
| `scripts/main.ts` | CLI para download de transcrição |

## Uso

```bash
# Padrão: markdown com carimbos de tempo (Inglês)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Especificar idiomas (ordem de prioridade)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# Sem carimbos de tempo
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# Com segmentação por capítulos
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# Com identificação de locutores (requer pós-processamento com IA)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# Arquivo de legenda SRT
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Traduzir transcrição
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# Listar transcrições disponíveis
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Forçar nova busca (ignorar cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh
```

## Opções

| Opção | Descrição | Padrão |
|--------|-------------|---------|
| `<url-or-id>` | URL do YouTube ou ID do vídeo (vários permitidos) | Obrigatório |
| `--languages <codes>` | Códigos de idioma, separados por vírgula, em ordem de prioridade | `en` |
| `--format <fmt>` | Formato de saída: `text`, `srt` | `text` |
| `--translate <code>` | Traduzir para o código de idioma especificado | |
| `--list` | Listar transcrições disponíveis em vez de buscar | |
| `--timestamps` | Incluir carimbos de tempo `[HH:MM:SS → HH:MM:SS]` por parágrafo | ativado |
| `--no-timestamps` | Desativar carimbos de tempo | |
| `--chapters` | Segmentação por capítulos a partir da descrição do vídeo | |
| `--speakers` | Transcrição bruta com metadados para identificação de locutores | |
| `--exclude-generated` | Pular transcrições geradas automaticamente | |
| `--exclude-manually-created` | Pular transcrições criadas manualmente | |
| `--refresh` | Forçar nova busca, ignorar dados em cache | |
| `-o, --output <path>` | Salvar em caminho de arquivo específico | gerado automaticamente |
| `--output-dir <dir>` | Diretório de saída base | `youtube-transcript` |

## Variáveis de Ambiente Opcionais

| Variável | Descrição |
|----------|-----------|
| `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` | Passado para `yt-dlp --cookies-from-browser` durante o fallback, ex: `chrome`, `safari`, `firefox`, ou `chrome:Profile 1` |

## Formatos de Entrada

Aceita qualquer um destes como entrada de vídeo:
- URL completa: `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
- URL curta: `https://youtu.be/dQw4w9WgXcQ`
- URL de incorporação: `https://www.youtube.com/embed/dQw4w9WgXcQ`
- URL do Shorts: `https://www.youtube.com/shorts/dQw4w9WgXcQ`
- ID do vídeo: `dQw4w9WgXcQ`

## Formatos de Saída

| Formato | Extensão | Descrição |
|--------|-----------|-------------|
| `text` | `.md` | Markdown com frontmatter (incl. `description`), cabeçalho de título, resumo, TOC/capa/carimbos de tempo/capítulos/locutores opcionais |
| `srt` | `.srt` | Formato de legenda SubRip para players de vídeo |

## Diretório de Saída

```
youtube-transcript/
├── .index.json                          # Mapeamento ID do vídeo → caminho do diretório (para consulta de cache)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Metadados do vídeo (título, canal, descrição, duração, capítulos, etc.)
    ├── transcript-raw.json              # Trechos brutos da transcrição da API do YouTube (em cache)
    ├── transcript-sentences.json        # Transcrição segmentada por frases (dividida por pontuação, mesclada entre trechos)
    ├── imgs/
    │   └── cover.jpg                    # Miniatura do vídeo
    ├── transcript.md                    # Transcrição em Markdown (gerada a partir das frases)
    └── transcript.srt                   # Legenda SRT (gerada a partir dos trechos brutos, se --format srt)
```

- `{channel-slug}`: Nome do canal em kebab-case
- `{title-full-slug}`: Título completo do vídeo em kebab-case

O modo `--list` gera saída apenas para stdout (nenhum arquivo é salvo).

## Cache

Na primeira execução, o script salva:
- `meta.json` — metadados do vídeo, capítulos, caminho da imagem de capa, informações de idioma
- `transcript-raw.json` — trechos brutos da transcrição da API do YouTube (`{ text, start, duration }[]`)
- `transcript-sentences.json` — transcrição segmentada por frases (`{ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]`), dividida por pontuação de final de frase (`.?!…。？！` etc.), carimbos de tempo alocados proporcionalmente pelo comprimento dos caracteres, mesclagem de texto com reconhecimento CJK
- `imgs/cover.jpg` — miniatura do vídeo

Execuções subsequentes para o mesmo vídeo usam dados em cache (sem chamadas de rede). Use `--refresh` para forçar uma nova busca. Se um idioma diferente for solicitado, o cache é automaticamente atualizado.

Quando o YouTube retorna respostas anti-bot / bloqueadas no caminho direto do InnerTube, o script tenta novamente com identidades de cliente alternativas e depois recorre ao `yt-dlp` se disponível. Se o fallback for necessário, mas o `yt-dlp` não estiver disponível, o agente deve decidir como disponibilizar o `yt-dlp` e continuar, em vez de empurrar a decisão de instalação para o usuário.

A saída SRT (`--format srt`) é gerada a partir de `transcript-raw.json`. A saída de texto/markdown usa `transcript-sentences.json` para limites naturais de frases.

## Fluxo de Trabalho

Quando o usuário fornece uma URL do YouTube e deseja a transcrição:
1. Execute com `--list` primeiro se o usuário não especificou um idioma, para mostrar as opções disponíveis
2. **Sempre coloque a URL entre aspas simples** ao executar o script — o zsh trata `?` como um curinga glob, então uma URL do YouTube sem aspas causa "no matches found": use `'https://www.youtube.com/watch?v=ID'`
3. Padrão: execute com `--chapters --speakers` para a saída mais completa (capítulos + identificação de locutores)
3. O script salva automaticamente os dados em cache + arquivo de saída e imprime o caminho do arquivo
4. Para o modo `--speakers`: depois que o script salva o arquivo bruto, siga o fluxo de trabalho de identificação de locutores abaixo para pós-processar com rótulos de locutores

Quando o usuário deseja apenas uma imagem de capa ou metadados, executar o script com qualquer opção também colocará em cache `meta.json` e `imgs/cover.jpg`.

Ao reformatar o mesmo vídeo (ex: primeiro texto depois SRT), os dados em cache são reutilizados — não é necessário buscar novamente.

## Fluxo de Trabalho de Capítulos e Locutores

### Capítulos (`--chapters`)

O script analisa os carimbos de tempo dos capítulos a partir da descrição do vídeo (ex: `0:00 Introdução`), segmenta a transcrição pelos limites dos capítulos, agrupa os trechos em parágrafos legíveis e salva como `.md` com um Índice. Nenhum processamento adicional é necessário.

Se não existirem carimbos de tempo de capítulos na descrição, a transcrição é gerada como parágrafos agrupados sem cabeçalhos de capítulo.

### Identificação de Locutores (`--speakers`)

A identificação de locutores requer processamento de IA. O script gera um arquivo `.md` bruto contendo:
- Frontmatter YAML com metadados do vídeo (título, canal, data, capa, descrição, idioma)
- Descrição do vídeo (para extração de nomes dos locutores)
- Lista de capítulos da descrição (se disponível)
- Transcrição bruta em formato SRT (carimbos de tempo de início/fim pré-computados, eficiente em tokens)

Depois que o script salva o arquivo bruto, inicie um subagente (use um modelo mais barato como o Sonnet para eficiência de custos) para processar a identificação de locutores:
1. Leia o arquivo `.md` salvo
2. Leia o modelo de prompt em `{baseDir}/prompts/speaker-transcript.md`
3. Processe a transcrição bruta seguindo o prompt:
   - Identifique os locutores usando os metadados do vídeo (título → convidado, canal → apresentador, descrição → nomes)
   - Detecte mudanças de locutor a partir do fluxo da conversa, padrões de pergunta-resposta e pistas contextuais
   - Segmente em capítulos (use os capítulos da descrição se disponíveis, caso contrário crie a partir de mudanças de tópico)
   - Formate com rótulos `**Nome do Locutor:**`, agrupamento de parágrafos (2-4 frases) e carimbos de tempo `[HH:MM:SS → HH:MM:SS]`
4. Sobrescreva o arquivo `.md` com a transcrição processada (mantenha o frontmatter YAML)

Quando `--speakers` é usado, `--chapters` está implícito — a saída processada sempre inclui segmentação por capítulos.

## Casos de Erro

| Erro | Significado |
|-------|---------|
| Transcrições desativadas | O vídeo não possui legendas |
| Nenhuma transcrição encontrada | O idioma solicitado não está disponível |
| Vídeo indisponível | Vídeo excluído, privado ou com restrição regional |
| IP bloqueado | Muitas solicitações, tente novamente mais tarde |
| Restrição de idade | O vídeo requer login para verificação de idade |
| bot detectado | O script tenta novamente com clientes alternativos e depois `yt-dlp`; se a ferramenta de fallback estiver ausente, o agente deve resolver isso por conta própria, caso contrário, se ainda falhar, tente `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari` (ou seu navegador) |

## FAQ

### O que é o Recurso de Download de Transcrições do YouTube?

O Recurso de Download de Transcrições do YouTube é uma ferramenta que permite baixar transcrições, legendas e imagens de capa de vídeos do YouTube usando apenas o URL ou o ID do vídeo. Ele suporta vários recursos, como recuperação em vários idiomas, tradução, segmentação de capítulos e identificação de locutores.

### Como este recurso obtém transcrições do YouTube sem uma chave de API?

O recurso usa diretamente a API InnerTube do YouTube para buscar transcrições. Se o acesso direto estiver bloqueado, ele automaticamente recorre ao \`yt-dlp\` para garantir a obtenção confiável de transcrições, sem exigir uma chave de API separada.

### Posso obter transcrições em outros idiomas além do inglês?

Sim, você pode especificar uma lista de códigos de idioma separados por vírgula usando a opção \`--languages\`. O recurso tentará buscar as transcrições na ordem de prioridade especificada. Você também pode traduzir a transcrição para outro idioma usando a opção \`--translate\`.

### Ele suporta identificação de locutores e segmentação de capítulos?

Sim, o recurso suporta segmentação de capítulos a partir das descrições do vídeo usando a opção \`--chapters\`. Para identificação de locutores, você pode usar a opção \`--speakers\`, que gera um arquivo bruto para pós-processamento por IA e rotulagem dos locutores.

### Quais formatos de saída estão disponíveis para a transcrição do YouTube?

Você pode gerar a transcrição no formato Markdown (\`.md\`), que inclui marcas de tempo, capítulos e dados opcionais de locutores, ou como um arquivo de legenda SRT (\`.srt\`), compatível com a maioria dos players de vídeo.

### Existe um mecanismo de cache e como ele funciona?

Sim, o recurso armazena em cache metadados do vídeo, dados brutos da transcrição e frases segmentadas. Execuções subsequentes para o mesmo vídeo usarão esses dados em cache, acelerando o processamento. Você pode forçar uma nova busca com a opção \`--refresh\`.