adicionar-midia

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

1. Lê a nota-alvo (frontmatter + corpo).
2. Extrai: tema principal, conceitos-chave, fase:, domínio.
3. 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:

# 1. Listar legendas disponíveis:
uvx yt-dlp --list-subs --skip-download "https://youtube.com/watch?v=<id>"

# 2a. Legenda manual PT-BR (preferido):
uvx yt-dlp --write-sub --sub-lang pt-BR --sub-format vtt \
  --skip-download -o "/tmp/addmidia-%(id)s.%(ext)s" "<url>"

# 2b. Fallback — legenda automática PT-BR:
uvx yt-dlp --write-auto-sub --sub-lang pt-BR --sub-format vtt \
  --skip-download -o "/tmp/addmidia-%(id)s.%(ext)s" "<url>"

# 2c. Fallback final — EN (manual > automática):
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