video-to-deck

O que video-to-deck faz?

Crie uma apresentação a partir de um vídeo. Você (o modelo) é apenas texto — você não consegue ouvir áudio nem ver frames. Portanto, os scripts deste skill fazem a parte de ver e ouvir e fornecem a você um pacote de evidências textual (evidence.md). Sua tarefa é apenas síntese: leia as evidências e escreva uma boa apresentação. Não invente nada que as evidências não suportem.

A saída é Marp markdown (deck.md): um .md normal que você pode ler agora, e uma apresentação real (PPTX/PDF/HTML) através de um comando render.sh posteriormente.

$SKILL abaixo = o diretório deste skill (a pasta que contém este arquivo).

Procedimento

1. Configuração única (idempotente)

bash "$SKILL/scripts/setup.sh"

Instala faster-whisper (transcrição), tesseract (OCR) e — se npm estiver presente — marp-cli e mermaid-cli. Seguro reexecutar. ffmpeg já deve estar instalado.

2. Encontre os vídeos

bash "$SKILL/scripts/find_videos.sh" "<pasta>"        # um caminho por linha, recursivo

Para um único arquivo nomeado, pule esta etapa e use o caminho diretamente.

3. Construa o pacote de evidências para cada vídeo (um de cada vez)

bash "$SKILL/scripts/process_video.sh" "<video>" "<dir_saida>/<nome-base-video>"

Isso extrai o áudio → transcreve, amostra keyframes → aplica OCR no texto na tela e escreve <dir_saida>/<nome-base-video>/evidence.md (além de transcript.txt, segments.tsv, frames/, ocr.txt). Vídeos longos em CPU são lentos; defina WHISPER_MODEL=small para qualidade, ou use uma GPU CUDA para velocidade (detectado automaticamente; veja WHISPER_DEVICE em scripts/transcribe.py). Processe os vídeos sequencialmente, não em paralelo.

Passo de visão opcional (Qwen-VL). O OCR lê apenas texto. Para capturar também o que o texto não consegue — gráficos e suas tendências, diagramas, layout de UI, um gesto do apresentador — habilite um modelo de visão que legende cada keyframe mantido. Está desligado por padrão; ative-o definindo VISION_MODEL (e, se necessário, VISION_ENDPOINT) no ambiente do mesmo comando:

VISION_MODEL=qwen2.5-vl \
VISION_ENDPOINT=http://127.0.0.1:8081/v1/chat/completions \
  bash "$SKILL/scripts/process_video.sh" "<video>" "<dir_saida>/<nome-base-video>"

Quando ativado, evidence.md ganha uma seção "## Descrições visuais" junto com o OCR — use-a para slides de gráficos/diagramas. Qualquer endpoint de visão compatível com OpenAI funciona (llama-swap uma vez que um servidor local como llama.cpp/llama-swap ou Ollama, ou uma API hospedada; VISION_API_KEY se precisar de um token). Se o endpoint estiver inacessível, a execução continua apenas com OCR — nada quebra.

4. Escreva a apresentação

Leia todo o evidence.md. Copie "$SKILL/templates/deck.marp.md" para <dir_saida>/<nome-base-video>/deck.md e preencha. Regras:

• Mantenha o frontmatter marp: true — é isso que torna um conjunto de slides.
• Use a transcrição para o que foi dito; use o OCR / texto na tela para rótulos, números, títulos e códigos exatos exibidos nos slides; se houver uma seção "Descrições visuais" presente (o passo de visão foi ativado), use-a para gráficos/diagramas/UI que o OCR não consegue transmitir.
• Marque uma afirmação com seu momento quando útil: [00:04:12].
• Coloque o keyframe do slide no slide — este é o PADRÃO, não um enfeite opcional. Cada bloco ### [intervalo] frames/kf_####.jpg em ocr.txt nomeia o frame representativo para aquele slide; leve-o para o slide do deck que se tornou: ![](frames/kf_0007.jpg). O keyframe é a evidência do slide, ele mostra o diagrama/gráfico/UI que os bullets só podem descrever, e faz o deck espelhar a apresentação original. Omita-o apenas quando o slide for um slide de diagrama puro que você redesenhou em Mermaid, ou quando o frame não carrega sinal visual (um rosto falando, uma transição em branco). Quando dois slides do deck vêm de um slide fonte, use dois frames diferentes daquela execução do slide, em vez de repetir um.
• Inclua apenas o que as evidências suportam. Se a transcrição e o OCR estiverem vazios, diga que o vídeo não tinha conteúdo extraível, em vez de inventar uma apresentação.

Densidade — a apresentação deve CONSOLIDAR as evidências, não resumi-las. O fracasso mais comum é uma apresentação fina: 20 slides com bullets de quatro palavras que jogam fora a maior parte do que o vídeo realmente continha. O pacote de evidências é caro de construir; a apresentação é o que as pessoas leem.

• Um slide do deck por slide fonte. Cada bloco ### [intervalo] frames/… na seção OCR é um slide real do vídeo — essa lista é sua lista de verificação e aproximadamente sua contagem de slides. Não mescle três slides fonte em um único bullet. Uma palestra de 40 minutos normalmente tem 30-45 slides.
• Leve os detalhes para o slide. Cada número, métrica, limite, porcentagem, nome de produto, CRD, chave de configuração e rótulo presente nas evidências pertence ao slide em si. Se o slide fonte tinha seis bullets e quatro estatísticas, seu slide tem seis bullets e quatro estatísticas — não "precisão melhorada".
• Bullets são uma linha completa (~15-20 palavras), não quatro palavras. 5-8 por slide é normal. Resumido só é correto quando a fonte era resumida.
• Use uma tabela sempre que a fonte for tabular — matrizes de roteamento, grades de benchmark, definições de nível, regras de prioridade. Reproduza cada linha e coluna, não uma amostra.
• Notas do apresentador são aditivas, para o que foi dito que não está no slide: ressalvas, histórias de guerra, o "porquê", detalhes de Q&A. Elas não são o lugar para esconder conteúdo que pertence ao slide.
• Verificação de cobertura antes de terminar. Percorra os blocos ### [..] em ocr.txt em ordem e confirme que cada um está representado. Se você pulou um bloco, ou era uma duplicata/animação do slide anterior ou um frame de demonstração — seja capaz de dizer qual.

5. Passo de diagramas (a verificação "isso pode ser um diagrama?")

Para cada tópico, pergunte: isso é estrutural (componentes + conexões, interações entre atores, um processo/fluxo, estados + transições, entidades + relações)? Se sim, desenhe como um Mermaid (padrão) ou PlantUML em seu próprio slide em vez de bullets. Consulte "$SKILL/references/diagrams-cheatsheet.md" para a tabela de decisão conteúdo→tipo e esqueletos copiáveis. Não force um diagrama onde o conteúdo é apenas narrativo.

6. (Opcional) Exporte a apresentação real

bash "$SKILL/scripts/render.sh" "<dir_saida>/<nome-base-video>/deck.md" pptx   # ou pdf | html | all

Isso pré-renderiza blocos de diagrama para imagens e então produz o PPTX/PDF. Se marp/mermaid não estiverem instalados, a apresentação permanece como .md (ainda válida e visualizável).

Para uma árvore inteira de uma vez, adicione --pdf ao driver em lote (abaixo) em vez de chamar render.sh por apresentação.

Lote / pastas aninhadas

Para uma pasta inteira — especialmente uma árvore de curso aninhada — prefira scripts/drive_decks.sh <raiz>: ele itera em bash e gera um novo agente por vídeo (nunca sobrecarrega o contexto do modelo) e espelha as subpastas fonte na saída, de modo que a hierarquia pai→filho é preservada. scripts/rename_by_topic.sh <apresentacoes> então transforma cada folha em slug pelo seu tópico dentro de sua pasta de curso. Adicione --pdf para exportar cada apresentação para PDF quando a autoria terminar — o Mermaid é pré-renderizado para imagens, e a pasta folha é recolhida para que cada PDF caia em seu pai (<saida>/CursoA/licao/deck.md → <saida>/CursoA/licao.pdf), evitando uma subpasta por PDF. Para reconstruir a hierarquia de apresentações que foram produzidas planas por uma execução anterior, use scripts/regroup_by_source.sh <apresentacoes> — ele lê a linha Fonte: de cada evidence.md para colocar cada apresentação sob seu pai de curso (duplicatas quarentenadas em _duplicates/), então execute a renomeação. Veja README.md para o guia completo de lote.

Referências

• references/marp-cheatsheet.md — Sintaxe de slides Marp (separadores, imagens, notas, colunas).
• references/diagrams-cheatsheet.md — Quando desenhar um diagrama e a sintaxe para cada tipo.

Notas

• O OCR captura bem texto na tela para screencasts/vídeos de slides. Para filmagens de ação ao vivo, a transcrição carrega a maior parte do sinal — apoie-se nela e não faça afirmações exageradas sobre recursos visuais.
• Transcrição, OCR e renderização são sempre locais. Se a etapa de autoria sai da máquina depende inteiramente do agente para o qual você aponta --agent-cmd.
• O design é agnóstico a modelo: qualquer agente de texto que possa executar bash e ler arquivos pode usar este skill.