---
name: youtube-extract
category: dev-tools
description: "Extrai transcrições e metadados de vídeos, playlists e canais YouTube para o ficheiro de pesquisa Stack_Pesquisa_Videos.md. Usar quando 'youtube', 'vídeo', 'playlist', 'canal', 'transcrição', 'extrair vídeo', 'pesquisa vídeos'."
version: "1.0.0"
created: 2026-04-04
tools: [Bash]
---

# Skill: /youtube-extract

Extrai transcrições e metadados de vídeos, playlists e canais YouTube usando o script `youtube-pesquisa-videos.py`. Adiciona automaticamente ao ficheiro de pesquisa do StackDescomplicar.

---

## Ficheiros relevantes

| Ficheiro | Caminho |
|----------|---------|
| **Script** | `/media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py` |
| **Destino padrão** | `/media/ealmeida/Dados/Hub/04-Stack/Stack_Pesquisa_Videos.md` |

---

## Processo de execução

### 1. Identificar o pedido

Detectar na mensagem do utilizador:
- **URLs** — vídeos individuais, playlists (`?list=`), canais (`@canal`, `/c/`, `/channel/`)
- **Limite** — "primeiros 10", "máx 5", etc. → usar `--max N`
- **Destino** — ficheiro alternativo? → usar `--output caminho`
- **Modo** — adicionar ao ficheiro (`--append`) vs mostrar no terminal (sem flag)

### 2. Construir o comando

```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    URL1 URL2 ... \
    [--max N] \
    [--append] \
    [--output /caminho/alternativo.md] \
    [--file lista.txt]
```

### 3. Exemplos por tipo de URL

**Vídeo individual:**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtu.be/dQw4w9WgXcQ" --append
```

**Playlist completa:**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtube.com/playlist?list=PLxxx" --append
```

**Playlist com limite:**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtube.com/playlist?list=PLxxx" --max 10 --append
```

**Canal completo (máx. 20):**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtube.com/@NomeCanal" --max 20 --append
```

**Mix de URLs:**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtu.be/ID1" \
    "https://youtube.com/playlist?list=PLxxx" \
    --max 5 --append
```

**Ficheiro de lista:**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    --file /caminho/lista.txt --append
```

**Pré-visualizar sem gravar:**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtu.be/ID1"
```

---

## Comportamento padrão

| Situação | Acção |
|----------|-------|
| URL única de vídeo | Extrair e perguntar se adiciona ao ficheiro |
| Múltiplos vídeos | Extrair todos e adicionar com `--append` |
| Playlist/canal sem limite | Alertar o utilizador — perguntar limite antes de executar |
| Ficheiro de destino não especificado | Usar `Stack_Pesquisa_Videos.md` |

> **Aviso obrigatório para playlists/canais sem `--max`:** Informar o utilizador do número de vídeos antes de processar — canais podem ter centenas.

---

## Após a extracção

1. Informar quantos vídeos foram adicionados e os números `#N` atribuídos
2. Sugerir ao utilizador que complete os campos `*(a completar)*` no ficheiro
3. Se houver erros (transcrição indisponível), mencionar quais os vídeos afectados
4. Opcional: abrir o ficheiro no editor — `xdg-open "Stack_Pesquisa_Videos.md"`

---

## Pré-requisitos

- `yt-dlp` instalado: `pip install yt-dlp` ou `brew install yt-dlp`
- Python 3.8+
- Acesso à internet

Verificar disponibilidade:
```bash
yt-dlp --version && python3 --version
```

---

## Casos especiais

**ID curto do YouTube (11 chars):**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py dQw4w9WgXcQ --append
```

**Destino alternativo (outro projecto):**
```bash
python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \
    "https://youtu.be/ID1" \
    --output "/media/ealmeida/Dados/Hub/05-Projectos/MeuProjecto/videos.md" \
    --append
```

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"","issue":"","fix":"","source":"user|auto"}
```

*Adicionar nova linha após cada erro corrigido.*