iwyusdaz/chalkreel

chalkreel — objetivo de aprendizaje -> video explicativo accesible

Estás produciendo un video explicativo de aprendizaje. A diferencia de los explicadores optimizados para engagement, un video de aprendizaje parte de un objetivo medible, gestiona la carga cognitiva de forma intencionada (principios multimedia de Mayer) y entrega elementos de accesibilidad — subtítulos, transcripción, notas de descripción de audio — como entregables de primera clase, no como ideas posteriores. Cada afirmación factual en la narración se traza hasta una fuente.

Todo lo que el espectador escuche también debe poder verse o leerse. Todo lo que se le diga al estudiante debe ser trazable. Nada se entrega sin una compuerta humana.

Reglas estrictas

1. No hay modelos de video generativos. No hay metraje de archivo. No hay generadores de imágenes para el contenido de las escenas. Los fotogramas se dibujan con código (componentes Remotion, SVG, CSS). Esto mantiene cada fotograma revisable, comparable y reproducible.
2. Cuatro compuertas humanas. Nunca avances más allá de una compuerta sin la aprobación explícita registrada en el registro del proyecto: COMPUERTA 1 objetivo + mapa de latidos, COMPUERTA 2 guión de narración, COMPUERTA 3 estilo visual, COMPUERTA 4 corte final.
3. Etiqueta todo lo sintético. Los datos de ejemplo construidos, las temporizaciones simuladas y los resultados de revisión del agente se etiquetan como tales en el propio archivo. Nunca presentes un artefacto seco como si fuera una salida real renderizada/TTS.
4. Afirmaciones antes que guión. Las notas de investigación con afirmaciones con fuente existen antes de que se escriba la narración, y ningún número entra en el guión sin una fila en el libro de contabilidad.
5. TTS local primero. La voz predeterminada es kokoro-82m (local, gratuita). Se admite TTS propio; nunca invoques un TTS en la nube sin la clave configurada por el usuario. No hay modelos locales aparte del TTS que elija el usuario.

Entradas

objetivo:      una oración medible (ABCD — la compuerta de objetivo lo exige)
audiencia:     quién aprende y su conocimiento previo asumido
duración:      duración objetivo (por defecto 60–120 s)
idioma:        idioma de la narración (por defecto en)

Rechaza temas. "Un video sobre la fotosíntesis" no es una entrada; ejecuta scripts/objective-gate.mjs e itera con el usuario hasta que pase.

Pipeline

objetivo + audiencia + conocimiento previo + duración + idioma
  |
  +-- 1. COMPUERTA DE OBJETIVO    objective-gate.mjs; reescribe tema -> objetivo ABCD;
  |                               redacción visible para el estudiante "serás capaz de...";
  |                               mapa de latidos segmentado según segmentación de Mayer (latidos de 10-30 s)
  |                               << COMPUERTA 1: usuario aprueba objetivo + mapa de latidos
  +-- 2. INVESTIGACIÓN            extrae afirmaciones, encuentra fuentes, escribe libro de contabilidad
  |                               (ids estilo claim-001; fuentes con título/editorial/año;
  |                               redacción vaga preferida sobre estadísticas inventadas)
  +-- 3. NARRACIÓN                guión por presupuesto de segmento; pase de lint humanizador
  |                               (scripts/lint-narration.mjs debe salir con 0);
  |                               verificación de nivel de lectura vs. audiencia
  |                               << COMPUERTA 2: usuario aprueba guión
  +-- 4. COMPARATIVA DE ESTILOS   renderiza el MISMO latido en 2-3 variantes de fondo/tema
  |                               con la plantilla; el usuario elige visualmente
  |                               << COMPUERTA 3: usuario elige un estilo
  +-- 5. CONSTRUCCIÓN             un componente Remotion por segmento (template/);
  |                               TTS con marcas de tiempo por palabra (kokoro-82m por defecto, BYO ok);
  |                               construye timing JSON {segments[].words[{w,start,end}]}
  +-- 6. ACCESIBILIDAD            make-srt.mjs (SRT sincronizado por palabra), make-transcript.mjs
  |                               (transcripción HTML), notas de descripción de audio por
  |                               segmento, luego a11y-lint.mjs DEBE pasar
  +-- 7. CONTROL DE CALIDAD       puntúa los fotogramas renderizados + el guión contra los
  |                               criterios escritos a continuación; escribe qc-report.md con etiquetas de método
  |                               << COMPUERTA 4: usuario revisa el corte final
  +-- entregar: video.mp4 + .srt + transcript.html + instructor-notes.md
      + libro de contabilidad + rastro documental completo (objetivo, investigación, narración,
      storyboard, temporización, informe QC)

Presupuestos de segmento

• 10–30 s por segmento (segmentación de Mayer; límite máximo de 30 s sin anulación del usuario).
• ~145 palabras por 60 s de narración; una idea por segmento.
• Texto en pantalla: solo etiquetas y frases cortas (2–7 palabras), nunca la narración leída textualmente (principio de redundancia).
• Cada segmento define: narración, un tipo de escena, texto en pantalla, nota de descripción de audio, IDs de afirmaciones.

Valores predeterminados de TTS

• Predeterminado: kokoro-82m, local. Voz: af_heart (o la elección del usuario). Velocidad 1.0.
• Captura marcas de tiempo por palabra del TTS/alineador en el JSON de temporización. Si el TTS no puede emitirlas, alinea con un alineador forzado; nunca adivines las temporizaciones — una alineación adivinada hace que los subtítulos se desvíen, y la verificación de ida y vuelta detectará texto no coincidente pero no tiempos desplazados.
• TTS propio: cualquier motor que devuelva marcas de tiempo a nivel de palabra; documenta el motor y la voz en el registro del proyecto.

Scripts (todos independientes, node >=18, sin dependencias)

Script	Propósito	Salida 0 significa
scripts/objective-gate.mjs "<objetivo>"	valida el objetivo ABCD	el objetivo es medible
scripts/lint-narration.mjs <script.txt>	verificador de marcas de escritura de IA (ejecutar antes de TTS)	el guión suena lo suficientemente humano como para grabarlo
scripts/make-srt.mjs <timing.json> --out x.srt	SRT sincronizado por palabra desde el JSON de temporización	SRT escrito
scripts/make-transcript.mjs --timing <timing.json> --storyboard <sb.json> --out t.html	página de transcripción accesible	HTML escrito
scripts/a11y-lint.mjs <storyboard.json>	"sin información solo en audio" + verificación de entregables	cada hecho de la narración está en pantalla o en notas de transcripción/AD

Los fixtures negativos viven en examples/ (bad-narration.txt, bad-storyboard.json) — siempre verifica una configuración nueva ejecutando los lints sobre ellos y confirmando que FALLAN.

Formatos de archivo

timing.json — marcas de tiempo por palabra (de la alineación TTS):

{ "video": { "title": "...", "fps": 30 },
  "segments": [ { "id": "seg-01", "text": "...", "start": 0.0,
    "words": [ { "w": "Cerca", "start": 0.1, "end": 0.34 } ] } ] }

storyboard.json — un objeto por segmento:

{ "video": { "title": "...", "fps": 30, "width": 1920, "height": 1080,
    "srtEmitted": true, "transcriptEmitted": true, "claimsLedger": "ruta" },
  "segments": [ { "id": "seg-01", "title": "Hook", "sceneKind": "statement",
    "startSec": 0, "durationSec": 18.2, "narration": "...",
    "visual": { "backdrop": "chalkboard", "description": "...",
                "onScreenText": [ "Recuerda: no solo releer" ] },
    "audioDescriptionNote": "...", "claims": [] } ] }

sceneKind se asigna a un componente de plantilla: statement, definition, timeline, cycle, list, caption. Agrega nuevos tipos en la plantilla, no como componentes únicos dentro de un proyecto.

Paquete de criterios de control de calidad (evalúa la salida renderizada CONTRA ESTO, por escrito)

Un agente de control de calidad no "ve" el video y opina. Evalúa cada criterio como PASA/FALLA con una observación citada. Las verificaciones a nivel de fotograma necesitan fotogramas renderizados; las verificaciones a nivel de guión se ejecutan sobre los artefactos. Escribe el resultado en qc-report.md y etiqueta el método de revisión (ej. "Revisión heurística del agente").

A nivel de guión (ejecutar siempre)

1. Alineación con el objetivo — cada segmento avanza hacia el objetivo aprobado; cualquier cosa que no lo haga se elimina (principio de coherencia aplicado a los objetivos).
2. Trazabilidad de afirmaciones — cada número, fecha o hallazgo nombrado en la narración tiene una fila en el libro de contabilidad con una fuente. Fallo si hay algún hecho huérfano.
3. Lint de narración — lint-narration.mjs sale con 0.
4. Nivel de lectura — las oraciones promedian menos de ~17 palabras; ningún término técnico sin explicar; verbos concretos sobre abstracciones.
5. Paquete de accesibilidad — a11y-lint.mjs sale con 0; existen SRT y transcripción; nota de AD presente para cada segmento.

A nivel de fotograma (ejecutar sobre fotogramas renderizados o capturas de pantalla por segmento)

6. Señalización — el término/número clave del momento está visualmente resaltado (subrayado de tiza, color, flecha) exactamente mientras se narra.
7. Coherencia — nada decorativo en pantalla; cada elemento se corresponde con una idea narrada; sin música de fondo a menos que el usuario lo solicite.
8. Redundancia — el texto en pantalla no duplica la narración textualmente; son etiquetas y frases cortas.
9. Contigüidad espacial — las etiquetas están adyacentes a la cosa que describen; sin búsquedas de leyenda a gráfico dentro de un fotograma.
10. Contigüidad temporal — la revelación de un elemento está sincronizada con su línea de narración (verificar contra timing.json), no se muestra antes ni después.
11. Legibilidad — las líneas de tiza contrastan con el fondo (>= 4,5:1 para equivalentes de texto en pantalla); nada recortado a 1920x1080 o 1280x720.
12. Presupuesto de movimiento — las animaciones se estabilizan en menos de 1,2 s; nada se mueve durante una oración que introduce una idea diferente.

Evalúa cada PASA/FALLA con evidencia. Cualquier FALLA en 1–5 bloquea la COMPUERTA 4. Cualquier FALLA en 6–12 requiere una corrección y una re-renderización de ese segmento, o una aceptación explícita del usuario.

Estilos predeterminados (comparativa COMPUERTA 3)

• Fondo: chalkboard (pizarra verde oscuro profundo, textura sutil, viñeta suave). Alternativas para la comparativa: paper (blanco cálido, líneas de tinta), night (casi negro, un solo color de acento).
• Paleta: blanco tiza primario, un acento (ámbar #FFC66D) para resaltados. Resalta solo lo que requiera la señalización.
• Tipografía: grande (>= 64 px a 1080p), alto contraste; subtítulos centrados en la parte inferior con placa translúcida, máximo 2 líneas / 42 caracteres por línea.
• Respeta al espectador: sin parpadeos (> 3 parpadeos/s prohibidos), el movimiento se estabiliza rápido, la barra de progreso muestra la posición del capítulo.

Rastro documental (registra todo)

01-objective.md (+ salida de compuerta)     05-timing.json
02-research-notes.md                         06-subtitles.srt
03-narration.md                              07-claims-ledger.md
04-storyboard.json                           08-qc-report.md

El rastro documental es un producto tanto como el video: es lo que hace que el pipeline sea auditable por otro diseñador instruccional.

Límites honestos (menciónalos en el registro del proyecto)

• El control de calidad del agente es una revisión heurística por un modelo, no un respaldo experto.
• No se afirma que una salida esté "validada instruccionalmente" — eso requiere pruebas con estudiantes que este skill no realiza.
• Los subtítulos sincronizados por palabra son tan buenos como la alineación TTS; verifica 10 señales contra el audio antes de la COMPUERTA 4.
• Licencias de voz: las voces de kokoro-82m tienen sus propios términos de uso; verifica antes de la distribución comercial.

Atribución

Inspiración a nivel de método, sin código copiado: anything2explainer (PolyForm Noncommercial — método solamente, ver ATTRIBUTION.md de este repositorio), el patrón de flujo de aprobación con compuertas de vox-director (MIT) y el concepto de lista de verificación de marcas de escritura de IA de blader/humanizer y Wikipedia's "Signs of AI writing" (el lint de este repositorio es una implementación independiente).