name: adicionar-midia
description: Micro-skill: pesquisa vídeos (YouTube) e podcasts (com transcrição disponível) relevantes para uma nota, baixa as legendas via uvx yt-dlp, analisa relevância e embute os melhores como callouts [!tip] na nota. Use quando o usuário pedir "adicionar vídeo", "adicionar mídia", "embutir vídeo", "buscar vídeo sobre X", "enriquecer com mídia", "podcast sobre X". Também invocada pela lente Mídia do /enriquecer-nota.
Skill: adicionar-midia
Pesquisa, analisa e embute vídeos do YouTube e podcasts (com transcrição) em notas do vault.
Cada mídia aprovada vira um callout > [!tip] com link + contexto de relevância.
Regra de ouro: nunca embutir sem ter lido a transcrição. Sem legenda = descarta.
Invocação
/adicionar-midia [path] [instrução]
- Sem
path: pergunta qual nota enriquecer.
- Com
path: usa o arquivo indicado (relativo à raiz do vault).
- Instrução complementar: tema específico, canais preferidos, idioma, tipo (vídeo|podcast).
Dependência: yt-dlp via uvx
Todos os downloads usam uvx yt-dlp (sem instalação global). Se uvx falhar, reporta o comando
exato e aborta sem editar a nota. Avisos de "No supported JavaScript runtime" e "impersonation"
são não-fatais — o download das legendas funciona mesmo assim.
Fase 1 — Perfil da nota
- Lê a nota-alvo (frontmatter + corpo).
- Extrai: tema principal, conceitos-chave,
fase:, domínio.
- Lista as mídias já embutidas na nota (callouts
[!tip] com links de vídeo/podcast) para evitar duplicar.
Fase 2 — Pesquisa de candidatos
Vídeos (YouTube)
Critérios de seleção (aplicar todos):
- Idioma: PT-BR prioritário; EN se referência canônica no domínio.
- Tipo: tutorial técnico, talk de conferência, explicação conceitual. Nunca: vlogs, anúncios, "top N coisas sem profundidade".
- Autores prioritários por domínio:
- IA/LLMs → Andrej Karpathy, François Chollet, DeepMind, Anthropic, OpenAI
- Web/Frontend → Fireship, Theo, Matt Pocock (TypeScript), Kent C. Dodds
- Java/Backend → Venkat Subramaniam, Josh Long, InfoQ, GOTO conferences
- Arquitetura → Martin Fowler, Sam Newman, Software Engineering Radio
- Sistemas → Brandon Gregg, Brendan Burns
- Duração: 5-60 min (curto demais = superficial; longo demais = difícil de ancorar).
Buscas WebSearch (2-3 queries dirigidas):
site:youtube.com "<tema principal>" <autor-prioritário>
"<conceito-chave>" tutorial conference talk youtube <ano>
"<conceito-chave>" explained youtube
Seleciona 3-5 candidatos com URL, título, canal e duração estimada.
Podcasts (EN com transcrição)
Critérios adicionais:
- Obrigatório: transcrição disponível no site do podcast ou no YouTube.
- Idioma: EN apenas (padrão de mercado para podcasts técnicos com transcrição).
- Fontes preferenciais: Lex Fridman Podcast, Practical AI, Software Engineering Daily, The TWIML AI Podcast, Acquired, CoRecursive.
- Como verificar transcrição: buscar
site:<podcast-url> transcript ou verificar se há vídeo no YouTube com legendas.
Apresenta lista de candidatos com tipo (vídeo/podcast) e fonte de transcrição antes de prosseguir.
Fase 3 — Download de legendas
Para cada candidato aprovado pelo usuário:
uvx yt-dlp --list-subs --skip-download "https://youtube.com/watch?v=<id>"
uvx yt-dlp --write-sub --sub-lang pt-BR --sub-format vtt \
--skip-download -o "/tmp/addmidia-%(id)s.%(ext)s" "<url>"
uvx yt-dlp --write-auto-sub --sub-lang pt-BR --sub-format vtt \
--skip-download -o "/tmp/addmidia-%(id)s.%(ext)s" "<url>"
uvx yt-dlp --write-sub --sub-lang en --sub-format vtt \
--skip-download -o "/tmp/addmidia-%(id)s.%(ext)s" "<url>"
Limpar VTT para leitura (remove marcações de tempo e tags):
grep -vE '^WEBVTT|^Kind:|^Language:|-->|^[[:space:]]*$|align:|position:' \
"/tmp/addmidia-<id>.<lang>.vtt" | sed -E 's/<[^>]*>//g' | awk '!seen[$0]++'
Para encontrar timestamps de trechos relevantes, consultar as linhas HH:MM:SS.mmm --> do .vtt
original. Formatar como [mm:ss] ou [h:mm:ss] se ≥1h.
Se nenhuma legenda disponível para o candidato → descarta e avisa o usuário.
Fase 4 — Análise de relevância
Para cada transcrição lida, avalia em 3 dimensões (0-10 cada):
| Dimensão | Critério |
|---|
| Alinhamento | A transcrição trata do conceito central da nota (não só tangencial)? |
| Profundidade | Acrescenta ângulo, exemplo ou mecanismo que a nota ainda não cobre? |
| Qualidade pedagógica | Clareza de explicação, exemplos concretos, sem jargão vazio? |
Trecho âncora: identifica o trecho mais relevante (timestamp + citação de 1-2 frases).
Filtro: descarta candidatos com Alinhamento <7. Apresenta shortlist com pontuação e justificativa:
CANDIDATOS APROVADOS:
📹 [Título do Vídeo] — Canal (~Xmin) — EN
Alinhamento: 9 | Profundidade: 8 | Pedagógico: 8
Trecho âncora [X:XX]: "<citação>"
→ Relevância: <por que acrescenta à nota em 1 linha>
🎙️ [Título do Episódio] — Podcast (~Xmin) — EN (transcrição no site)
Alinhamento: 8 | Profundidade: 7 | Pedagógico: 9
→ Relevância: <por que acrescenta em 1 linha>
DESCARTADOS:
✗ [Título] — Alinhamento: 5 — superficial demais para o tema
Fase 5 — Plano de inserção
Sugere onde inserir cada mídia na nota (seção de maior encaixe semântico):
PLANO — <título da nota>
📹 [<Título do Vídeo>](<url>) — <Canal> (~Xmin) — <idioma>
Inserir após §<Nome da Seção>
Relevância: <1 linha>
Trecho âncora [X:XX]: "<citação>"
🎙️ [<Título do Episódio>](<url>) — <Podcast> (~Xmin) — EN
Inserir após §<Nome da Seção>
Relevância: <1 linha>
[c] confirmar tudo [N] descartar item N [x] cancelar
Fase 6 — Inserção
Para cada mídia aprovada, insere o callout no local indicado:
Vídeo
> [!tip] Assista: <Título do Vídeo>
> **Canal:** <Nome> | **Duração:** ~Xmin | **Idioma:** PT-BR / EN
>
> <1-2 frases sobre o que o vídeo acrescenta que a nota não cobre — no registro Feynman.>
> Trecho de destaque [X:XX]: *"<citação do trecho âncora>"*
>
> 🎬 [Assistir no YouTube](<url>)
Podcast
> [!tip] Ouça: <Título do Episódio>
> **Podcast:** <Nome> | **Duração:** ~Xmin | **Idioma:** EN (transcrição disponível)
>
> <1-2 frases sobre o que o episódio acrescenta que a nota não cobre.>
>
> 🎙️ [Ouvir](<url>)
Após inserção: atualiza updated: no frontmatter. Descarta os .vtt de /tmp:
rm -f /tmp/addmidia-*.vtt
Convenções rígidas
- Legendas obrigatórias — nunca embutir vídeo sem ter lido a transcrição. Sem legenda = descarta.
- Podcast só com transcrição — verificar antes do download; sem transcrição = descarta.
- Máximo 2 mídias por nota — mais do que isso fragmenta o foco. Exceção: notas capstone (>600 linhas) podem ter até 3.
- Callout
[!tip] — padrão canônico para mídia. Nunca embutir só o link cru.
- Não duplicar — checar mídias já presentes antes de qualquer inserção.
- Fontes autoritativas prioritárias — Karpathy/3Blue1Brown/InfoQ/GOTO valem mais que tutoriais genéricos.
- Confirmar antes de editar — mostra plano; não grava sem aprovação.
Edge cases
| Caso | Comportamento |
|---|
| Nenhuma legenda disponível | Descarta candidato; avisa |
| Todos os candidatos com Alinhamento <7 | "Nenhum vídeo passou o critério de relevância"; encerra sem editar |
| Nota já tem ≥2 mídias | Avisa; pergunta se quer substituir ou adicionar mesmo assim |
uvx/yt-dlp falha | Reporta o comando exato; não escreve; aborta |
| Podcast sem transcrição disponível | Descarta; nunca embutir sem transcrição |
| URL inválida ou não-YouTube | Avisa; pede nova URL ou aborta |
