motion-diorama

Motion Diorama — Habilidad de Producción de Videos Educativos (v3.0 · edición pública)

Principio fundamental: revisa antes de renderizar, no después. Todo lo que se puede verificar a bajo costo (línea de tiempo, fotogramas fijos, ancho del texto) DEBE pasar primero. El renderizado a resolución completa se realiza solo una vez, al final, después de que todos los semáforos estén en verde.

Este archivo es el NÚCLEO. Los detalles visuales por modo están en references/ — mode-a.md para el Modo A, mode-b.md para el Modo B, mode-c.md para el Modo C (DEBEN LEERSE según el modo de este video, antes de construir la escena). Los escenarios de prueba están en evals/evals.md. Los scripts en scripts/ se ejecutan TAL CUAL — no reescribas sus funciones.

Decisiones bloqueadas (del creador de la habilidad — no las cambies a escondidas; si usas esta habilidad y la modificas, hazlo de forma consciente)

• Tres modos activos: Modo A (paisaje/historia + variante de mapa vivo), Modo B (desmontar objetos — cómo funcionan las cosas/máquinas), y Modo C (anatomía — Serie del Cuerpo Humano). El modo lo selecciona el usuario por video a través del prompt de inicio; la sesión lee el archivo de referencia de ese modo antes de la Etapa 2.
• Objetivo: construir audiencia. Cierre predeterminado = conclusión (Modo A) / llamada de retorno (Modo C) + fundido a negro. NO hay tarjetas/etiquetas de serie dentro del video y NO hay píldoras de etapa/indicadores de posición en pantalla (decisión del usuario 13 de noviembre de 2026, v2.8) — la identidad de la serie solo vive en los subtítulos. La llamada al valor es SÓLO ocasional, si el tema lo permite y el usuario lo solicita para ese video — no es un elemento obligatorio. Las CTA de venta están prohibidas.
• Números/datos = HÍBRIDO: la superposición de lectura en pantalla (overlay DOM) es el sistema principal para TODOS los números. Excepción: un máximo de UN número héroe 3D dorado dentro de la escena por video, solo para el número cumbre de ese video — y el mismo número DEBE aparecer también como lectura/subtítulo, porque la versión 3D es un énfasis visual, no un portador de información.
• Duración final 30–60 segundos, siguiendo el audio.
• Audio: esta habilidad es AGNÓSTICA respecto al audio — usa cualquier MP3 de narración que el usuario proporcione en public/narasi.mp3.
• Música: archivo del usuario en public/musica.* — no elijas música.
• Hechos: la fuente del usuario es la referencia PRINCIPAL y prevalece si hay conflicto. La sesión PUEDE complementar con investigación web, con la condición de que: la fuente se cite en el informe final, se prioricen fuentes autoritativas (revistas, instituciones, oficiales), y las afirmaciones no verificadas DEBEN marcarse como inciertas — está prohibido presentar conjeturas como hechos.
• Operador único: una persona. Todos los resultados DEBEN aparecer como archivos en la sesión (fotogramas fijos, vista previa, final) para poder descargarlos.
• Ritmo objetivo: 1–2 videos/día. La eficiencia es un requisito de diseño: reutiliza andamios, primitivas y componentes; no reconstruyas lo que ya existe.
• Compuertas — Modo Residencia es la configuración predeterminada de la edición pública: la sesión NO se detiene esperando la aprobación del usuario. La Compuerta 1 (resumen de la línea de tiempo) y la Compuerta 2 (hoja de contactos de fotogramas fijos) se ejecutan INTERNAMENTE: la sesión evalúa los resultados de su propia etapa contra los criterios escritos de esta habilidad (PASS del validador + lista de verificación de QC), se corrige a sí misma los hallazgos (máx. 2 intentos de corrección por escena), y luego continúa. La decisión sigue el BLOQUE DE DECISIÓN en el prompt (predeterminado: la narración demasiado larga se acelera con atempo hasta un máx. de 1,25×; los hechos no verificados se marcan en el informe). Las preguntas no respondidas de ese bloque se plantean TODAS JUNTAS en un solo mensaje antes de que comience la construcción — está prohibido preguntar a mitad de camino. La sesión solo puede detenerse a mitad de camino por BLOQUEADORES DUROS: (a) material faltante o dañado, (b) transcripción imposible de crear, (c) narración que sigue fuera del rango de 30–60 segundos después del atempo máximo. Si el prompt indica "Modo Residencia: NO", se aplican las compuertas clásicas — dos aprobaciones del usuario (después de la Etapa 1 y después de la Etapa 3) con una escala de flexibilización de la Compuerta 2 basada en evidencia: 3 aprobaciones limpias consecutivas → 1 fotograma fijo por escena; 3 más → opcional para tipos de escena probados; la Compuerta 1 nunca se flexibiliza; una revisión visual mayor restaura el formato completo; cada flexibilización se registra en el informe final.

Prohibiciones estrictas

• Prohibido usar imágenes de IA/fotos/2D/sprites/texturas externas/modelos descargados como escena. Todo el contenido visual = geometría 3D procedural de Three.js.
• Prohibido letterbox; cámara nativa 9:16.
• Movimiento solo desde la cámara en el espacio 3D (parallax real). Prohibido simular movimiento mediante zoom/pan de imágenes 2D.
• Humanos solo como siluetas oscuras pequeñas sin rostro. El sujeto principal del Modo A no tiene primeros planos (distancia de cámara mínima de 8 m para animales/objetos héroe de paisaje) — en el Modo C esta regla de distancia no aplica: los órganos héroe llenan el encuadre; en el Modo B esta regla solo vincula el encuadre de la etapa de contexto — el objeto héroe en la etapa de laboratorio sí llena el encuadre (consulta references/mode-b.md y references/mode-c.md).
• Un renderizador, un conjunto de materiales, un rig de luces para todas las escenas.
• Prohibido adivinar la duración a partir del número de palabras/storyboard. El TIEMPO proviene SOLO del audio original (consulte Sincronización).
• Prohibida la animación desde useFrame(), Math.random(), Date.now(), o acumulación de fotogramas — todo el movimiento se deriva de useCurrentFrame() y constantes aleatorias con semilla fija.

Sincronización — timeline.json es la única fuente de verdad

1. Asegúrate de que public/narasi.mp3 exista. Si no existe: DETENTE, informa al usuario. No determines ninguna sincronización antes de que el audio esté disponible.
2. Toma la marca de tiempo por palabra con esta jerarquía: a. Marca de tiempo predeterminada de TTS (p. ej., ElevenLabs con marcas de tiempo) si el usuario la proporciona — la más precisa. b. Plan de respaldo Whisper: solo modelo GRANDE, language="id" forzado (no detección automática), y Whisper solo proporciona el TIEMPO — el texto de las oraciones DEBE provenir del guion oficial del usuario, no del resultado de la transcripción (el ASR de Indonesia se equivoca fácilmente con números y nombres).
3. Organiza docs/timeline.json exactamente con este esquema:

{
  "fps": 30,
  "audio_duration_s": 40.20,
  "total_duration_s": 41.00,
  "sentences": [
    {"id": 1, "text": "…", "start_s": 0.00, "end_s": 3.68, "scene": 1}
  ],
  "scenes": [
    {"id": 1, "sentence_ids": [1, 2], "start_s": 0.00, "end_s": 6.44}
  ]
}

4. Reglas de mapeo: límite de escena = segundo de INICIO de la primera oración de la siguiente escena; el mapeo se basa en el CONTENIDO de la oración — está prohibido agrupar oraciones para llenar la duración; la diferencia entre el corte real y la línea de tiempo ≤ 0,3 segundos.
5. Ejecuta python3 scripts/validate_timeline.py docs/timeline.json. Si FALLA: corrige la línea de tiempo, repite. Está prohibido continuar cuando FALLA.
6. Organiza un resumen de la línea de tiempo (número de oraciones, mapeo de escenas, duración total) y evalúalo contra estos criterios — esta es la Compuerta 1. Modo Residencia: no te detengas; guarda el resumen para el informe final. Modo de compuerta clásica: muéstralo al usuario y ESPERA la aprobación.
7. total_duration_s debe estar entre 30 y 60 segundos. Fuera de ese rango: Modo Residencia — aplica la política del prompt (atempo máx. 1,25× para duraciones largas; estira la pausa de cierre para duraciones cortas) y regístralo en el informe; si aún así está fuera del rango, es un BLOQUEADOR DURO: detente e informa. Modo clásico: informa al usuario — no cortes ni parchees en secreto. El silencio sin razón está prohibido; se permite una pausa de recompensa de 0,3–1 segundo al cierre y se cuenta en el total.

Bloqueo de estilo (resumen — detalles por modo en references/)

Modo A (detalles en references/mode-a.md)

• Diorama 3D estilizado semi-realista: paleta cálida cinematográfica, un rig de luz de atardecer fijo, superficies limpias y suaves, fondo simplificado. La paleta puede ajustarse al tema/temporada; el rig de luz y los materiales no.
• Título del tema: tipografía SERIF en mayúsculas sobre un plano de establecimiento en movimiento. Hook = la primera oración de la narración (pregunta / refutación de mito / paradoja) que aparece como texto + sonido + visual en aproximadamente los primeros 1,5 segundos.
• Subtítulos: karaoke por palabra en páginas de 2–4 palabras (no una sola palabra), palabra activa en negrita, palabra clave en color de acento, en la zona segura inferior.
• Lectura de datos: contador animado que cuenta exactamente cuando se menciona el número en la narración + etiqueta pequeña + línea de puntero; las lecturas siguientes tienen el mismo estilo. El único texto 3D que puede aparecer: un número héroe dorado para el número cumbre (ver Decisiones bloqueadas).
• Cámara: viaje continuo dentro del segmento; zoom escalonado como estructura de argumento; corte brusco solo entre segmentos de hechos, en forma de fundido negro de aproximadamente 0,1 segundos.
• Estructura narrativa: para temas de sistema/flujo usa "sigue un flujo"; un video puede contener dos hechos de un tema con un segmento de demostración.
• Cierre: beauty shot + título/era en serif repetido + oración de conclusión. Fundido a negro; sin etiquetas/tarjetas de serie dentro del video (v2.8). (Llamada al valor solo si se solicita para este video).

Modo B — Desmontar Objetos (detalles en references/mode-b.md)

• DOS etapas del mundo: diorama de CONTEXTO cálido estilo Modo A (el objeto aparece completo en su hábitat) → etapa de LABORATORIO con fondo de cuadrícula técnica oscura donde se desmonta el objeto; transición mediante zoom continuo (el fondo se desvanece/iris), sin corte brusco.
• Un modelo de objeto héroe procedural construido una vez; las vistas de explosión y corte se derivan del mismo modelo.
• SIN tarjeta de título (hook = primera oración de la narración en el plano de contexto) y SIN HUD permanente de ningún tipo — las migas de pan, el contador de zoom y el minimapa de referencia se ELIMINAN (decisión de investigación + dirección v2.8). Navegación desde cámara continua, etiquetas de línea guía y título de fase momentáneo.
• Fases estándar: contexto → zoom + etiqueta de objeto → DESMONTADO (etiquetas de partes bilingües ID + término EN, aparecen según el orden de la narración) → CORTE (proceso animado + lectura del proceso) → ENCENDIDO (el corte funciona, sigue un flujo, etiqueta de proceso, partículas de flujo con código de color semántico) → macro del mecanismo determinante → recompensa de etiqueta de principio de una línea mientras la cámara se aleja.
• Cierre del Modo B: oración de conclusión/principio + fundido a negro; sin tarjetas/etiquetas de serie (v2.8).

Modo C — Anatomía (detalles en references/mode-c.md)

• NO es un diorama: un órgano héroe 3D brillante flotando en un vacío púrpura oscuro con bokeh; un modelo de órgano construido una vez, usado en todas las escenas. Nombre de serie predeterminado de ejemplo: "Serie del Cuerpo Humano" (cámbialo por el nombre de tu serie).
• Código de color de flujo ABSOLUTO: azul = pobre en oxígeno, rojo brillante = rico en oxígeno — nunca se invierte, ni en este video ni entre videos de la serie. Las partículas celulares cambian de color en el punto de intercambio, exactamente en su oración.
• Estructura OBLIGATORIA sigue-un-flujo: la cámara guía un paquete a través de todo el circuito; zoom escalonado desde el órgano → sistema → microscópico → órgano → cuerpo completo (silueta).
• Hook = referencia en tiempo real del espectador + contador en vivo que se ejecuta sincronizado con el latido visual del órgano desde el primer segundo. El título en serif se RETRASA hasta aproximadamente 5–8 segundos (después del hook), seguido de anotaciones de hechos.
• SIN píldoras de etapa y sin HUD de ningún tipo (v2.8): la posición del flujo se lee desde el viaje de la cámara; las etiquetas de chip anatómico se adhieren al órgano y se iluminan cuando su parte está activa.
• Cierre del Modo C: contador final animado + oración de LLAMADA DE RETORNO que refleja el hook; fundido a negro; sin tarjetas/etiquetas de serie (v2.8). Prohibido el gore/realismo médico gráfico.

Reglas de texto (anticorte — la causa número uno de revisiones)

• TODO el texto de lectura obligatoria es un overlay DOM (componente de Remotion), NO texto dentro del lienzo WebGL. La única excepción: el número héroe 3D híbrido en Decisiones bloqueadas — otros textos 3D están prohibidos.
• Mide CADA texto con measureText/fitText de @remotion/layout-utils DESPUÉS de que la fuente esté cargada; fontSize = min(límite del modo, resultado de ajuste); ancho máximo 90% del ancho del fotograma; margen seguro 5% en todos los lados; respeta las zonas seguras de la plataforma (evita ±250 px superior y ±310 px inferior para texto importante).
• Si el texto no cabe en el tamaño mínimo de legibilidad: DIVÍDELO en dos páginas/líneas — está prohibido reducirlo hasta que sea ilegible, está prohibido dejarlo cortado.
• Contraste: el texto claro sobre fondo claro debe tener un contorno/sombra oscura.
• Las etiquetas de línea guía siguen la misma regla.

Audio

• La narración es el reloj maestro: todos los límites de escena, subtítulos, contadores y cámaras leen docs/timeline.json — no hay una segunda fuente de sincronización.
• La música del archivo del usuario se coloca como lecho debajo de la narración (ducking simple; no cubras las palabras). Sin archivo de música del usuario: no inventes música — informa al usuario.
• El final se normaliza a −14 LUFS, pico ≤ −1 dB.

Flujo de producción (el orden no debe saltarse)

• Etapa 0 — Andamiaje: utiliza el andamio del proyecto ya existente; el renderizador, el rig de cámara, el bloqueo de estilo y las primitivas NO se reescriben. Si el repositorio aún no contiene un proyecto Remotion (primera producción): construye el andamio desde la carpeta starter/ en el repositorio de este paquete de habilidad (dependencias con la versión exacta que se haya probado que funciona), luego trátalo como un andamio ya existente.
• Etapa 1 — Línea de tiempo: según la sección Sincronización → validador PASA → Compuerta 1 (interna en Modo Residencia; aprobación del usuario en modo clásico).
• Etapa 2 — Construir escena leyendo timeline.json y el archivo de referencia del modo de este video (references/mode-a.md, references/mode-b.md o references/mode-c.md).
• Etapa 3 — Compuerta de fotogramas fijos: renderiza 3 fotogramas fijos por escena (inicio/medio/fin de escena) + hoja de contactos. Modo Residencia: evalúa la hoja de contactos contra la lista de verificación de QC de este modo, corrige los hallazgos en la etapa de fotogramas fijos (máx. 2 intentos por escena), luego continúa — no esperes al usuario; guarda la hoja de contactos + lista de evaluación para el informe final. Modo clásico: muéstralo y ESPERA la aprobación del usuario. Corrige en la etapa de fotogramas fijos — es mucho más barato que en el video.
• Etapa 4 — Vista previa + QC autónomo: renderiza vista previa a escala 0.5, ejecuta QC sobre tus propios resultados, corrige todos los hallazgos (vuelve a renderizar solo las escenas modificadas) antes de informar.
• Etapa 5 — Final: renderiza a resolución completa UNA VEZ; ejecuta bash scripts/check_output.sh out/<slug>-final.mp4; muestra el archivo + informe de QC en la sesión.

Renderizado rápido (tubería bloqueada)

• Renderizado POR ESCENA: out/scenes/scene-N.mp4; combina con la concatenación de FFmpeg -c copy (los parámetros de códec/resolución/fps DEBEN ser idénticos entre escenas, de lo contrario la combinación se rompe).
• --concurrency = número de núcleos de CPU de la sesión (verifica nproc), no el predeterminado.
• La vista previa siempre es --scale=0.5; resolución completa 1080×1920 solo en la Etapa 5.
• Mantén el costo por fotograma bajo: geometría primitiva, instanciación para elementos repetitivos.

Validación y QC (fallo cerrado)

• Validador de línea de tiempo (scripts/validate_timeline.py): verifica estructura, rango, mapeo. DEBE pasar antes de la Etapa 2.
• Validador de estilo (scripts/validate_style.py): verifica que la escena renderizada coincida con el bloqueo de estilo (paleta, rig de luz, material, distancia de cámara). Se ejecuta en la Etapa 3 sobre fotogramas fijos.
• QC de texto: scripts/check_text_cutoff.py — verifica que ningún texto de overlay DOM esté cortado (usando measureText). Todos los textos DEBEN pasar.
• QC de audio: verifica que total_duration_s de timeline.json coincida con la duración real del archivo de audio dentro de ±0,3 s; normalización LUFS; pico.
• Cada etapa debe ser autoevaluada por la sesión (Modo Residencia) o aprobada por el usuario (Modo clásico) antes de continuar. No se permite saltar.

Informe final

Al final de la sesión (después de la Etapa 5 o después de un bloqueador duro), la sesión DEBE producir un informe que contenga:

• Resumen de la línea de tiempo (número de oraciones, escenas, duración total)
• Lista de materiales (origen de la narración, origen de la música)
• Resultados de validación (PASS/FAIL de cada validador)
• Hoja de contactos de fotogramas fijos (imagen)
• Lista de verificación de QC (todos los ítems, estado)
• Notas de corrección (si se realizaron correcciones durante la sesión)
• Enlace al archivo de salida final

Modo Residencia — Cómo Funciona

El Modo Residencia es el flujo de trabajo predeterminado de esta habilidad (v3.0). En este modo, la sesión procede de forma autónoma a través de las etapas de producción:

1. Sin espera de aprobación: las Compuertas 1 y 2 se ejecutan internamente (la sesión se autoevalúa contra los criterios de la habilidad).
2. Corrección automática: si se encuentran problemas en la etapa de fotogramas fijos, la sesión intenta corregirlos (máx. 2 intentos por escena).
3. Decisiones basadas en el prompt: el prompt contiene un Bloque de Decisión (predeterminado: acelerar narración larga, marcar hechos no verificados).
4. Preguntas en lote: todas las preguntas que surjan del Bloque de Decisión se plantean en un solo mensaje antes de la Etapa 2. No se permiten preguntas a mitad de camino.
5. Bloqueadores duros: la sesión solo se detiene para Bloqueadores Duros (material faltante, transcripción imposible, duración fuera de rango incluso después de atempo).
6. Informe completo: al final, se genera un informe que documenta todo el proceso, las decisiones y los resultados.

Si el usuario prefiere el flujo de trabajo clásico (con aprobaciones), debe indicar "Modo Residencia: NO" al inicio del prompt. En ese caso, se aplicarán las compuertas de aprobación clásicas con flexibilización basada en evidencia.

Nota importante sobre la localización al español

Esta habilidad ha sido localizada al español. La narración se realizará en español, y los subtítulos, las etiquetas y los textos en pantalla que aparecen en los Modos A, B y C deben ser en español (a menos que el usuario indique lo contrario). Los términos técnicos y nombres de series pueden mantenerse en inglés si son internacionalmente reconocidos, pero todo el contenido educativo y las explicaciones deben estar en español. La música y los archivos de audio deben ser proporcionados por el usuario en la carpeta public/.