# Motor de lecciones del curso AIB-C01 — diseño

**Fecha:** 24 de septiembre de 2026
**Alcance de esta spec:** el motor que convierte un guion escrito en una lección renderizada, validado sobre la lección 1 ya producida.
**Fuera de alcance:** el temario de las otras 39 lecciones, la plataforma de venta y el examen de práctica. Cada uno necesita su propia spec.

---

## 1. Qué problema resuelve

Un curso de preparación para la certificación **AWS Certified AI Business Strategist (AIB-C01)**, en español, de unas 3,5 horas repartidas en unas 40 lecciones.

El cuello de botella no es grabar: es sincronizar. Cada lección tiene entre 10 y 20 revelados de viñeta que deben aparecer exactamente cuando el instructor dice la frase correspondiente. Marcarlos a mano cuesta entre 20 y 40 minutos por lección, se rompe cada vez que se regraba una frase, y no sobrevive a 40 repeticiones.

El motor elimina ese trabajo: el instructor escribe, graba de corrido, y el sistema calcula los tiempos leyendo el audio.

## 2. Qué ya está demostrado

Esta spec no es una propuesta: describe un sistema que ya produjo la lección 1 completa.

| Comprobación | Resultado sobre material real |
|---|---|
| Alineación automática de viñetas | 15 de 15 resueltas, orden monótono, sin revelados pegados |
| Tolerancia a que el guion cambie al grabar | 3 frases modificadas al hablar, detectadas por parecido |
| Escala de tiempo tras ajustar el ritmo | 3 anclas verificadas contra el audio acelerado, exactas |
| Render final | 2:47,8 con 4 láminas, 15 revelados, columna y panel en movimiento |
| Integridad del audio | md5 idéntico al máster, sin segunda compresión |

Piloto: `piloto/leccion1-v3-1708.mp4`.

## 3. Arquitectura

Cuatro componentes con una sola dirección de dependencia. Cada uno se puede probar solo.

```
leccion-NN.md ──> alinear.py ──> leccion-NN.timing.json ──> Remotion ──> Lambda ──> leccion-NN.mp4
   (guion)         (+ audio)         (tiempos)              (plantillas)   (render)
```

**`leccion-NN.md`** es la fuente única. Contiene lo que se proyecta y lo que se dice, en el mismo archivo, porque separarlos es lo que desincroniza láminas y voz.

**`alinear.py`** toma el audio ya editado y produce los tiempos. Es también la compuerta: si algo no cuadra, falla y nombra el problema en vez de producir un JSON dudoso.

**Las plantillas de Remotion** reciben tiempos y medios, y no saben nada de audio ni de transcripción.

**Lambda** solo renderiza. El sitio y la función se despliegan una vez; cada lección es una invocación.

## 4. Formato del guion

```markdown
---
leccion: 1
seccion: "1 · Introducción"
titulo: "Bienvenida al curso"
idioma: es-419
---

## lámina: Bienvenida
plantilla: vinetas
columna: si

- Vamos a prepararnos juntos en este examen {vamos a prepararnos juntos}
- El examen evalúa criterio, no práctica en consola {te va a pedir criterio}

## narración

Hola, y bienvenido a este curso sobre la certificación...
```

Cada viñeta lleva entre llaves su **frase de disparo**: el fragmento que el instructor dirá en el momento en que esa viñeta debe aparecer. Sin llaves, se usa el texto de la viñeta.

**Regla dura de sintaxis:** las llaves `{}` delimitan la frase de disparo y **no pueden convivir con mapas YAML en línea**. Las propiedades de la lámina van siempre en lista indentada, nunca `{clave: valor}`. Esto ya causó dos disparos fantasma durante el piloto.

### Propiedades por lámina

| Propiedad | Valores | Por defecto |
|---|---|---|
| `plantilla` | `portada`, `vinetas`, `contraste`, `sobre-mi` | obligatoria |
| `columna` | `si`, `no` | `si` |
| `video` | ruta a un panel en movimiento | ninguno |
| `fotos` | lista de imágenes con rótulo | ninguna |

**La lámina declara lo que quiere; el motor no decide por su cuenta.** Si una lámina pide columna y panel de video a la vez, el motor los acomoda. Si no caben, **falla y lo dice**, en lugar de sacrificar uno en silencio. Esta regla existe porque durante el piloto se eliminó un panel aprobado aplicando una heurística no declarada.

## 5. El alineador

Entrada: el audio de la lección, ya editado. Salida: `leccion-NN.timing.json`.

**Procedimiento**

1. Transcribir con Whisper `medium`, marcas por palabra, idioma fijado a español.
2. Normalizar transcripción y frases de disparo: minúsculas, sin acentos, sin puntuación.
3. Buscar cada frase de disparo como subcadena exacta. Si aparece, el tiempo del revelado es el inicio de su primera palabra.
4. Si no aparece, buscar la ventana de igual número de palabras con mayor parecido (`SequenceMatcher`).
   - Parecido **≥ 0,85**: se acepta, se registra un aviso y se anota en el JSON la frase realmente dicha.
   - Parecido **< 0,85**: es un fallo de compuerta.

El paso 4 es lo que permite que el instructor hable natural. En el piloto capturó tres desvíos reales: *prepararnos* por *preparar*, una negación desplazada, y una cifra distinta.

**El orden importa:** el alineador corre **siempre sobre el audio definitivo**. Cualquier ajuste de ritmo o recorte se aplica antes. Si se altera el audio después de alinear, todos los revelados quedan desfasados y el desfase crece a lo largo de la lección.

### Ajuste de ritmo

Se aplica con `atempo`, que preserva el tono. Es una escala uniforme, así que los tiempos ya calculados se pueden dividir por el factor en lugar de volver a transcribir, **verificando tres anclas** repartidas contra el audio nuevo. En el piloto (factor 1,15) las tres cayeron exactas, lo que ahorra unos cinco minutos de CPU por lección.

Antes de acelerar hay que medir dónde se va el tiempo. En el piloto los silencios eran solo el 10 % y ninguna pausa superaba 0,83 s: recortarlos no habría servido y el ajuste tenía que ser de tempo.

## 6. Identidad visual

Decidida por el panel de asesores: **el molde del género de certificación con el acento propio**. El costo de diseño es único y vive en las plantillas; a partir de la lección 2, escribir una lección es escribir texto.

| Elemento | Valor |
|---|---|
| Lienzo | 1920 × 1080, 30 fps |
| Papel | `#FBFBF9` · Tinta `#16181D` · Texto suave `#373C46` |
| Acento | `#D99A2B` |
| Tipografía | Inter (ExtraBold títulos, SemiBold destacados, Regular cuerpo) |
| Título | 60 a 64 px, arriba a la izquierda |
| Cuerpo | 31 px |
| Columna del instructor | 430 px a la izquierda, fondo `#ECECE8`, degradado de 22 px |
| Margen del contenido | desde x=500 hasta x=1810 |
| Pie | regla dorada de 190 px y nombre de la certificación |

El acento dorado **nunca se usa para texto de cuerpo sobre papel claro**: no alcanza el contraste mínimo. Va en viñetas, reglas y subrayados.

### La columna

El instructor se graba **en vertical (1080 × 1920)**, que recortado a 430 × 1080 no necesita escalar hacia arriba y conserva resolución nativa.

Con columna, el ancho útil del contenido baja de 1810 a 1250 px. Eso condiciona la redacción: a 31 px de cuerpo, una viñeta de más de 1250 px se parte en dos líneas. El motor no lo impide, pero lo mide y lo reporta.

## 7. Compuertas de verificación

Ninguna lección se publica sin pasar las seis. Todas son contables o inspeccionables; ninguna es "se ve bien".

1. **Disparos resueltos.** Las frases de disparo aparecen en el audio, por coincidencia exacta o con parecido ≥ 0,85. Falla nombrando la frase y su mejor candidata.
2. **Orden monótono.** Los revelados avanzan en el tiempo. Un orden roto significa que una frase de disparo aparece antes de lo previsto.
3. **Separación mínima.** No hay dos revelados a menos de 0,4 s. Por debajo se leen como uno solo.
4. **Altura del bloque.** El bloque de viñetas no invade la zona de medios ni el pie. Falla nombrando la lámina.
5. **Movimiento en los paneles de video.** Todo panel declarado demuestra movimiento: se comparan pares de fotogramas separados 0,5 s dentro de su región, y la diferencia media debe superar 3.
   **Las muestras nunca se toman a intervalos múltiplos de la duración del bucle**, o caen en el mismo punto del montaje y dan un falso congelado. Esto ya produjo un diagnóstico equivocado durante el piloto.
6. **Integridad del audio.** El md5 del audio del render coincide con el del máster editado. El audio **se copia, nunca se recodifica dos veces**.

Además, la duración del render debe coincidir con la del audio.

## 8. Decisiones y sus contrapartidas

**Guion anotado con alineación automática, en vez de marcado manual.** Producir la lección 12 cuesta lo mismo que la 2. La contrapartida es que depende de la calidad de la transcripción; por eso el umbral de parecido y el aviso explícito cuando se usa.

**El audio manda sobre el guion.** Cuando el instructor cambia una frase al hablar, se ajusta el guion, no se regraba. El archivo `.md` queda como registro de lo dicho, no de lo planeado.

**Columna siempre presente por defecto.** Cuesta el 22,4 % del cuadro de forma permanente. Se acepta porque construye confianza en un mercado donde el alumno elige entre este curso y uno en inglés, y porque la lámina puede pedir el cuadro completo cuando lo necesite.

**Renderizar en Lambda en vez de local.** Una lección de 3 minutos a 1080p tarda minutos en una máquina y segundos en paralelo. Con 40 lecciones y varias iteraciones cada una, la diferencia es de días. La contrapartida es depender de una cuenta de AWS y de un despliegue que hay que mantener.

## 9. Lo que queda fuera, a propósito

- **Editor visual de tiempos.** El alineador los calcula; corregir a mano devuelve el problema que esto resuelve.
- **Transiciones entre láminas.** Un corte seco no distrae y no cuesta render.
- **Subtítulos quemados.** La plataforma de cursos los genera y permite elegir idioma.
- **B-roll y animaciones.** Ninguna de las cuatro cosas anteriores cambia si el alumno aprueba el examen, y las cuatro cuestan tiempo por lección.

## 10. Estructura de archivos

```
curso-aibc01/
├── lecciones/
│   ├── leccion-01.md                 fuente única
│   ├── leccion-01-para-grabar.txt    solo narración, generado
│   └── leccion-01.timing.json        salida del alineador
├── medios/
│   ├── grabaciones/leccion-01.mp4    vertical, crudo
│   ├── editado/leccion-01.mp4        con ritmo ajustado
│   └── fotos/                        imágenes de las láminas
├── motor/
│   ├── alinear.py                    alineador y compuertas 1 a 3
│   ├── verificar.py                  compuertas 4 a 6
│   └── remotion/                     plantillas y composición
└── salida/
    └── leccion-01-vN-HHMM.mp4        siempre con sufijo de versión
```

**El sufijo de versión en la salida no es cosmético:** el caché de borde retiene cuatro horas las URL sin versionar, y durante el piloto impidió ver una corrección ya publicada.

## 11. Criterios de aceptación del motor

1. Producir la lección 1 desde `leccion-01.md` más el audio, sin intervención manual, y que el resultado sea equivalente al piloto ya validado.
2. Las seis compuertas fallan cuando deben: se verifica introduciendo un defecto de cada tipo y comprobando que el sistema lo nombra.
3. Una lección nueva, escrita y grabada desde cero, llega a render sin tocar el código del motor.
