¿Qué hace video-to-deck?
Crea una presentación a partir de un video. Tú (el modelo) eres solo texto — no puedes escuchar audio ni ver fotogramas. Por eso los scripts de esta habilidad hacen la visión y la audición y te entregan un paquete de evidencia de texto (evidence.md). Tu trabajo es solo síntesis: lee la evidencia y escribe una buena presentación. No inventes nada que la evidencia no respalde.
La salida es Marp markdown (deck.md): un .md normal que puedes leer ahora, y una presentación real (PPTX/PDF/HTML) mediante un comando render.sh posterior.
$SKILL a continuación = el directorio de esta habilidad (la carpeta que contiene este archivo).
Procedimiento
1. Configuración única (idempotente)
bash "$SKILL/scripts/setup.sh"
Instala faster-whisper (transcripción), tesseract (OCR) y, si npm está presente, marp-cli y mermaid-cli. Es seguro volver a ejecutarlo. ffmpeg debe estar instalado previamente.
2. Encontrar los videos
bash "$SKILL/scripts/find_videos.sh" "<carpeta>" # una ruta por línea, recursivo
Para un solo archivo nombrado, omite esto y usa la ruta directamente.
3. Construir el paquete de evidencia para cada video (uno a la vez)
bash "$SKILL/scripts/process_video.sh" "<video>" "<dir_salida>/<nombre-base-video>"
Esto extrae el audio → lo transcribe, muestrea fotogramas clave → aplica OCR al texto en pantalla, y escribe <dir_salida>/<nombre-base-video>/evidence.md (además de transcript.txt, segments.tsv, frames/, ocr.txt). Videos largos en CPU son lentos; establece WHISPER_MODEL=small para calidad, o usa una GPU CUDA para velocidad (detección automática; ver WHISPER_DEVICE en scripts/transcribe.py). Procesa los videos secuencialmente, no en paralelo.
Paso de visión opcional (Qwen-VL). El OCR solo lee texto. Para capturar también lo que el texto no puede — gráficos y su tendencia, diagramas, diseño de interfaz, un gesto del orador — activa un modelo de visión que describa cada fotograma clave conservado. Está desactivado por defecto; actívalo estableciendo VISION_MODEL (y, si es necesario, VISION_ENDPOINT) en el entorno del mismo 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_salida>/<nombre-base-video>"
Cuando está activado, evidence.md gana una sección "## Descripciones visuales" junto al OCR — úsala para diapositivas de gráficos/diagramas. Funciona con cualquier endpoint de visión compatible con OpenAI (llama-swap una vez que haya un servidor local como llama.cpp/llama-swap u Ollama, o una API alojada; VISION_API_KEY si necesita un token). Si el endpoint no está disponible, la ejecución continúa solo con OCR — nada se rompe.
4. Escribir la presentación
Lee todo el evidence.md. Copia "$SKILL/templates/deck.marp.md" a <dir_salida>/<nombre-base-video>/deck.md y complétalo. Reglas:
- Conserva el frontmatter
marp: true— eso es lo que lo convierte en una presentación. - Usa la transcripción para lo que se dijo; usa el OCR / texto en pantalla para etiquetas, números, títulos y código exactos mostrados en las diapositivas; si hay una sección "Descripciones visuales" (el paso de visión estaba activado), úsala para gráficos/diagramas/interfaz que el OCR no puede transmitir.
- Etiqueta una afirmación con su momento cuando sea útil:
[00:04:12]. - Coloca el fotograma clave de la diapositiva en la diapositiva — esto es lo PREDETERMINADO, no un adorno opcional.
Cada bloque
### [intervalo de tiempo] frames/kf_####.jpgenocr.txtnombra el fotograma representativo para esa diapositiva; llévalo a la diapositiva de la presentación en la que se convirtió:. El fotograma clave es la evidencia de la diapositiva, muestra el diagrama/gráfico/interfaz que las viñetas solo pueden describir, y hace que la presentación refleje la fuente. Omítelo solo cuando la diapositiva sea una diapositiva de diagrama puro que redibujaste en Mermaid, o cuando el fotograma no tenga señal visual (una cabeza parlante, una transición en blanco). Cuando dos diapositivas de la presentación provengan de una diapositiva fuente, usa dos fotogramas diferentes de esa diapositiva en lugar de repetir uno. - Incluye solo lo que la evidencia respalde. Si la transcripción y el OCR están vacíos, di que el video no tenía contenido extraíble en lugar de inventar una presentación.
Densidad: la presentación debe CONSOLIDAR la evidencia, no resumirla a la ligera. El fallo más común es una presentación superficial: 20 diapositivas con viñetas de cuatro palabras que desechan la mayor parte de lo que el video realmente contenía. El paquete de evidencia es caro de construir; la presentación es lo que la gente lee.
- Una diapositiva de presentación por diapositiva fuente. Cada bloque
### [intervalo de tiempo] frames/…en la sección OCR es una diapositiva real del video — esa lista es tu lista de verificación y aproximadamente tu recuento de diapositivas. No combines tres diapositivas fuente en una viñeta. Una charla de 40 minutos normalmente tiene 30-45 diapositivas. - Lleva los detalles específicos a la diapositiva. Cada número, métrica, umbral, porcentaje, nombre de producto, CRD, clave de configuración y etiqueta presente en la evidencia pertenece a la diapositiva. Si la diapositiva fuente tenía seis viñetas y cuatro estadísticas, tu diapositiva tiene seis viñetas y cuatro estadísticas — no "precisión mejorada".
- Las viñetas son una línea completa (~15-20 palabras), no cuatro palabras. 5-8 por diapositiva es normal. Ser conciso solo es correcto cuando la fuente era concisa.
- Usa una tabla siempre que la fuente sea tabular — matrices de enrutamiento, cuadrículas de benchmarks, definiciones de niveles, reglas de prioridad. Reproduce cada fila y columna, no una muestra.
- Las notas del orador son adicionales, para lo que se dijo que no está en la diapositiva: salvedades, anécdotas, el "por qué", detalles de preguntas y respuestas. No son el lugar para ocultar contenido que pertenece a la diapositiva.
- Verificación de cobertura antes de terminar. Recorre los bloques
### [..]enocr.txten orden y confirma que cada uno está representado. Si omitiste un bloque, o era una duplicación/animación de la diapositiva anterior o un fotograma de demostración — sé capaz de decir cuál.
5. Paso de diagramas (la comprobación "¿esto puede ser un diagrama?")
Para cada tema, pregúntate: ¿es estructural (componentes + conexiones, interacciones entre actores, un proceso/flujo, estados + transiciones, entidades + relaciones)? Si es así, dibújalo como un diagrama Mermaid (por defecto) o PlantUML en su propia diapositiva en lugar de viñetas. Consulta "$SKILL/references/diagrams-cheatsheet.md" para la tabla de decisión contenido→tipo y esqueletos copiables. No fuerces un diagrama donde el contenido es solo narrativo.
6. (Opcional) Exportar la presentación real
bash "$SKILL/scripts/render.sh" "<dir_salida>/<nombre-base-video>/deck.md" pptx # o pdf | html | all
Esto pre-renderiza los bloques de diagrama a imágenes, luego produce el PPTX/PDF. Si marp/mermaid no están instalados, la presentación simplemente permanece como .md (aún válida y visible).
Para un árbol completo de una vez, agrega --pdf al controlador por lotes (abajo) en lugar de llamar a render.sh por cada presentación.
Lotes/carpetas anidadas
Para una carpeta completa — especialmente un árbol de curso anidado — prefiere scripts/drive_decks.sh <raíz>: itera en bash y genera un agente nuevo por video (nunca desborda el contexto del modelo) y refleja las subcarpetas fuente en la salida, por lo que la jerarquía padre→hijo se conserva. scripts/rename_by_topic.sh <presentaciones> luego transforma cada hoja en un slug según su tema dentro de la carpeta de su curso. Agrega --pdf para exportar cada presentación a PDF una vez que finalice la autoría — Mermaid se pre-renderiza a imágenes, y la carpeta hoja se colapsa para que cada PDF termine en su padre (<salida>/CursoA/leccion/presentacion.md → <salida>/CursoA/leccion.pdf), evitando una subcarpeta por PDF. Para reconstruir la jerarquía de presentaciones que se produjeron planas en una ejecución anterior, usa scripts/regroup_by_source.sh <presentaciones> — lee la línea Source: de cada evidence.md para colocar cada presentación bajo su padre de curso (duplicados en cuarentena en _duplicates/), luego ejecuta el renombrado. Consulta README.md para la guía completa de lotes.
Referencias
references/marp-cheatsheet.md— Sintaxis de diapositivas Marp (separadores, imágenes, notas, columnas).references/diagrams-cheatsheet.md— Cuándo dibujar un diagrama y la sintaxis para cada tipo.
Notas
- El OCR captura bien el texto en pantalla para screencasts/diapositivas de video. Para grabaciones de acción real, la transcripción lleva la mayor parte de la señal — apóyate en ella y no hagas afirmaciones exageradas sobre los elementos visuales.
- La transcripción, el OCR y el renderizado siempre son locales. Si el paso de autoría abandona la máquina depende completamente del agente al que apuntes con
--agent-cmd. - El diseño es independiente del modelo: cualquier agente de texto que pueda ejecutar bash y leer archivos puede usar esta habilidad.