Assistir a um vídeo — compreensão, não ingestão
Alguém compartilha um vídeo e pergunta sobre ele. Dois hooks tornam isso possível, e nenhum deles é detectável por conta própria — hooks não têm correspondência semântica, então uma sessão solicitada a "assistir isso" não encontra nada e improvisa. Essa lacuna é a razão de existir desta skill.
O limite — leia isto primeiro
Esta skill ASSISTE. Ela não ARQUIVA. Sua saída é a compreensão mantida na sessão, não um artefato do vault. Nenhuma nota, nenhum frontmatter, nenhum cross-link, nenhuma atualização de
_index, nenhum roteamento de itens de ação. Arquivos de trabalho vão para um caminho temporário (/tmp), nunca paravault/.
/aios:ingesté o pipeline de arquivamento — ele existe justamente para que transformar uma fonte em uma nota permanente e interligada do vault seja um ato deliberado com convenções. Se o operador quiser isso, passe a bola ("quer que eu/aios:ingestisso para que vá parareflections/ingests/com os cross-links?") — não implemente pela metade aqui. Dois caminhos, um limite, sem sobreposição.
Portanto, a forma de uma execução é: traga para o contexto → faça o que foi solicitado → ofereça, não presuma. Se a solicitação foi aberta ("assista isso" sem pergunta), assista, depois diga o que é em duas ou três linhas e pergunte o que eles querem disso. Não fabrique uma entrega que ninguém pediu.
Qual ferramenta — a decisão real
| A fonte | Use | Por quê |
|---|---|---|
| Documento (PDF, docx, apresentação, planilha) | MarkItDown ou as document-skills | Não é função desta skill; esses já têm correspondência semântica |
| Áudio/vídeo longo, áudio é suficiente | hooks/transcribe.py | MarkItDown envia áudio de uma só vez para o Google Web Speech — bom para uma frase, inútil para uma entrevista de 49 minutos |
| YouTube, áudio é suficiente | Legendas do MarkItDown primeiro | Muito mais rápido que transcrever; recorrer a transcribe.py quando as legendas estiverem ausentes ou ruins |
| A TELA carrega sinal | hooks/video-watch.py sobre a transcrição | Uma transcrição descarta cada quadro: slides, código, diagramas, terminal, gráficos, texto na tela |
A tela carrega sinal quando a fonte é uma palestra com slides, um screencast, um passo a passo de código, uma demonstração de ferramenta, uma aula com diagramas, ou qualquer coisa onde "como você pode ver aqui" o deixaria cego. Em caso de dúvida, pergunte — a passagem visual custa tempo real.
Os comandos
# espinha dorsal da transcrição (no dispositivo: ffmpeg → mlx-whisper large-v3-turbo, duração arbitrária)
python3 ~/aios/hooks/transcribe.py <arquivo-ou-URL> /tmp/watch-transcript.txt
# canal visual, sobreposto à transcrição — NUNCA no lugar dela
python3 ~/aios/hooks/video-watch.py <arquivo-ou-URL> \
--transcript /tmp/watch-transcript.txt --reader ocr --code
A escolha do leitor é a única decisão de flag real:
--reader ocr— texto exato na tela via Apple Vision. Padrão para slides, código, terminais, qualquer coisa que precise citar exatamente. Adicione--codequando os quadros contiverem código.--reader vlm— Visão Claude descreve cada quadro. Para diagramas, gráficos, arquitetura, UI — estrutura em vez de texto literal.--reader both— quando você precisa das palavras exatas e do que a imagem significa. Aproximadamente dobra o custo por quadro.
Todo o resto (--scene-threshold, --max-frames, --sample-every, --max-width, --phash-threshold) tem um padrão sensato. Mexa neles apenas quando a primeira passagem estiver visivelmente muito esparsa ou muito ruidosa; --help os lista.
Realidade da plataforma — informe, não tente
Ambos os hooks são macOS / Apple Silicon (mlx-whisper, Apple Vision via hooks/ocr-image.swift). No Linux ou Windows, avise e recorra ao MarkItDown, que lida com legendas do YouTube e áudio curto entre plataformas. Não deixe um operador ver um comando falhar para aprender isso.
Estabeleça expectativas antes de queimar tempo
Transcrever uma gravação longa e ler seus quadros leva minutos, não segundos — uma palestra de 45 minutos com passagem visual é a coisa mais pesada desta skill. Diga a estimativa antecipadamente e confirme, especialmente para a passagem visual. Duas manobras baratas que geralmente superam a força bruta:
- Transcrição primeiro, sempre. É a espinha dorsal semântica, é mais rápida e muitas vezes responde a pergunta diretamente — nesse ponto, a passagem visual é desnecessária.
- Se a solicitação for restrita ("ela menciona preços?"), pesquise na transcrição em vez de ler tudo de novo.
Modos de falha que valem a pena conhecer
- Uma transcrição não é o vídeo. Se o operador perguntar sobre algo mostrado, uma transcrição limpa que nunca menciona isso não é evidência de ausência — é o instrumento errado. Execute a passagem visual ou diga que ainda não pode responder.
- Legendas do YouTube podem ser geradas automaticamente e estar erradas (nomes, jargões, números). Se uma citação for importante, verifique com
transcribe.pyantes de atribuí-la. - Não cite o que você não leu. Os quadros são amostrados na mudança de cena e desduplicados, então a passagem visual é uma amostra, não um registro completo. Se uma afirmação se basear em um quadro, diga de qual timestamp ele veio.
- Arquivos temporários são temporários. Limpe
/tmp/watch-*quando terminar, ou diga onde os deixou. Nunca os escreva emvault/.
Passando a bola
Quando o material se revelar digno de ser mantido:
- Arquive-o corretamente →
/aios:ingest(vai parareflections/ingests/, nomenclatura{fonte}-{slug}, frontmatter, cross-links, itens de ação roteados para os to-dos do projeto). - Isso mudou o estado de um projeto → informe e ofereça-se para atualizar a nota do projeto.
- Isso produziu um insight duradouro → isso pertence ao vault pelo caminho normal de encerramento de sessão, não como um efeito colateral de assistir algo.
Assistir é barato e repetível. Arquivar é uma decisão. Mantenha-os separados.