Visual (Storyboard)
Esto es una tarea, no un paso del flujo. Se ejecuta solo cuando el usuario lo solicita; después de modificar el corte, se puede volver a hacer.
Solo hay dos requisitos previos: el registro de edición y los subtítulos ya existen (las capas se colocan según los subtítulos, el tiempo se calcula a partir del registro).
Necesita: edit-list.json, transcript.json, subtitles.json
Produce: visuals.json + modules/<secuencia-nombre>/index.html
Al terminar, se detiene. No indica al usuario el siguiente paso.
Primero, lee y ejecuta el Contrato de Fase del Skill de Negocio. Las reglas estrictas para la escritura de módulos se encuentran en Contrato de Módulo Visual, las reglas de juicio en Juicio Visual.
0. Preparación
Primero, ejecuta la "Verificación de Preparación" de Verificar Actualizaciones: si los skills están actualizados, si el Runtime es compatible; la raíz del plugin también se localiza allí (los <raíz-del-plugin> en los comandos de este documento deben sustituirse por esa ruta literal). Solo se continúa si está "Listo"; si el resultado es "Nueva sesión requerida" o "Detener", se ejecuta según su disposición (incluyendo la prohibición de "crear interfaces alternativas propias"). El Skill de Negocio no incluye lógica de entorno propia.
Si el resultado de preparación es runtime.kind=desktop-managed, reutiliza directamente la CLI estable ya instalada de la aplicación de escritorio y el mismo servicio launchd/windows-task; no analices rutas de Electron, instales dependencias adicionales ni inicies un segundo Runtime.
Comandos
node "<raíz-del-plugin>/scripts/ensure-running.cjs" --json
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" visual get <project> --json
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" visual frame <project> --cues sub-0004,sub-0005 --count 12 --out <dir> --json
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" visual add <project> --module modules/01-xx/index.html --cues sub-0004,sub-0005 [--zoom x,y,w,h] [--id vis-0001] --json
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" visual remove <project> --id vis-0001 --json
ensure-running debe probar primero que el puerto canónico 5190 pertenece al servicio gestionado de la plataforma actual; si falla, transmite el error y se detiene, sin recurrir a foreground ni a un puerto personalizado.
Las capas se vinculan a pantallas de subtítulos (--cues), el producto mismo las convierte en IDs de palabras — una capa nunca puede vincularse a palabras que nadie dice; si el corte cambia, la capa se mueve sola. No almacena segundos.
Cuatro pasos, sin saltar ninguno
① Texto define la tarea Leer subtitles.json, segmentar semánticamente, responder para cada segmento:
¿Tutorial/demostración/prueba, o concepto/lógica/transición?
② Extraer fotogramas para ver visual frame extrae 8-12 fotogramas, míralos realmente.
En la práctica, 2 de 12 segmentos fueron descartados visualmente — este paso no es una formalidad.
③ Medir la ventana de movimiento Diferencia de píxeles entre fotogramas consecutivos para detectar desplazamientos/cambios/operaciones.
Las capas solo se colocan en ventanas estables; la anotación sale antes de que empiece el movimiento.
④ Crear y colocar capas Escribir módulo → visual add → verificar capa por capa en la vista previa.
Reglas de juicio para el paso ②
La imagen es exactamente lo que dice → Anotar: rodear, marcar dónde dice cada palabra. La evidencia real no debe cubrirse.
Imagen débilmente relacionada/en blanco → Animación de pantalla completa: fondo blanco, desde el registro de estilos.
La imagen es suficientemente clara por sí misma → No hacer nada. Esta es la respuesta más común (en la práctica, 4 de 13 segmentos no se modifican).
El resultado del paso ③ son números, no sensaciones
Coordenadas del círculo Calcular con estadísticas de píxeles (escanear en escala de grises para encontrar líneas de texto), no medir a ojo — una vez se falló por 50px.
Momento de interacción Buscar cambios bruscos en la diferencia de píxeles entre fotogramas (en la práctica, de 4 a 335 en un solo paso). La anotación debe desaparecer 0.2s antes.
Ventana estable A menudo hay desplazamiento al principio (cuando busca contenido). La capa se vincula desde el cue de la pantalla que se estabiliza.
Usar zoom solo después de pensar
Por defecto, no hacer zoom. Una grabación de pantalla de 960x720 se vuelve borrosa al ampliar, el usuario lo notará de inmediato.
Cuando sea inevitable ≤1.6x, el área debe ser un cuadrado del 62.5% centrado — la composición completa es más importante que leer texto pequeño.
Texto demasiado pequeño Usa anotaciones circulares para guiar la vista; si realmente hay que leerlo, la solución es regrabar en alta resolución, no ampliar.
Ciclo de revisión
El directorio de módulos se nombra con secuencia numérica (01-daily-report, 05-anim-task-split), en la línea de tiempo se muestra el nombre del directorio. El usuario informa el número y tú modificas esa capa, sin tocar las demás.
Dos reglas para modificar capas, cada una correspondiente a un incidente real:
Al modificar una capa, verifica el módulo Si la capa se acorta/alarga, los tiempos relativos escritos en el módulo no cambian automáticamente — el momento de salida de la anotación podría caer después del final de la capa y nunca aparecer.
Verificación visual: captura de pantalla Mira la imagen, no consultes propiedades del DOM. Un iframe con "visibilidad correctamente invertida" una vez estaba físicamente fuera de la pantalla — propiedades correctas, pantalla completamente vacía.
Prohibiciones
- No saltar los pasos de extracción de fotogramas y medición de movimiento (cada error ocurrió una vez: se cubrió evidencia real, la anotación quedó suspendida sobre un desplazamiento).
- No hacer algo en cada segmento — no es un objetivo llenar todo; no hacer nada es una respuesta común.
- No almacenar segundos, no medir coordenadas a ojo, no añadir presión sobre fondos blancos.
- No usar imágenes de relleno si no hay contenido real.
- Los estilos se eligen del registro, no se pueden inventar.
- Los iconos de marca deben usar glifos oficiales, no dibujar sustitutos (la X se dibujó con dos líneas cruzadas y el usuario lo detectó). Si no está en el índice local, tomar el glifo oficial monocromático de simple-icons (el blanco y negro combina perfectamente), guardar el SVG original en el directorio del módulo para referencia; la misma marca en el mismo video solo debe tener un aspecto.