Communitygithub.com

paper-explainer

Convierte un artículo académico (arXiv/PDF), un informe técnico extenso o una revisión de múltiples artículos en un video explicativo horizontal de 6 a 8 minutos en chino.

¿Qué es paper-explainer?

Esta habilidad está diseñada para transformar contenido académico denso en videos explicativos atractivos y de alta calidad, dirigidos a una audiencia con conocimientos técnicos pero no familiarizada con el artículo en cuestión. El proceso cubre desde la selección del tema y la lectura profunda hasta la redacción del guion, la verificación de hechos, la planificación de tomas, la locución y la renderización, todo ello con un riguroso conjunto de reglas para evitar iteraciones de retrabajo. Soporta plataformas como Claude Code y Cursor, aprovechando agentes de subproceso para tareas paralelas (prueba de escucha, verificación de hechos, revisión). El flujo de trabajo está altamente estructurado: primero se asegura la lógica y el guion, luego se crean los guiones gráficos y la locución, y solo al final se realiza la producción visual y la renderización a través de WebCodecs en Chrome. El resultado es un video de 6–8 minutos (1920×1080, 30fps, H.264+AAC) que explica claramente qué modifica el artículo, por qué funciona, qué podemos aprender y cómo reproducirlo con un ejemplo concreto.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ningcodes/paper-explainer-skill/tree/HEAD/skill

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Artículo → Video explicativo

Audiencia objetivo: Personas con formación técnica, pero que no han leído este artículo. Al terminar, deben poder explicar: qué modifica, por qué es efectivo, qué podemos aprender, y poder reproducir lo que hace con un ejemplo concreto. No se deducen fórmulas, se explica la lógica.

Especificaciones finales: Horizontal 1920×1080, 30fps, H.264 + AAC, duración de 6–8 minutos, priorizando claridad (se acepta hasta 10 minutos aproximadamente). El final incluye créditos y llamada a la acción que son elementos configurables en film.json (outro), no escrito de forma fija.

Esta habilidad se complementa con el código del repositorio: engine/ (cáscara del lienzo, papel físico, tarjeta de estilo ④, página de renderizado WebCodecs, mezcla y sincronización, alineación de locución, música y efectos de sonido), examples/demo (ejemplo mínimo de 25 segundos), examples/always-on (ejemplo completo de un episodio). Documentación de la interfaz: engine/README.md.


1. Reglas estrictas (cada una proviene de retrabajos, en caso de conflicto, esta es la referencia)

  1. Antes de empezar, cargar el texto completo de esta habilidad, y en el brief enviado a los subagentes, pegar el texto original de la lista de verificación, no repetir de memoria. Para briefs de escritura y revisión, también pegar el texto completo de references/voiceover-selfcheck.md. La primera línea del brief debe ser la ruta de esta habilidad, solicitando leer el texto completo primero.
  2. El orden no puede invertirse: Cadena lógica → bloquear locución → storyboard (tabla de planificación de tomas) → locución → corte bruto para ver el flujo → efectos especiales / refinamiento artístico → portada al final. Si la locución no está bloqueada, no se hacen imágenes; si el storyboard y el guion no están bloqueados, no se genera ningún material aparte de la locución (como avatares opcionales). Primero definir el estilo y luego cambiar el contenido = retrabajo.
  3. Quien escribe no aprueba. Antes de enviar la locución a revisión, debe pasar una prueba de «escuchar una sola vez» independiente y una verificación de hechos; antes de que el autor vea el producto final, un agente que no haya participado en la producción debe ver el video dinámico completo y cotejarlo con references/review-checklist.md, entregando el informe de revisión junto con el video.
  4. Solo hay un camino para la renderización: render(t) fotograma a fotograma en una página de Chrome local + codificación hardware WebCodecs (engine/common/shell-wc.html). En el brief solo se escribe esta ruta, sin dar la opción «captura de pantalla fotograma a fotograma headless → ffmpeg». Antes de renderizar, probar 10 segundos de ms/fotograma y el renderizador WebGL; si el renderizador es software (SwiftShader / llvmpipe), detenerse e informar, no cambiar a otro método de renderizado. La síntesis no debe usar geq. La renderización se realiza en agentes secundarios y segmentos independientes en paralelo, mientras la sesión principal permanece disponible para dialogar en cualquier momento.
  5. Locución: Cualquier TTS que genere wav → engine/voice/align.py para alinear. Las frases leídas incorrectamente se regeneran individualmente, no se modifican los tiempos manualmente.
  6. El fotograma 0 ya debe tener contenido, los primeros 20–30 segundos son los más importantes. El gancho directo: nombre de autoridad + el resultado más contraintuitivo + la confusión del espectador (o «te explico X de una vez»), sin jugar con el suspense.
  7. La duración sigue a la claridad, se acepta hasta aproximadamente 10 minutos; las pausas entre frases deben ser ajustadas (ver sección 10).
  8. Imagen: Legibilidad primero, estilo editorial blanco cálido / beige; por defecto, tarjeta de estilo ④ Periódico (ya utilizada en episodios publicados). Gusta la cámara continua, el zoom en páginas de artículos, la mezcla suave de música de fondo. No se usa el fondo oscuro al estilo 3Blue1Brown como fondo general del video, ni el estilo de cartel de cuadrícula suizo; no se hacen cortes duros de diapositivas estáticas.
  9. Aparición opcional: La imagen principal es el contenido. Si se quiere incluir la imagen del autor, solo como ventana pequeña en la esquina inferior derecha, solo al principio / en los capítulos / al final, sin mostrar un rostro grande; la locución no se convierte en letras grandes.
  10. Final: Pregunta de discusión (relacionada con el mecanismo central de este episodio, que se pueda responder en una o dos frases) → Créditos + llamada a la acción (outro de film.json); no se avanza el próximo episodio.
  11. Texto: Profesional y conciso, con proceso de razonamiento, pocos emojis; no usar «no es... sino...»; no escribir pruebas no realizadas; separar las afirmaciones oficiales, las mediciones reales y las inferencias. La locución se envía por segmentos para que el autor la revise. La lista de verificación frase por frase está en references/voiceover-selfcheck.md (prioritaria sobre cualquier redacción anterior en este archivo).
  12. Basarse en prácticas verificadas para hacer el plan, no inventar nuevos formatos. Para tomas nuevas, buscar primero escrituras similares en examples/.

Pasos que el autor debe hacer personalmente (el agente se detiene aquí, explica claramente qué debe hacer el autor y espera confirmación): Revisar la cadena lógica y la locución (sección 7), generar el wav de locución (sección 9, a menos que el autor ya haya proporcionado un método TTS utilizable), ver la tabla de planificación de tomas (sección 8), ver la muestra y el producto final (secciones 11–12), y publicar. Si el autor no ha terminado de revisar, el mismo episodio no pasa a la siguiente etapa (otros episodios pueden continuar).

Ahorrar tokens: Cada versión enviada a revisión tiene como máximo 1 ronda de verificación de hechos y 1 ronda de prueba a ciegas; los problemas pequeños se acumulan y se corrigen junto con las opiniones del autor. Para buscar y organizar archivos, usar modelos pequeños; para escribir, juzgar hechos y revisar, usar modelos fuertes. El contenido grande se escribe en archivos, solo se devuelve la ruta y la conclusión.


2. Resumen del flujo

  1. Selección y filtrado del tema: Resumen del artículo + popularidad del mismo tema en tu plataforma de publicación; requisito mínimo: el artículo tiene un estudio de caso completo.
  2. Lectura profunda → Tarjeta del artículo (references/paper-card.md).
  3. Encontrar el gancho.
  4. Esquema de tres preguntas + ejemplo transversal + cadena de preguntas del espectador (references/question-chain.md).
  5. Redactar locución (sección 4 + references/voiceover-selfcheck.md).
  6. Prueba de «escuchar una sola vez» a ciegas (dos roles, subagente, references/listen-test-brief.md) → Complementar guion.
  7. Verificación de hechos independiente + abogado del diablo (subagente, en paralelo, references/factcheck-brief.md) → Después de modificar el guion, volver a probar la comprensión.
  8. El autor revisa la locución por segmentos (una página de cadena lógica + locución segmentada, esperar confirmación).
  9. Storyboard: Seleccionar tarjeta de estilo + tabla de planificación de tomas (references/shot-plan.md) + barra de progreso de la columna superior → (El autor ve la tabla de planificación de tomas).
  10. Locución (cualquier TTS).
  11. Alineación y pistas de audio (voz humana + música de fondo + efectos de sonido).
  12. Componentes comunes → Escribir scene.js por capítulo en paralelo → Muestra → Revisión independiente → Video completo → Refinamiento artístico por capítulo → Nueva revisión → Revisión .1.
  13. Autocomprobación de fotogramas perdidos → Entrega; después de que el autor vea y plantee preguntas, reflexionar primero antes de modificar.

Esta habilidad también se aplica a resúmenes de «te lo explico todo de una vez» con múltiples fuentes

Las revisiones / charlas en serie de múltiples artículos también siguen los pasos 0–12. Consecuencias de no cargar esta habilidad: frases llenas de «institución + año + número» leídas de una vez, cada capítulo habla de lo suyo, sin páginas reales de artículos, sin animaciones ni música, sin pruebas de comprensión, todo el video requiere retrabajo. Adaptaciones:

  • Usar un ejemplo transversal + un diagrama madre para unir todo el video; cada capítulo utiliza el mismo conjunto de palabras para repasar el diagrama madre. El diagrama madre prioriza la clasificación existente en el artículo, y el texto principal se divide en capítulos según esta clasificación, sin crear un marco propio.
  • Cada capítulo solo cuenta una historia principal y un número principal; el resto de números se colocan en la tarjeta de fuente en pantalla, la locución solo dice «X descubrió».
  • Progresión de capítulos (de lo superficial a lo profundo / orden de la línea de producción), el último capítulo retoma el gancho del principio.
  • Las instituciones y los años no entran en frases largas de la locución; una frase, una información.
  • La autoridad de la revisión proviene de «artículo + código abierto de grandes empresas»; el gancho solo deja un sujeto.

0. Selección y filtrado del tema

  • Cuando hay múltiples candidatos, ver primero la visión general de IA del artículo (por ejemplo, alphaXiv), solo para decidir si leer en profundidad, no como fuente de hechos.
  • Verificar la popularidad del mismo tema en la plataforma donde vas a publicar: si alguien lo ha explicado a fondo, cómo ha sido la acogida de esas explicaciones. La popularidad académica (me gusta, citas, número de artículos) no es igual a la popularidad en la plataforma; lo que suele ser popular en la plataforma es «concepto bien explicado», «un solo artículo es suficiente» y nombres de personas/empresas. Sin evidencia, no decir «muy popular últimamente».
  • Requisito mínimo: el artículo debe tener un estudio de caso completo (entrada → qué se hizo en cada capa → puntuación antes y después), que pueda sostener «recorrerlo». Si no, elegir con precaución.
  • Al seleccionar el tema, decidir cuatro cosas: la pregunta del lector, nuestra afirmación, la evidencia y la entrega (qué se lleva el espectador al terminar).

1. Lectura profunda: Tarjeta del artículo

  • Obtener el texto completo: https://arxiv.org/pdf/<id>; si es posible, obtener también el código fuente TeX (/src/<id>, más preciso para números y notas de figuras, las imágenes originales se pueden usar directamente); si la descarga del PDF falla, leer primero arxiv.org/html/<id>. Solo descargar materiales que tengas derecho a usar, anotar la licencia (CC BY, etc.).
  • PDF: pdftoppm -r 150 para renderizar todas las páginas y ver el contenido; las páginas y partes que se usen en las imágenes deben tener 300dpi, y las imágenes que se vayan a ampliar deben tener 720dpi de renderizado vectorial (el zoom de la cámara será de 2–3 veces, 150dpi o fotogramas de video se verán borrosos). Para los cuadros de palabras (para localizar el resaltador), usar pdftotext -bbox; puede fallar en ciertas versiones de poppler, usar PyMuPDF (ver examples/demo/get-paper.sh, recordar la normalización NFKC, de lo contrario las ligaduras como fi no se encontrarán en las frases). Para el texto original de la página web, usar engine/tools/capture.mjs (captura de pantalla 3× + cuadros de frases).
  • Leer todo el texto principal, apéndices, notas de figuras. Los apéndices, ablaciones, casos fallidos y limitaciones deben revisarse por separado. Las indicaciones, reglas de juicio y pseudocódigo en los apéndices deben leerse: el mecanismo central «en base a qué se juzga» a menudo solo se escribe aquí.
  • La tarjeta del artículo se escribe según los 12 elementos de references/paper-card.md. Para el desglose de un solo artículo, primero tomar la imagen central y la estructura del propio artículo original, no aplicar su propio marco.

2–3. Gancho, tres preguntas, ejemplo transversal, cadena de preguntas del espectador

Gancho (cada frase ≤3 segundos, una frase solo una información):

  1. Poner el nombre de autoridad abreviado al principio («Nuevo artículo de Google:»).
  2. Inmediatamente después, el punto más único y contraintuitivo de este artículo, describiendo la escena en lenguaje sencillo («Ayuda a los productores a conciliar varias hojas de programación, personal y presupuesto, y la puntuación sube de 43 a 78»); para un solo caso, mantener la limitación «un caso real de...», no puede decirse como un promedio.
  3. Se puede usar una frase corta de giro para terminar («El modelo no movió ni un solo peso.»).
  4. Luego dar el nombre completo y la institución, y añadir una frase de avance («A continuación, desglosaremos juntos su arquitectura completa»).
  • No poner múltiples cantidades con el mismo número en una misma frase («8B», «una setenta y unaava parte», «128.000» se pueden oír mal).
  • En el gancho, no obligar al espectador a entender primero un término técnico para poder entender: primero usar lenguaje sencillo para describir el evento, la frase original en inglés solo se muestra en pantalla; los términos que el espectador no conoce pueden aparecer, pero deben definirse inmediatamente en el siguiente párrafo.
  • Verificar los objetos de comparación en el gancho, y escribir las condiciones limitantes; cada palabra clave en el gancho y el título debe tener un párrafo en el texto principal que responda directamente (si se dice «autoevolución», debe haber un párrafo «¿Esto se considera autoevolución? ¿Dónde se refleja?»).
  • El fotograma 0 debe ser el título principal a pantalla completa o la imagen más contraintuitiva (132px Songti, ya en su lugar, no empujado desde arriba en blanco); los números clave deben aparecer por primera vez cuando la locución los mencione y convertirse en el protagonista de ese segmento (≥200px), no parpadear al principio.

Extensión de las tres preguntas: ¿Qué modifica (nivel)? | ¿Por qué funciona (idea del autor + mecanismo + por qué no fallará, ocupa más de la mitad) | ¿Qué podemos aprender?

Ejemplo transversal: Elegir un ejemplo propio del artículo, que cubra cada capa, y que todos los mecanismos vuelvan a él.

Cadena de preguntas del espectador (obligatorio antes de escribir el guion): Escribir por párrafo «¿Qué pregunta se hará el espectador al oír esto? → Cómo responder en la siguiente frase». La plantilla y los elementos que deben cubrirse están en references/question-chain.md. La cadena de preguntas se entrega junto con la cadena lógica para que el autor las revise. Debe haber una sección de «agua fría».

4. Locución

Estructura: Gancho → Pregunta (alguien anterior nombra un trabajo específico) → Si fueras el autor → Una frase sobre la esencia → Arquitectura (explicar por grupos según el artículo) → Recorrer con el ejemplo del artículo (paso a paso, cada paso con un «por qué») → Tarjeta de resumen (una frase que unifique todos los pasos) → Aclaración de conceptos del título → Resultados (pregunta → respuesta) → Agua fría (numerada) → ¿Qué podemos aprender? → Final (pregunta de discusión → Créditos + llamada a la acción).

Reglas estrictas para la claridad

  • Solo dar el nombre no es explicación. Cada término / mecanismo, la primera vez que aparece, debe tener una definición operativa en una frase: quién, mira qué, cómo juzga. Traducir términos del artículo no es explicar.
  • No saltar pasos. Debe haber una conexión causal entre las acciones («Al ver estos dos problemas → modificar el archivo Harness»).
  • Primero lo concreto, luego lo abstracto. Primero decir qué archivos se modificaron y qué se escribió, luego decir a qué categoría pertenece y cómo se llama.
  • Los conceptos nuevos deben prepararse antes de usarse. No permitir que palabras como «candidato» o «selección ciega» aparezcan por primera vez en la sección de agua fría.
  • La evidencia se coloca después de que se hayan explicado los pasos, no intercalar números en medio de los pasos; al hablar de experimentos de control, primero decir cómo se hizo el grupo de control, luego el resultado.
  • Los roles deben estar claros: cuando hay múltiples modelos, decir explícitamente «Aquí hay dos modelos: el que trabaja es X, el que modifica Harness es Y»; aclarar si los pesos cambian o no, si hay aprendizaje por refuerzo.
  • La primera vez que aparezca un nombre de benchmark, primero explicar qué es; las unidades deben ser consistentes en todo el video («puntos» no mezclar con «puntos porcentuales»); «ello» no puede ser ambiguo.
  • En la imagen, solo usar los nombres que aparecen en la locución.

Estilo

  • Los términos técnicos en inglés que el espectador conoce (Harness, agent, diff) se usan directamente, con un solo nombre en todo el video, sin crear traducciones al chino. Usar las palabras originales del sector (entorno RL, trayectoria, verificador), sin crear metáforas propias.
  • Describir la escena en lenguaje sencillo; los nombres de tareas y benchmarks primero se traducen a una frase en lenguaje sencillo.
  • Si fueras el autor: después de preguntar «¿Qué pensarías?», dejar una pausa de 1 segundo (la imagen muestra «?»), luego decir «Supongo...». Las inferencias deben decir «Supongo».
  • Una frase sobre la esencia: debe poder ser repetida, seguida de una frase complementaria; no escribir frases cortas de eslogan (ver lista de verificación).
  • Las listas largas se explican según la propia agrupación del artículo, tomando como referencia la tabla original del artículo. Explicar directamente el artículo, no forzar la relación con las herramientas del espectador.
  • Recorrido: dividir en «Primer paso... Segundo paso...», cada paso aclarar quién tiene qué y hace qué, y añadir un «por qué». Los casos seleccionados deben explicar que «el artículo eligió este para mostrar, el promedio no es tan grande».
  • Cada mecanismo se explica con «cómo se hacía originalmente → qué problema había → cómo se modificó → por qué es mejor».
  • Los mecanismos técnicos deben ir acompañados de la comparación de código más pequeña posible antes y después; si hay texto original, usarlo (marcar «Extracto original · con omisiones»), si no, escribir pseudocódigo marcado «Ilustrativo».
  • Las analogías son solo un complemento, se colocan después del ejemplo. Hablar de los esquemas «probados pero no adoptados». Antes de eliminar información, preguntarse: si se elimina, ¿el espectador podría entender mal?
  • Sección de resultados: cada número responde a una pregunta, no leer un boletín de calificaciones; no apretar varios números en una misma frase. Cuando el mismo «máximo/mayor» provenga de diferentes comparaciones, especificar el alcance.
  • Sección de agua fría: «Hay tres reservas. Primera...»; la numeración completa; el material proviene del subagente abogado del diablo; al citar números favorables, también mencionar los desfavorables.
  • El final no es aleccionador: «¿Qué podemos aprender de esto?» «Mi mayor conclusión es...»; no usar frases imperativas como «Puedes llevarte».
  • Lenguaje oral, frases cortas; los subtítulos usan números arábigos.
  • Antes de enviar a revisión, revisar frase por frase con references/voiceover-selfcheck.md.

Número de palabras y ritmo: En general, aproximadamente 5.8 palabras/segundo (caracteres chinos, palabras en inglés y números cuentan como 1); 6–8 minutos ≈ 2000–2700 palabras. No confiar en acelerar, sino en reducir las pausas: las frases dentro del mismo párrafo se conectan en una sola respiración, solo se deja un pulso completo antes de las preguntas, los giros y los números clave; en el guion, usar «‖» para marcar las pausas de pulso completo (3–5 por capítulo). El objetivo es que las pausas ocupen el 10–12% del tiempo, con una pausa cada 5–6 segundos en promedio.

Formato del archivo de locución (lectura directa por el motor): Título del párrafo ## 00 · Nombre del párrafo, las frases que se leen, una por línea, comenzando con - ; las «> Tarjeta de pantalla» y el texto explicativo no se leen. ID de frase = s<sección>-<número>.

5–6. Prueba a ciegas + Verificación de hechos + Abogado del diablo (subagentes independientes, ejecución simultánea)

  • Prueba de escuchar una sola vez a ciegas: Dos roles (A no conoce el tema, B sí lo conoce), preguntas fijas, lista de malentendidos, puntuación. Umbral: A ≥ 8 puntos antes de pasar a la locución. Plantilla del brief en references/listen-test-brief.md. Los problemas mencionados en la prueba a ciegas deben tratarse uno por uno, no solo añadiendo una frase.
  • Verificación de hechos: Locución + artículo, verificar uno por uno números, fuerza de atribución, condiciones limitantes, objetos de comparación, si «inferencia» está marcada, si la agrupación coincide con la tabla original del artículo; generar must-fix (frases que se pueden reemplazar directamente).
  • Abogado del diablo: Solo dar el artículo, ponerse en la posición del revisor: la suposición más débil, si la comparación es justa, las celdas donde se pierde frente a la línea base, el tamaño de la muestra, contraejemplos, reproducibilidad en una semana; generar material para la sección de agua fría. Plantillas del brief para verificación y abogado del diablo en references/factcheck-brief.md.
  • Cada ronda de modificación del guion (especialmente después de la verificación, cuando se añaden números y condiciones limitantes), se debe volver a ejecutar la prueba a ciegas y la verificación de las frases modificadas. La precisión y la claridad deben verificarse juntas. El umbral se calibra según los guiones ya publicados.

7. El autor revisa la locución (detenerse y esperar confirmación)

  • Primero, dar una página con la cadena lógica: una línea por párrafo «Pregunta del espectador → Respuesta de este párrafo».
  • No pegar un bloque de texto completo: dividir por párrafos, con subtítulo + una frase de explicación + una frase de locución por línea; las conclusiones clave en negrita.
  • Revisar párrafo por párrafo, cada vez 1–3 párrafos, escribir «Ahora → Problema → Después de la modificación», hacer preguntas que se puedan responder directamente con sí/no, usar lenguaje sencillo con contexto; si hay una opción predeterminada razonable, hacerla y decir qué se ha hecho.
  • Anotar las preferencias del autor y actualizar esta habilidad al finalizar. Confirmar antes de pasar a la locución y la producción.

8. Storyboard: Tarjeta de estilo, tabla de planificación de tomas, barra de progreso

Tarjeta de estilo

Imagen = Esqueleto (estructura, movimiento de cámara, zoom en el artículo, lienzo grande, momento de transición, fijo en todo el video) + Tarjeta de estilo (paleta de colores, fuente, material, acción característica, estilo de elementos fijos). Cambiar de estilo solo cambia la tarjeta. Un video usa solo una tarjeta, y la serie mantiene la misma tarjeta. El ritmo sigue a la locución, y la composición de cada toma se rediseña según la tarjeta.

Tarjeta ④ Datos de periódico (por defecto, ya implementada en engine/common/style.js)

  • Paleta de colores: Papel #FFF1E5|Tinta #33302E|Secundario #66605C|Línea fina #CCC1B7|Rojo vino #990F3D = Después de la mejora / Números clave / Nuestras anotaciones|Azul Oxford #0F5499 = Línea base / Versión original|Cian #0D7680 = Coincidencia, conexión, ✓|Gris #B9AFA6 = Rechazado / Neutro|Panel color trigo #F2DFCE.
  • Fuentes: Título en chino Noto Serif SC Black (gancho 132px, título principal de capítulo/toma 92px, tarjetas 56–64px, interlineado 1.1); texto principal, etiquetas Noto Sans SC; números Inter 800 + tnum; etiqueta de columna (kicker) Bold 28–30px, con una línea corta rojo vino de 56×5 arriba. Las fuentes se descargan con style-cards/editorial/get-fonts.sh (OFL).
  • Maquetación: kicker + título grande + introducción + imagen; margen izquierdo 120px, cuadrícula de columna estricta; líneas finas de 1px y gruesas de 4px para jerarquizar; los gráficos solo dibujan líneas de cuadrícula horizontales, las etiquetas se colocan directamente sobre las líneas y puntos, sin usar leyendas; las notas = línea fina de guía + una frase corta de explicación; en cada pantalla, en la esquina inferior izquierda, una línea de fuente en gris (≥26px, dibujada uniformemente por chrome.js).
  • Acciones características: El título se empuja hacia arriba con una máscara línea por línea (easeOutQuart 0.55s, ED.maskLine); la introducción aparece desde la izquierda (wipeText); la línea fina crece desde la izquierda (growLine); el contorno se traza en sentido horario (strokeCW); la línea quebrada se dibuja de izquierda a derecha, los números se desplazan sincrónicamente; las frases clave se subrayan en rojo vino que aparece (underlineSweep); el zoom de la cámara en los gráficos es lento, 3–4%. Sin rebotes, sin brillos.
  • Transiciones: Entre capítulos, la página completa se desliza horizontalmente como pasando la página de un periódico (0.6s, dibujado uniformemente por chrome.js); dentro del capítulo, transformación continua / lienzo grande.
  • Elementos fijos: Barra de navegación de progreso de la columna superior del periódico, barra de subtítulos color trigo (Songti Bold 44px), línea de fuente, todo dibujado por engine/common/chrome.js, los capítulos no lo hacen por sí mismos.
  • Desventajas: Ligeramente frío, muchas palabras y niveles, las notas de 28px en el móvil siguen siendo pequeñas, eliminar si es posible.

Otras tarjetas (sin implementación adjunta en el repositorio, escribir style.js según sea necesario): ② Pizarra blanca dibujada a mano (estilo Excalidraw, adecuado para desglose de arquitectura); ① Animación matemática (estilo 3Blue1Brown, adecuado para deducción de fórmulas; la regla estricta 8 no recomienda fondo oscuro para todo el video, si realmente se usa, las páginas blancas del PDF sobre fondo oscuro deben reducir el brillo y añadir viñeta); ⑤ Desarrollador oscuro (adecuado para prácticas de ingeniería); ③ Nuevo brutalismo (adecuado para ganchos cortos, en videos largos cansa); A Explicación en blanco cálido (fondo #FAFAF7, naranja intenso #D4552A = mejora, azul pizarra #3E6A8A línea discontinua = línea base). Al cambiar de tarjeta: la animación no cambia, solo se modifica la personalidad de la transición (④ no rebota) y la apariencia de la transición entre capítulos; el significado del color es fijo: después de la mejora = color de énfasis de la tarjeta, línea base = color frío, rechazado = gris.

Reglas para párrafos de alta densidad (todas las tarjetas)

  1. Una pantalla, un protagonista: al hablar de alguien, que ocupe aproximadamente el 65% del ancho, zoom de cámara de 1.3–1.5 veces; al cambiar de protagonista, el anterior se convierte en una barra fina de resumen en la parte superior; solo alejar la cámara para ver el panorama general durante 1–2 segundos cuando se menciona la relación.
  2. Límite de texto: Además de los subtítulos, máximo aproximadamente 25 caracteres chinos por pantalla, máximo 4 bloques visuales; lo que la locución ya ha dicho no se escribe como etiqueta; un elemento tiene como máximo una etiqueta.
  3. No usar etiquetas dobles en chino e inglés; todo el texto que se deba leer debe tener ≥28px, la línea de fuente puede ser de 26px.
  4. No colocar recortes pequeños de artículos que no se puedan ver claramente: si se va a citar, entrar a tamaño completo para verlo claramente durante ≥1.5s, después de usar, solo dejar la línea de fuente o una pequeña marca.
  5. Moderación en los espacios reservados: la siguiente columna solo deja una línea fina + un pequeño encabezado de columna, sin cubrir grandes áreas con un esqueleto gris.
  6. En la parte superior, solo dejar una navegación: los pasos de este capítulo se convierten en subdivisiones de la barra de progreso, sin ocupar una línea separada.

Reglas de storyboard comunes a todas las tarjetas

  • Ritmo central: Página original → Resaltador amarillo rgba(250,199,117,0.7) que sigue a la locución de izquierda a derecha (con sonido de rotulador) → La página original permanece claramente visible durante ≥3 segundos (sin contar entrada, salida y zoom); antes de redibujar un gráfico, mostrar primero la imagen original y rodear los puntos a explicar.
  • Dos tipos de resaltador: Subrayar en la página original = amarillo (igual para todas las tarjetas); nuestras anotaciones (líneas de guía, círculos, subrayados) = color de énfasis de la tarjeta (④ rojo vino). El espectador distingue de un vistazo qué es original y qué es interpretación.
  • Tomas fijas: Toma de recorrido | Toma de comparación de código | Toma de tabla de niveles | Toma de la idea del autor (marcar «Inferencia») | Toma de experimento de control (cómo se hizo el grupo experimental vs el grupo de control) | Tarjeta de resumen.
  • Opacidad del fondo de los subtítulos ≥0.97, una línea ≤22 caracteres, coherente palabra por palabra con la locución.
  • Tamaño de fuente: el texto que se debe leer debe tener ≥28px; el texto que porta información usa color tinta, el gris solo para metadatos.
  • No dejar pantallas vacías: el contenido debe llenar aproximadamente el 70%; en ningún momento (incluyendo los fotogramas intermedios de transformación y cambio de toma) la mitad de la pantalla puede estar vacía más de 2 segundos; el fotograma de aterrizaje ya debe tener un protagonista.
  • El significado visual no debe inducir a error: una cadena de flechas verticales se puede leer como flujo de datos; lo que no fluye hacia el siguiente rol se coloca al lado, con un cuadro discontinuo y una etiqueta.
  • Los diagramas esquemáticos se marcan con «Ilustrativo»; los gráficos deben estar a escala, los ejes deben tener etiquetas; el logo del artículo se tapa, el nombre de la institución solo se escribe.
  • No usar relleno de ruido aleatorio (cuadrícula de grises de Math.random, códigos de barras, barras de esqueleto); los diagramas esquemáticos usan 3–4 niveles de tono suave.
  • Los títulos no deben superponerse (primero salir, luego entrar); antes de que aparezca una nueva imagen, la imagen antigua debe haber desaparecido por completo, sin dejar rastro.
  • Las capas que contienen texto no deben ampliar mapas de bits con scale()>1, sino redibujar cambiando el tamaño del diseño.
  • El 3D debe usar iluminación Three.js (cajas de esquinas redondeadas, material mate, luz hemisférica + luz principal + luz de relleno, sombras de contacto horneadas, renderizar a 2× y luego reducir); prohibido CSS 3D.

Zona segura (maquetar según esto durante la fase de storyboard)

  • y 0–64: Solo para la barra de progreso; el borde superior de los elementos del video debe ser ≥ y80, el contenido normal se coloca dentro de y 136–930, izquierda y derecha 96px.
  • y 900–940: Línea de fuente; y 952–1040: Barra de subtítulos. Los números y etiquetas de los gráficos no entran en estas dos franjas.
  • Avatar opcional: Esquina inferior derecha, aproximadamente x>1660, y>840; el contenido que se deba leer se coloca en x<1640, y<940.
  • No superponer la barra de progreso / avatar sobre el producto final después (solo se puede reducir el texto principal, y los subtítulos se hacen más pequeños).

Movimiento de cámara y transiciones (tres técnicas según el contenido)

Prohibido «fundir a negro a página en blanco y empezar desde cero» y la disolución cruzada de pantalla completa (como pasar diapositivas).

ContenidoTécnicaCómo hacerlo
Mayoría de las explicaciones: concepto, antecedentes, una frase sobre la esencia, resultados, agua fríaTransformación continua (estilo 3Blue1Brown)Los elementos de la siguiente toma crecen a partir de los de la toma anterior: la etiqueta vuela al centro y se convierte en el gráfico principal, las palabras del título se reducen y se integran en la fórmula, los subelementos emergen del elemento padre cuando la locución los menciona, ? se convierte en bombilla, la tarjeta de pregunta se convierte en tarjeta de agua fría. Cada elemento que entra debe tener un origen
Citar texto original del artículo, imágenes originalesZoom en el artículo (papel físico)El artículo es una hoja de papel real con sombra e inclinación de aproximadamente 1.5–2° (página PDF real, sin usar barras grises como marcadores de posición), normalmente encogido en una esquina; cuando se va a citar, se desliza de nuevo, se pasa la página (0.8s, dibujando el reverso del papel), se acerca 2–3 veces a la frase o la imagen, el resaltador pasa; al hablar de la imagen, esa parte de la imagen «flota» y sale volando para convertirse en una tarjeta animada redibujada. La captura de pantalla flotante se detiene al lado sin cubrir la tarjeta objetivo, y después de usarla, se guarda en un minimapa en la esquina. El zoom no debe superar la resolución de la captura de pantalla
Párrafos con pasos secuenciales (recorrido, flujo)Movimiento de cámara en lienzo grande (estilo Kurzgesagt)Los pasos se colocan de izquierda a derecha en un mismo lienzo grande; la cámara se desplaza horizontalmente entre los pasos (0.5–0.9s easeInOutCubic + whoosh); en la esquina, un minimapa del artículo. El esqueleto de la siguiente parada se prepara con antelación, y durante el desplazamiento ya se puede ver el destino; los elementos cortados fuera del encuadre se oscurecen. Solo se usa 1–2 segmentos por episodio, después de recorrer, alejar para ver el panorama general y luego recoger en una cadena de resumen
  • Esqueleto del video completo: Transformación continua como base → Cada vez que se menciona el artículo, zoom in → Al explicar pasos, lienzo grande → Entre grandes párrafos, usar transición de capítulo de ≤0.6s, solo 5–6 veces.
  • Sintaxis de animación: Entrada ease-out (④ sin rebote), subelementos con un desfase de 60–120ms; cámara easeInOutCubic; el mismo objeto a través de las tomas mantiene el mismo elemento (interpolación de posición/escala), no copiar uno nuevo con fade in; al escalar tarjetas, el contenido también se escala, no primero vaciar y luego escalar.
  • Desenfoque de movimiento: 12–16 muestras de igual peso, estela ≤ la mitad del desplazamiento de un solo fotograma y ≤40px; al hacer zoom, no añadir desenfoque direccional; al barrer la pantalla completa, desenfoque ≤0.35s.
  • Primero hacer la tabla de planificación de tomas (references/shot-plan.md): Cada párrafo debe indicar qué técnica usar, qué queda de la toma anterior, de qué elemento crece la siguiente toma, la fuente original, la palabra ancla. El autor debe verla antes de hacer las imágenes.

Barra de progreso de la columna superior

  • Dividir en 6–8 columnas según los párrafos de la locución, en la pantalla usar nombres de columna de periódico de dos caracteres (Introducción / Antecedentes / Idea / Desglose / Resultados / Dudas / Lecciones...); «Gancho» y «Agua fría» son nombres internos, no aparecen en pantalla.
  • Configuración en film.json del directorio del proyecto, en nav: [{ "n": "01", "name": "Introducción", "sections": ["00"] }, ...]; los tiempos de inicio y fin provienen de timeline.json. La columna actual en rojo vino Songti, el progreso ya emitido en línea rojo vino, los últimos 2 segundos de cada columna muestran un latido de avance de la siguiente columna. Implementación: engine/common/chrome.js.

Avatar (opcional)

Por defecto no se coloca. Si se coloca, usar una imagen que tengas derecho a usar, preparar una pista de avatar con fondo transparente, superponer en la última capa de la síntesis en la zona segura de la esquina inferior derecha; aparecer en todo el video o solo al principio / en los capítulos / al final; cuando la cámara se acerca al artículo (≥1.4 veces, o el texto original caería en la esquina inferior derecha), el avatar se desliza completamente fuera de la pantalla, y cuando se aleja, vuelve a deslizarse, cada vez 0.35s, sin semitransparencia. En la fase de storyboard, maquetar según la zona segura.

9. Locución (cualquier TTS)

  • Usar cualquier TTS que pueda generar wav / mp3 (página web comercial, API, modelo local), generar por segmentos (cada lote de aproximadamente ≤450 palabras, demasiado largo tiende a tragarse palabras). Los números y números de versión se escriben en su lectura en chino (cuarenta y tres punto uno, Opus cuatro punto ocho); los términos técnicos en inglés se mantienen; los subtítulos usan números arábigos (numfix en chapter.json).
  • Cada lote, primero hacer reconocimiento de voz para verificar las palabras iniciales y finales y los nombres propios en inglés (engine/voice/align.py asr), las frases leídas incorrectamente se regeneran individualmente y se escriben en overrides de voice.json.
  • Una práctica verificada (ejemplo): Una determinada página web de TTS comercial, seleccionar una voz de estilo de explicación técnica, velocidad 1x; cada segmento «pegar guion → añadir etiqueta de emoción automáticamente → generar → descargar la primera»; al usar automatización del navegador, abrir una nueva pestaña propia, no tocar la pestaña que el usuario está viendo. La voz y la cuenta son propias, no se distribuyen con el repositorio.
  • Antes de la entrega, transcribir segmento por segmento para verificar las palabras iniciales y finales de la voz original; el fade out ≤ 2 fotogramas.

10. Alineación y pistas de audio

  • uv run --with numpy python engine/voice/align.py voice.json: El resultado del reconocimiento se alinea palabra por palabra con la locución → los límites de las frases se adsorben al silencio → se elimina el silencio inicial y final de cada frase, las pausas largas dentro de la frase se reducen a ≤0.30s, atempo 1.05, fade in/fade out de 8ms → se concatenan y se genera voice/voice.wav, timeline.json, clauses.json.
  • Parámetros de pausa (último episodio publicado): Inicio 0.3s, entre frases 0.35s, entre párrafos 0.7s, final 2.5s; en preguntas, «‖», y antes de números clave, se puede aumentar a 0.8–1.0s.
  • timeline.json es la única fuente de tiempo de todo el video: la barra de progreso, los subtítulos, las palabras ancla y las señales de efectos de sonido provienen de él. Para añadir frases, solo es necesario añadir nuevos fragmentos y volver a ejecutar la alineación. Cuando no hay locución, usar engine/tools/mk_dummy_timeline.py para generar un eje de tiempo provisional y hacer primero las imágenes.
  • Música de fondo (engine/audio/audiolib.py music): Sintetizada con numpy, sin usar material con derechos de autor. Pad cálido + arpegio suave + bajo, Fa mayor Fmaj7–Dm7–Bbmaj7–C7, 84 BPM; aproximadamente −28 LUFS; cuando aparece la voz humana, ducking de aproximadamente 7 dB (ataque 60ms / liberación 450ms); fade in/fade out al principio y al final.
  • Efectos de sonido (sfx, aproximadamente 19 dB por debajo de la voz humana; 24 dB no se oyen en el móvil): Movimiento de cámara / transición de capítulo = whoosh; rotulador = marker; tarjetas / etiquetas / ✓✗ = pop (alineado al fotograma en el que el elemento realmente entra); desplazamiento de números = tick; papel que flota / paso de página = paper. No poner whoosh en momentos sin movimiento visual. El punto de tiempo se registra con data.cue() en scene.js, utilizando la misma fuente de tiempo que render(t).
  • Mezcla (mix): Dos veces loudnorm I=-16:TP=-1.8:LRA=11 → AAC 192k; después de la codificación, medir el pico real ≤ −1.5 dBTP.
  • Antes de la entrega, escuchar una vez con auriculares y otra con el altavoz del móvil (solo ajustar según los valores medidos no cuenta; el agente no puede escuchar, así que pedir al autor que escuche y señale los segmentos con la locución más densa).

11. Producción y renderizado

Primero hacer los componentes comunes y luego asignar tareas (documentación de la interfaz engine/README.md)

  • timeline.json / clauses.json: Tiempo de todo el video; tiempo del capítulo = inicio y fin de la sección de este capítulo, dentro del capítulo se usan segundos locales.
  • film.json: Orden de los capítulos, columnas de la barra de progreso, créditos finales.
  • engine/common/chrome.js: Barra de progreso, subtítulos, línea de fuente, paso de página al inicio del capítulo. Los capítulos solo dibujan renderContent, no hacen los elementos fijos por sí mismos, de modo que al unirlos solo hay un conjunto de UI.
  • Brief del capítulo: Texto completo de la tarjeta de estilo + reglas de alta densidad + interfaz + reglas de hechos + presupuesto; escribir desde el principio «el diseño debe llenar aproximadamente el 70%, ningún fotograma (incluyendo los intermedios de transformación y cambio de toma) puede tener la pantalla casi vacía, título principal de la toma 92px, no usar barras grises como marcadores de posición».
  • Diagrama madre: El código del diagrama madre común para todo el video se escribe como un archivo de especificaciones (por ejemplo, examples/always-on/MOTHER.md), y cada capítulo lo copia tal cual.

Capítulos en paralelo: Un agente de producción por capítulo, el controlador principal solo hace los componentes comunes, la renderización unificada y la concatenación.

  • renderContent(ctx, t, data) de scene.js debe ser una función pura de t: sin animaciones CSS, sin temporizadores, los números aleatorios deben usar un PRNG con semilla. Los puntos de corte solo se pueden calcular a partir de las palabras ancla (data.A(id_frase, subcadena)), no escribir los segundos manualmente.
  • Conexión entre capítulos: En t=0 de cada capítulo, ya debe haber una página completa; los últimos 0.5s deben estar fijos sin moverse; engine/tools/prep_render.mjs exporta el último fotograma sin chrome del capítulo anterior como imagen de fondo para el paso de página del siguiente capítulo (prev.png). El primer capítulo puede implementar renderPrev para dibujar su propia «página anterior».
  • Los capítulos muy largos (>90s) se dividen en dos agentes, usando un barrido de cámara para la transición: las coordenadas, las coordenadas del lienzo y la velocidad final de los elementos en el fotograma de transición se escriben fijas en el brief.
  • Si se modifican los componentes comunes, se debe transmitir a todos los agentes de capítulos, y los capítulos ya renderizados deben volver a renderizar los fotogramas afectados; si hay dudas, volver a renderizar todo el capítulo.
  • La autocomprobación del agente de producción solo extrae fotogramas fijos (abrir la página shell headless seek(t) para capturar pantalla, máximo 10 fotogramas por ronda); el producto final solo se renderiza con WebCodecs.

Renderizado (única ruta)

  1. node engine/tools/serve.mjs 8771 (solo escucha en 127.0.0.1).
  2. En Chrome local, abrir una nueva pestaña: http://127.0.0.1:8771/engine/common/shell-wc.html?ch=<directorio del capítulo>.
  3. En la consola, await probe(): verificar webglRenderer (debe ser una GPU real, como Apple M series / Metal, NVIDIA, AMD) y prefer-hardware; si software: true, detenerse e informar.
  4. startRender({ to: 10, download: false }) para probar 10 segundos reales, ver __prog.msPerFrame (en GPU, generalmente 5–15 ms/fotograma).
  5. startRender({ name: 'chNN.mp4' }) → sondear __prog.state === 'done' → el navegador descarga. Cada pestaña solo descarga una vez (la segunda vez Chrome la intercepta silenciosamente), una salida por nueva pestaña, cerrar después de renderizar.
  6. Después de descargar, cp (no mv) a <capítulo>/build/video.mp4, ffprobe -count_frames para verificar que el número de fotogramas = ceil(T×30).
  7. node engine/common/assemble.mjs --project <directorio del proyecto>: Concatenar fotograma a fotograma, música y efectos de sonido, mezcla, empaquetado, y generar una versión ligera <30MB. La mezcla no usa -shortest, la diferencia entre audio y video debe ser < 1 fotograma.

Orden: Muestra → Revisión independiente → Video completo → Refinamiento artístico → Nueva revisión → Revisión .1

  1. Primero, producir dos segmentos de muestra con síntesis completa: A = Gancho + primer zoom en el artículo (aproximadamente 30 segundos); B = primeras una o dos paradas en el lienzo grande (aproximadamente 40 segundos). Mostrar al autor el efecto y escuchar el volumen, y al mismo tiempo entregar al agente de revisión.
  2. El agente de revisión es independiente de la producción (solo ve el producto final + esta habilidad + la tarjeta del artículo), revisa elemento por elemento según references/review-checklist.md, genera must-fix / should / nice, con código de tiempo y método de modificación específico.
  3. Los must-fix se aplican a todo el video, no solo al rango de la muestra.
  4. Refinamiento artístico capítulo por capítulo: Después de bloquear el contenido y el eje de tiempo, cada capítulo se asigna a un agente que solo se ocupa del arte (sin modificar la locución, el orden de las tomas ni los números), extraer 3 fotogramas de cada toma (en la entrada / en reposo / antes de la salida), que puedan ser capturados individualmente como un póster para que se considere aprobado; verificar los cuatro niveles de fuente, que el protagonista sea lo suficientemente grande (números clave ≥200px), que se hayan utilizado las acciones características, que el significado del color no se haya desviado, que se alinee con la cuadrícula, que no haya tarjetas PPT con «marco gris por defecto + texto pequeño». Si se encuentran problemas de contenido, anotarlos en la revisión y devolverlos al equipo de producción.
  5. Revisar todo el video una vez más, corregir y sacar la versión .1; antes de tener una ronda de revisión, no enviar la «versión final».

12. Autocomprobación y entrega

  • Seguir la lista de verificación de references/review-checklist.md

[El resto del contenido se ha truncado para la traducción, pero debe continuar según el original]

Skills relacionados