chulegexiaojiu/novel-storyboard

¿Qué hace novel-storyboard?

Genera storyboards para AI short drama — la primera capa de la tubería que enfrenta directamente al modelo de video. Premisa fundamental: los planos se generan, el costo de añadir un corte adicional es casi nulo, por lo que aquí no se escatima en cantidad de planos; el único límite superior es la duración máxima de generación por segmento del modelo de video (15 segundos por defecto).

Mecanismo central: los planos reclaman beats. Cada plano declara qué beats consecutivos de una escena del guion cubre (sceneIndex + beats: [inicio, fin]), y los planos no pueden cruzar escenas — cambio de escena implica cambio de plano. Esto hace que la relación entre storyboard y guion sea mecánicamente auditable:

Entregable	Resuelve
Reclamo de beats	Cada beat es reclamado por exactamente un plano, en orden; si se modifica el guion, al re-ejecutar validate se señalan los planos inválidos
Plano único ≤ 15 s	Límite de generación por segmento de AI video; diálogos largos se dividen forzosamente aquí (ajustable mediante params.maxShotSeconds según el modelo)
Diálogo cabe en el plano	La duración de los beats reclamados ≤ la duración del plano — verificación shot por shot, no al azar
Prompt de frame de storyboard + texto del plano	El prompt del frame (frame, en chino, nombrando directamente al personaje) se entrega al modelo de imagen junto con las hojas de diseño; el texto del plano (shot, en chino, con identidad genérica) describe lo que ocurre en esos segundos. El tipo de plano es un enumerado, y la palabra china del tipo debe incluirse en el prompt del frame
Prompt de video H3 (uno por segmento)	Estructura I2VA de MiniMax H3: directiva de alineación fija + integrated_multimodal_description + overall_soundscape + non_diegetic_music. El diálogo de los beats reclamados se coloca palabra por palabra dentro de <d>[Chinese] …</d> — diálogo, paisaje sonoro y música, todo en un solo prompt
Prompt de video Seedance (uno por segmento, generado por script)	Paralelo a H3. El script lo construye según la estructura oficial: declaración de imágenes de referencia, bloqueo a nivel de segmento, campos cuantitativos por shot, diálogo en {}, efectos de sonido en <>, música en （）, restricciones de numeración. El modelo solo escribe el shot de cada corte, sin duración, número ni referencia a imágenes
Campos cuantitativos de composición	Por segmento: blocking (quién está a la izquierda/derecha, distancia); por shot: distancia focal / posición de cámara / composición / punto de mirada / foco / estabilidad — cuando no hay frames de storyboard, son la única fuente de composición
Hoja de lotes de generación	Planos con misma escena e iluminación se agrupan en un lote, comparten una misma imagen de referencia de entorno — versión AI de la hoja de continuidad, resumida automáticamente por el script
Hoja de sincronización de doblaje	Cada línea de diálogo se asigna a un número de plano — a qué segmento de video se pega el audio TTS, resumido automáticamente por el script

{baseDir} = directorio donde se encuentra este archivo. Script {baseDir}/scripts/novel-storyboard.mjs, cero dependencias, se ejecuta directamente con node.

Límites (lo que no hace): no escribe actuación ni cambia diálogos (trabajo de novel-script), no genera hojas de diseño de escenas/personajes/accesorios (trabajo de novel-art / novel-characters), no realiza generación de video ni edición/compilación. La sincronización de labios/boca no se maneja por ahora — es trabajo de la tubería de generación.

---

Paso 0 — Definir entrada y alcance

script.json es un requisito duro — el storyboard no tiene sentido sin guion; validate/render deben recibir --script. El resto de fuentes se usan si están disponibles:

• --outline / --cast: verificación de que los prompts no contienen nombres de personajes + en el informe se muestran como C01 con nombre
• --art: en el informe, S01 se muestra como nombre de escena + la hoja de lotes incrusta la imagen de diseño de escena
• --shots <directorio de tarjetas>: opcional monta la biblioteca de tarjetas de recetas de planos de shot-recipes (apuntando a shot-recipes/references/cards, solo acepta directorios, no JSON exportado). Activa la 18.ª compuerta shot-recipe. Si no se tiene instalado shot-recipes, no usar — esta skill es autocontenida, no depende de él

Cuántos episodios procesar: sigue el lote del guion (storyboard hasta donde llegue el guion), por defecto un lote ≤ 3 episodios.

Paso 1 — seed: borrador de trabajo

node {baseDir}/scripts/novel-storyboard.mjs seed <script.json> --eps 1-3 > <workdir>/storyboard.json

Expansión determinista: la lista de beats por escena (número, acción/diálogo, duración de cada beat, quién habla) entra en seedScenes; este es el borrador de trabajo sobre el que se cortan los planos. La duración de cada beat se calcula, no la deja estimar al modelo. Los shots se dejan vacíos; cortar los planos es trabajo del modelo.

Paso 2 — Segmentar y cortar planos por episodio

Una tarea por episodio, se pueden ejecutar en paralelo. Cada tarea recibe:

• {baseDir}/references/storyboard-pass.md y {baseDir}/references/schema.md (léelos y síguelos)
• Los seedScenes del episodio + tarjetas de escena (puntos de anclaje y prompt de iluminación de art.json) + tarjetas de personaje (puntos clave de apariencia de cast.json)

Flujo: primero segmentar por unidad argumental (cada segmento de 9–15 s, sin cruzar escenas), luego cortar 2–5 s de storyboard dentro del segmento (plano/contraplano en diálogos, insertos para acciones clave, tríptico de entrada — la gramática de corte está en storyboard-pass.md). Por cada corte, escribir un prompt de frame de storyboard (en chino, nombrando directamente al personaje), un texto de shot shot (en chino, con identidad genérica) y seis campos de composición. Por cada segmento, escribir blocking, soundscape, y si hay música, music.

El texto de shot de cada segmento se escribe según {baseDir}/references/shot-writing.md (independiente del protocolo: un movimiento de cámara por corte, la acción debe completarse, diálogo palabra por palabra, capas de sonido, no escribir estilo visual). Según el servicio de video al que se envíe, se aplica la sintaxis del protocolo correspondiente: MiniMax H3 ver {baseDir}/references/h3-prompt.md, Seedance ver {baseDir}/references/seedance-prompt.md.

Por cada segmento, escribir un h3Prompt, según {baseDir}/references/h3-prompt.md (versión internalizada de la metodología oficial, no depende de ningún skill externo). Por defecto en inglés (promptLang cambiable a chino), un renglón por corte. Puntos clave: la directiva de alineación y los momentos de [Shot k] se derivan de la duración del storyboard, sin desviarse ni un carácter (validate lo verifica palabra por palabra); el diálogo reclamado se coloca palabra por palabra dentro de <d>[Chinese] …</d>; los movimientos de cámara de cada corte van en su propio renglón; el paisaje sonoro y la música van en los dos campos restantes — el paisaje sonoro también es una instrucción de acción; si cambia la imagen, cambia también el paisaje sonoro.

Los prompts de Seedance no se escriben: el panel de prompts del informe render y export --protocol seedance los ensamblan a partir de estos campos. El estilo visual lo añade quien invoca al enviar; las restricciones globales se dan con --constraints <archivo>.

Al terminar, eliminar seedScenes.

Paso 3 — Validación ⛔ No se puede saltar

node {baseDir}/scripts/novel-storyboard.mjs validate <storyboard.json> \
  --script <script.json> --outline <outline.json> --cast <cast.json> \
  [--shots </path/to/cards>]

Las 18 compuertas de calidad son todas código: cobertura de beats (a nivel de storyboard, exactamente una vez, en orden, continuos), segmento 0 < duración total ≤ 15 s, cada corte 2–5 s, diálogo cabe en el plano, duración total de cada episodio dentro del ±15% del objetivo del guion, máximo 3 personas en cuadro (si se excede, debe incluir explicación de cómo se desglosa), número de segmento en formato E01-01 consecutivo, palabra china de tipo de plano en el prompt del frame, movimientos de cámara usan el vocabulario de H3 y están en su párrafo [Shot k], directiva de alineación de H3 derivada de la estructura del storyboard verificada palabra por palabra + momentos de corte verificados uno por uno, diálogo reclamado palabra por palabra dentro de <d>, idioma del prompt coherente con promptLang (verificación bidireccional: chino escrito en inglés, inglés mezclado en chino, ambos bloqueados), prompt de frame no vacío en chino, el prompt de video no contiene nombres de personajes (H3 en cualquier idioma, Seedance en texto de shot; el prompt de frame puede nombrarlos directamente), campos cuantitativos de composición completos, texto de shot de Seedance conforme (no vacío en chino, sin escribir tiempo, número de plano, referencia a imágenes ni símbolos de protocolo), coherencia con guion en escenas/personajes/accesorios, coherencia con recetas de planos (compuerta opcional, ver abajo).

Si hay infracciones, corregir una por una, re-ejecutar hasta que pase.

18.ª compuerta shot-recipe (montaje opcional): solo se verifica si se da --shots; si no, se salta explícitamente. Un corte puede tener un recipe opcional (id de tarjeta de receta, a nivel de cut, no de segmento; recetas de múltiples frames se expresan mediante cortes consecutivos con el mismo id, no con arrays). La compuerta verifica tres cosas: el id está en la biblioteca de tarjetas, cada must_phrases de la tarjeta aparece en el frame de ese corte (con includes después de pasar ambos a minúsculas), y si la tarjeta tiene un límite inferior de cuts ≥ 2, el número de cortes consecutivos con el mismo id no debe ser inferior a ese límite. El tipo de plano sugerido y el movimiento de cámara de la tarjeta no son compuerta; solo se indican en la columna "Receta" del informe y al final de checkup como desviación: las recetas son vocabulario, no leyes; si algo opcional se vuelve estricto, nadie lo monta.

Paso 4 — Salida e informe

cd <directorio de salida>
node {baseDir}/scripts/novel-storyboard.mjs render <nombre-de-la-serie>-storyboard.json --md \
  --script <script.json> --outline <outline.json> --art <art.json> > <nombre-de-la-serie>-storyboard.md
node {baseDir}/scripts/novel-storyboard.mjs render <nombre-de-la-serie>-storyboard.json --html \
  --script <script.json> --outline <outline.json> --art <art.json> > storyboard-report.html

El idioma de la interfaz del informe se especifica con --lang zh|en (prioridad --lang > campo lang en la raíz del JSON > chino por defecto) — solo afecta etiquetas de la interfaz, independiente de promptLang (idioma del prompt H3). render usa --frames <directorio> para buscar frames de storyboard (<directorio>/<nº segmento>/f<nº corte>.png, por defecto directorio actual), y --images <directorio> para buscar imágenes de diseño de escena de la hoja de lotes (<directorio>/<slug de escena>-sheet.png, por defecto ./images); ambos pueden apuntar a cualquier ruta — esta skill no genera estos archivos; una vez que el downstream genera las imágenes, re-ejecutar render para incrustarlas en el informe. export --frames <directorio> copia los frames de storyboard que se encuentren en el paquete de producción, sin necesidad de colocarlos manualmente. El informe incluye: barra de KPI, cinta de ritmo del storyboard (separadores gruesos = límites de segmento, ancho de bloque = proporción de duración del plano, color = distancia del tipo de plano, clic para saltar a la tarjeta de segmento), tabla de storyboard por episodio (frame principal + tiras de subframes + fila de shot por corte + botones de copia de prompt de frame/H3), hoja de lotes de generación, hoja de sincronización de doblaje, compuertas de calidad, exportación JSON. La versión Markdown incluye el prompt H3 completo por segmento, listo para copiar y usar.

Resumir en una frase: cuántos episodios, cuántos planos, duración total vs objetivo, cuántos lotes de generación, ruta del informe; si hay compuertas que no pasaron, mencionarlas.

No decir "imágenes generadas" — ese paso ya no existe; se entregan prompts y lista de imágenes a adjuntar.

Estructura final:

<directorio de salida>/
├── <nombre-de-la-serie>-storyboard.json
├── <nombre-de-la-serie>-storyboard.md
├── storyboard-report.html         ← se abre con doble clic
├── manifest.json                  ← generado por export
└── E01-01/                        ← una carpeta por segmento = todo el material para una generación H3
    ├── f1.png                     ← frame principal de storyboard (colocado aquí por downstream después de generar)
    ├── f2.png …                   ← subframes de storyboard
    └── prompt.md                  ← prompt H3 (generado por export)

---

Relevo de cinco skills (la tubería se cierra aquí)

novel-outline    → outline.json    (qué: estructura y episodios)
novel-characters → cast.json       (quién: hojas de diseño de personajes)
novel-art        → art.json        (dónde: hojas de diseño de escenas/accesorios)
novel-script     → script.json     (acción: escenas, beats, diálogo)
novel-storyboard → storyboard.json (cómo filmar: planos, primer frame, lotes)

El storyboard es el extremo consumidor: seed consume script.json, la generación de frames de storyboard (en downstream) consume las hojas de diseño de art y characters como referencia, el prompt H3 se envía directamente al modelo de video, la hoja de sincronización de doblaje recibe el producto TTS del guion de diálogo. Los informes de cada uno de los cinco JSON tienen botón de exportación; después de modificar, todos pueden reintroducirse en su respectivo render/validate.

Límites

• La interfaz del informe tiene chino e inglés incorporados (--lang, por defecto chino); el idioma del prompt lo controla promptLang de forma independiente (por defecto inglés)
• La duración es tiempo de generación enviado al modelo de video, no una estimación — el límite por segmento se ajusta según tu modelo con params.maxSegmentSeconds, el intervalo de ritmo de corte con min/maxCutSeconds
• La sincronización de labios/boca no se maneja por ahora — es trabajo de la tubería de generación
• Los frames de storyboard no buscan ser perfectos de una vez — son anclas de composición para el modelo de video; si la composición y los activos son correctos, es suficiente; los ajustes finos se dejan para la regeneración

Las fallas de compuerta se acumulan

validate y checkup añaden los resultados de las compuertas a .gates.jsonl en el directorio actual; ejecutar stats para resumir:

node {baseDir}/scripts/novel-storyboard.mjs stats

Responde tres cosas: qué compuerta suena más a menudo (qué regla el modelo ignora más a menudo, hay que cambiar la redacción), qué compuerta nunca ha sonado (puede ser una compuerta muerta, o la regla ya está internalizada), cómo se ven las fallas detalladas (problemas que ocurren repetidamente sin que ninguna compuerta los atrape, solo se pueden detectar manualmente).

Si no se desea registrar, añadir --no-log; si no se puede escribir, se salta silenciosamente sin afectar la validación.

Autocomprobación

node {baseDir}/scripts/selftest.mjs

323 aserciones, sin llamar al modelo, sin gastar cuota. Las 18 compuertas de calidad tienen casos de prueba de fallo cada una. Ejecutar esto después de modificar el script.

Ejemplo incluido

{baseDir}/examples/storyboard-ferry.json: Storyboard completo del episodio 1 de "El Ferry" — 10 segmentos, 34 cortes, cubriendo los 35 beats del guion, promedio de 3.5 s por corte, total 119 s / objetivo 120 s, 2 lotes de generación, cada segmento con prompt H3 completo (alineación de múltiples imágenes + momentos de corte todos verificados). Sirve como referencia de calidad y como fixture de autocomprobación.