CubeLabs

1. ¿Qué es PPT Master?

PPT Master es un proyecto open source (licencia MIT) creado por Hugo He, un profesional de finanzas (CPA · CPV) que quería que las diapositivas generadas por IA siguieran siendo editables en PowerPoint, no imágenes aplanadas. Es uno de los repos más en tendencia de GitHub con más de 46.000 estrellas y cientos de estrellas nuevas al día.

Su tesis es simple: "editable ya no es suficiente — la pregunta real es cuánto PowerPoint obtienes de verdad". PPT Master entrega el modelo de objetos nativo de PowerPoint:

• Shapes y conectores nativos con handles de ajuste funcionales — haz clic en cualquier elemento y sigue editándolo como objeto nativo.
• Gráficos y tablas con datos reales — objetos Chart/Table respaldados por datos, con Edit Data.
• Modelo completo de texto/imagen/relleno/efecto de PowerPoint.
• Slide masters y layouts reales (p:sldMaster / p:sldLayout) vía la ruta de plantillas.
• Transiciones nativas y animaciones opt-in de entrada/énfasis/trayectoria/salida.
• Notas del orador que pueden convertirse en narración de audio e incluso vídeo MP4.

En forma, es un workflow (una "skill") que corre dentro de cualquier herramienta con capacidad de agente: le dices en el chat "haz un deck a partir de este PDF" y ejecuta el pipeline en tu máquina. La fórmula del proyecto:

# harness + modelo = agente
$ harness (PPT Master) + modelo (Kimi K3 / Claude) = agente que genera PPTX
PPT Master solo posee el workflow; el modelo pone el techo de calidad.

Tres promesas del proyecto:

En las próximas lecciones lo instalaremos, generaremos nuestro primer deck y exploraremos cada capacidad con ejemplos reales.

2. Instalación y requisitos

Lo único que necesitas instalar es Python 3.10+. Todo lo demás viene con una línea: pip install -r requirements.txt.

Paso a paso

Formatos de entrada y Pandoc

La mayoría de formatos se procesan nativamente con Python. Pandoc solo hace falta para formatos legacy:

# Solo si necesitas formatos legacy
brew install pandoc          # macOS
sudo apt install pandoc      # Ubuntu / Debian

Elegir el modelo

La recomendación del autor: Kimi K3 (o Claude) con ventana de contexto grande (~1M tokens), emparejado con generación de imágenes gpt-image-2 (OpenAI) o gemini-3.1-flash-image (Google). Otros modelos pueden ejecutar el pipeline, pero con una brecha de calidad.

Instalación alternativa por marketplace

El repo incluye .claude-plugin/marketplace.json, así que también puedes instalarlo como skill vía marketplace:

npx skills add hugohe3/ppt-master
# O dentro de Claude Code:
/plugin marketplace add hugohe3/ppt-master
/plugin install ppt-master@ppt-master

Verifica que todo quedó listo abriendo el proyecto en tu agente y pidiendo un deck de prueba (siguiente lección).

3. Tu primera presentación

El bucle completo son tres pasos. Ya tienes instalado; ahora a crear.

El flujo de confirmación

Por defecto (salvo que pidas generación rápida), el agente primero confirma el spec de diseño:

Tú: Please create a PPT from projects/q3-report/sources/report.pdf
IA:  Sure. Let's confirm the design spec:
     [Template] B) Free design
     [Format]   PPT 16:9
     [Pages]    8-10 pages
     ...

El agente se encarga de todo: análisis de contenido, diseño visual, generación de SVG y exportación a PPTX. Los formatos de lienzo soportan PPT 16:9, Xiaohongshu, WeChat y más de 10 formatos adicionales.

Comandos de ejemplo

# Desde un archivo
You: Please create a PPT from projects/q3-report/sources/report.pdf

# Desde contenido pegado
You: Please turn the following into a PPT: [pega tu contenido...]

# Con especificaciones
You: Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/

4. El pipeline SVG → PPTX

Entender el pipeline te ayuda a sacar más partido y a diagnosticar problemas. PPT Master escribe el diseño en SVG y luego lo convierte a DrawingML, el formato XML nativo de PowerPoint.

Cómo fluye el trabajo

sources/ (PDF, DOCX, texto)
   │  conversión y análisis por el agente
   ▼
SVG hand-authored (diseño por página)
   │  # pipeline SVG: un conversor
   ▼
svg_output/ ──► finalize_svg.py ──► svg_final/  (previews autocontenidas)
   │
   ▼
exports/<nombre>_<timestamp>.pptx   (DrawingML nativo editable)

• SVG hand-authored: el agente escribe cada diapositiva como SVG (formas, texto, colores, iconos, fórmulas) siguiendo el spec de diseño.
• Un solo conversor SVG→PPTX: lee svg_output/ y escribe un deck DrawingML directamente editable.
• finalize_svg.py: en el flujo estándar genera previews autocontenidas en svg_final/ para que veas cada página antes de abrir PowerPoint.

¿Por qué SVG? Porque es un formato de dibujo vectorial que mapea de forma casi directa a los objetos de PowerPoint: rectángulos, elipses, texto, rutas, rellenos y gradientes. El proyecto mantiene una guía de mapeo PowerPoint ↔ SVG honesta, feature por feature, que documenta hasta dónde llega la conversión hoy (SmartArt es una omisión deliberada).

Qué recibes al final

5. Modo rápido (Quick mode)

El flujo estándar tiene una ronda de confirmación (spec de diseño + elección de plantilla). El modo rápido salta esa ida y vuelta: es una pasada única, no resumible, que va directo a autoría y exportación.

# Pide explícitamente generación rápida
You: Quickly generate a 5-page deck from projects/q3-report/sources/report.pdf — no need to confirm with me

# Con requisitos explícitos
You: Turn this into a deck, skip the confirmation, about 8 pages, dark corporate look

Lo que digas explícitamente se cumple; lo que no digas, el agente lo decide solo — sin volver a preguntar. El número de páginas y el estilo del segundo ejemplo se respetan: el modo rápido elimina la ronda de confirmación, no tu control.

Qué cambia respecto al flujo estándar

• Sin design_spec.md ni spec_lock.md: las decisiones de contenido/diseño existen solo en el contexto activo del agente. Si se pierde el contexto antes de entregar, empieza de nuevo.
• Sin preview svg_final/: el modo rápido no ejecuta finalize_svg.py en la ruta por defecto; exporta directamente el PPTX.
• No pierde capacidades: conversión de fuentes, investigación de huecos factuales, guía estética compartida, imágenes/iconos/shapes nativos/gráficos/tablas/fórmulas se siguen preparando según necesidad.
• El modo rápido acepta hasta una raíz de workspace exacta por tipo (Brand/Style/Layout/Deck) y la valida e instala; sin raíz exacta usa diseño libre.

Regla práctica: usa el flujo estándar cuando quieras revisar el spec antes de generar; usa quick mode cuando tengas claro lo que quieres y valores la velocidad.

6. Imágenes: generación IA y búsqueda web

Para las imágenes que no trae el usuario, PPT Master ofrece dos rutas mezclables dentro del mismo deck:

A) Generación IA — image_gen.py

Configura IMAGE_BACKEND más la *_API_KEY del proveedor y el pipeline la llama automáticamente:

# En .env
IMAGE_BACKEND=openai
OPENAI_API_KEY=sk-...
# o
IMAGE_BACKEND=gemini
GEMINI_API_KEY=...

# Ver backends disponibles
python3 skills/ppt-master/scripts/image_gen.py --list-backends

Actualmente gpt-image-2 es el mejor default por calidad.

B) Búsqueda web — image_search.py

Funciona sin configuración: sin claves usa Openverse / Wikimedia Commons como fallback. Con claves gratuitas de Pexels o Pixabay mejora mucho la calidad de fotografía moderna:

# En .env (ambas son gratuitas)
PEXELS_API_KEY=...
PIXABAY_API_KEY=...

El licenciamiento se gestiona automáticamente: considera CC0, Dominio Público, licencias Pexels/Pixabay sin atribución, CC BY y CC BY-SA, y añade un pequeño crédito inline cuando la imagen seleccionada requiere atribución. Usa --strict-no-attribution solo si una diapositiva no puede tolerar ninguna línea de crédito.

Dónde viven las claves

Las API keys viven en .env. El orden de lectura: primero las variables del entorno del proceso, luego el primer .env encontrado en: directorio actual → directorio de la skill → raíz del repo clonado → ~/.ppt-master/.env.

cp .env.example .env            # instalación por clone
mkdir -p ~/.ppt-master
cp /ruta/ppt-master/.env.example ~/.ppt-master/.env   # instalación por marketplace

7. Plantillas y reutilización

Por defecto PPT Master usa diseño libre — no necesitas plantilla. Pero cuando un deck debe reutilizar una identidad de marca, un método de comunicación o un set fijo de layouts, hay dos rutas para reutilizar un .pptx existente:

Fill Native PPTX

Dale al agente tu .pptx más tu material (o un tema) y pídele: "fill this deck with the new content". Rellena datos en tu diseño existente y exporta solo las páginas que elijas, manteniendo todo nativamente editable.

Create Template

Para construir un workspace reutilizable, pide explícitamente la ruta Create Template:

You: Create a reusable Deck template from projects/brand/our_deck.pptx via /create-template

El importador analiza la referencia, confirma si el resultado es Brand, Style, Layout o Deck y materializa un workspace validado con su templates/design_spec.md más los prototipos y assets requeridos. Los workspaces viven en:

Para usar un workspace al generar, da su ruta raíz exacta en el chat (un nombre de plantilla a secas nunca resuelve a un workspace):

You: Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/

8. Gráficos y tablas nativos

Los gráficos y tablas tienen dos modos de exportación, y la diferencia importa:

• Por defecto: los gráficos y tablas se exportan como shapes DrawingML derivados de SVG — editables y visualmente consistentes entre aplicaciones (priorizan la consistencia cross-app).
• Con --native-charts-and-tables: los grupos elegibles se sustituyen por objetos Chart/Table nativos de PowerPoint respaldados por datos, con Edit Data y controles específicos del objeto. Pueden renderizar distinto entre aplicaciones.

# Exportar con objetos nativos Chart/Table
python3 skills/ppt-master/scripts/export.py --native-charts-and-tables

# El archivo resultante se guarda como:
exports/<nombre>_<timestamp>_native_charts_tables.pptx

Ambas variantes son editables — la diferencia es el modelo de objetos de PowerPoint, no la editabilidad. Con la variante nativa, en PowerPoint haces clic derecho sobre el gráfico y accedes a Editar datos para abrir la hoja de datos real.

Además de gráficos y tablas, el pipeline prepara fórmulas matemáticas como objetos renderizados cuando el contenido lo requiere (informes financieros, papers, documentos técnicos).

9. Animaciones, transiciones, narración y vídeo

Los decks exportados llevan transiciones de página y animaciones opcionales por elemento como OOXML real — no vídeo incrustado.

Transiciones y animaciones

El default es una transición fade con ninguna animación de elemento. Para activar animaciones:

# Ejemplo: animaciones automáticas
You: Generate this deck with animations (-a auto)

Los 29 short names antiguos siguen aceptándose como compatibilidad, pero las elecciones nuevas usan nombres con prefijo canónico. La configuración es estricta: efectos desconocidos, modos de inicio inválidos o valores de timing incorrectos fallan en lugar de convertirse silenciosamente en otro efecto. Antes de reemplazar un resultado existente, PPT Master lee el paquete candidato y comprueba timing, IDs, targets de shape, efectos, duraciones y modos de inicio.

Narración y vídeo

Convierte las notas del orador en narración de voz por diapositiva, incrusta el audio en el PPTX y deja que PowerPoint exporte el deck como MP4 con narración sincronizada — sin herramientas de terceros.

You: Generate narration for this deck and re-export with audio embedded.
You: Generate narration audio for this deck

La narración usa por defecto edge-tts (unos 90 locales); los proveedores cloud opcionales cubren voces de mayor calidad. El agente recomienda una voz para el idioma del deck y pregunta una vez antes de generar.

Voz clonada

Trae tu propia voz clonada de ElevenLabs / MiniMax / Qwen / CosyVoice y que todo el deck se narre con tu voz (o la de un presentador, con permiso). Clona una vez en la consola del proveedor, pasa el voice_id, y PPT Master lee las notas de cada diapositiva en esa voz y lo incrusta de vuelta en el PPTX.

10. Live preview, solución de problemas y mejores prácticas

Live preview y edición visual

Mientras el deck se genera, se abre una preview en el navegador en la URL que reporta el launcher (prefiere http://localhost:5050 y usa el siguiente puerto libre si está ocupado).

• Ver las páginas renderizarse en vivo mientras el agente las produce.
• Editar directamente, sin IA: selecciona un elemento y cambia texto, color, fuente o tamaño en el panel lateral; arrástralo para reposicionar o muévelo con las flechas (Shift = 10px). Ctrl+Z deshace. Los cambios se escriben en svg_output/ al pulsar Apply changes.
• O anotar para el agente: haz clic en un elemento, escribe qué quieres cambiar, pulsa Submit annotations, y di "apply my annotations" en el chat para que el agente reescriba esa región y re-exporte el PPTX.

Solución de problemas común

Mejores prácticas

1. Empieza con el flujo estándar — revisa el spec de diseño antes de generar; usa quick mode cuando el requisito esté claro.
2. Elige el modelo adecuado al material — documentos densos (papers, informes) se benefician de modelos de contexto grande como Kimi K3 o Claude.
3. Separa assets en projects/ — ruta y naming claros evitan que el agente use archivos equivocados.
4. Aprovecha la preview en vivo para pulir antes de exportar; corregir en SVG es más barato que en PowerPoint.
5. Para entregables de marca, crea un workspace Brand/Style y reutilízalo en cada deck.
6. Usa narración y MP4 sincronizado para convertir un buen deck en contenido formativo sin herramientas extra.
7. Guarda los .env fuera de git — las claves de imagen y búsqueda no deben versionarse.

Con esto ya tienes el mapa completo: instalar, crear tu primer deck, dominar el pipeline SVG→PPTX, modo rápido, imágenes, plantillas, gráficos nativos, animaciones, narración y troubleshooting. Es hora de lanzar tu agente, soltar un PDF en projects/ y pedir tu primer deck.