Manual de vídeo animado

Manual de Video

Convierte capturas de pantalla de un producto en un breve video tutorial con subtítulos: un cursor animado hace clic a través de las pantallas, resalta y acerca la atención dirigida, y texto animado explica cada paso.

El trabajo consta de cuatro pasos. El usuario decide; tú haces la producción.

Paso	El usuario	Tú
1. Proyecto del producto	indica para quién es el producto, establece el color de marca, la plantilla de fondo, el logotipo, la guía de marca	derivas las reglas de voz y ajustas el movimiento
2. Escenas	adjunta capturas de pantalla o un enlace de Figma	importa los marcos de Figma
3. Borrador del guion gráfico	define las pantallas clave, su orden y el texto	redactas el borrador para que lo edite
4. Video	mira, edita el texto y el orden, comenta sobre los marcos	agregas las acciones, verificas cada marco, corriges a partir de los comentarios, renderizas

La redacción y el orden son lo que más le importa al usuario, por lo que se definen en el paso 3 antes de cualquier trabajo de producción, y se mantienen editables en el paso 4 hasta que se renderice el MP4.

Habla con el usuario en su idioma. Escribe los subtítulos en el idioma de la interfaz de usuario del producto a menos que se indique lo contrario.

Dos formas de trabajar

Con el Studio (por defecto). Una aplicación web local muestra los cuatro pasos. El usuario trabaja allí; los botones marcados con ✦ ponen en cola solicitudes que tú recoges, cumples y respondes. Lee references/studio.md antes de iniciarlo: es el protocolo para ese bucle.

Solo en la conversación. Cuando el usuario prefiere no abrir un navegador, o no puedes ejecutar un servidor local, realiza los mismos cuatro pasos preguntando y mostrando en la conversación. Consulta "Sin el Studio" más abajo.

De cualquier manera, los archivos son idénticos, por lo que un proyecto puede moverse entre los dos.

Estructura del proyecto

Todo reside bajo video-manual/ en el proyecto del usuario, de modo que un perfil sirve para todos los manuales hechos para el producto:

video-manual/
├── product-profile.json     # uno por producto: audiencia, voz, movimiento, fondo
├── brand/                   # guide.md (guía de marca pegada), logotipo
├── requests.json            # solicitudes en cola desde el Studio
└── <manual-slug>/           # una carpeta por video, p. ej. create-task/
    ├── screens/             # 01-board.png, 02-new-task.png, ...
    ├── storyboard.json      # primero el borrador, luego el guion gráfico completo
    ├── comments.json        # comentarios sobre marcos desde el Studio
    └── out/                 # manual.html, manual.mp4, stills/, frames/

Configuración

Los scripts residen en la carpeta scripts/ de esta habilidad. La renderización necesita sus dependencias una vez:

cd <skill-dir>/scripts && npm install

Luego inicia el Studio en segundo plano y proporciona al usuario su dirección:

node <skill-dir>/scripts/studio.mjs video-manual --open

Diles en una frase lo que sucede a continuación: completan el paso 1, y tú recogerás lo que envíen con un botón ✦. Luego espera las solicitudes como se describe en references/studio.md.

Paso 1 — Proyecto del producto

Si video-manual/product-profile.json ya tiene un bloque voice, el producto está configurado: úsalo tal cual. La coherencia entre los videos de un producto es más importante que ajustar cada uno.

De lo contrario, el usuario completa el formulario (nombre, dominio, B2C/B2B, edad objetivo, dispositivo, color de acento, plantilla de fondo, logotipo y guía de marca opcionales) y envía una solicitud profile. Entonces:

1. Lee el bloque product y brand/guide.md.
2. Escribe el bloque voice: el registro, las terminaciones de las oraciones, el subtítulo más largo, las palabras a evitar, los términos del producto. Lee references/voice-guide.md. La guía de marca del usuario anula su consejo general.
3. Ajusta el movimiento para la misma audiencia. Lee references/motion-profiles.md. El usuario eligió el preajuste y el fondo; tú ajustas el ritmo, los tamaños y la suavización donde su audiencia lo requiera.
4. Agrega una rationale de una o dos oraciones.

Estos tres datos (edad objetivo, dominio, B2C o B2B) deciden cada subtítulo. Si el formulario deja uno en blanco o las pantallas lo contradicen, pregunta antes de escribir las reglas de voz.

Paso 2 — Escenas

Una imagen por cada estado de pantalla distinto, en screens/, numeradas en orden de aparición. Un estado que cambia visiblemente (se abre un modal, se despliega un menú desplegable, se completa un formulario) necesita su propia imagen: el video muestra el resultado de un clic cortando a la siguiente captura de pantalla.

El usuario normalmente las sube en el Studio. Ante una solicitud scenes con un enlace de Figma, exporta cada marco como PNG y registra su ancho lógico para coordWidth; también lee los metadatos de la capa: los límites exactos de los elementos son mucho más fiables que estimarlos a partir de píxeles.

Si falta un estado que el tutorial necesita, di cuál es y pídelo en lugar de saltarte el paso. Un salto que el espectador no pueda seguir va en contra del propósito de un manual.

Paso 3 — Borrador del guion gráfico

Ante una solicitud draft, lee cada pantalla y el perfil, luego escribe el borrador en storyboard.json: las escenas en orden, cada una con su caption y una note que describe lo que sucede en ella. Sin acciones todavía. Lee references/manual-script.md para saber cómo definir el alcance del video y escribir el texto, y escribe cada línea en la voz del perfil.

El usuario edita el borrador en el Studio y presiona "Solicitar el video" cuando la redacción y el orden sean correctos. Esa solicitud produce es la aprobación. No agregues acciones antes de que llegue.

Paso 4 — Video

Producir

Lee references/storyboard-schema.md y convierte el borrador aprobado en el guion gráfico completo: sigue la note de cada escena, agrega las acciones, establece coordWidth. Los subtítulos se mantienen exactamente como se aprobaron.

Las coordenadas son la parte más probable de estar equivocada. Usa límites exactos cuando los tengas (metadatos de Figma, rectángulos DOM). Cuando solo tengas la imagen, mira con atención y estima; la verificación a continuación existe para detectar lo que hagas mal.

Verificar antes de que el usuario lo vea

Construye y luego renderiza fotogramas fijos: un fotograma en cada clic, cambio de texto y subtítulo, y al final de cada escena:

node <skill-dir>/scripts/build.mjs video-manual/<slug>/storyboard.json
node <skill-dir>/scripts/render.mjs video-manual/<slug>/out/manual.html --stills video-manual/<slug>/out/stills

build.mjs valida el guion gráfico, verifica cada subtítulo contra las reglas de voz del perfil e imprime la duración de cada escena. Corrige los errores. Para advertencias de voz sobre texto escrito por el usuario, mantén su redacción y menciona la advertencia en tu respuesta.

Lee los fotogramas fijos y verifica cada uno:

• ¿La punta del cursor está sobre el elemento que nombra el subtítulo?
• ¿El anillo de resaltado rodea todo el elemento y nada más?
• Después de un zoom, ¿el objetivo está completamente visible y legible?
• ¿El texto escrito está dentro de su campo y cubre el marcador de posición?
• ¿Cada subtítulo es completamente visible, en un máximo de dos líneas?
• ¿Cada llamada apunta al elemento correcto sin cubrirlo ni cubrir el cursor?

Corrige el guion gráfico, reconstruye y vuelve a renderizar hasta que cada fotograma pase, luego responde a la solicitud. Un cursor que hace clic junto al botón hace que todo el manual se vea mal, por lo que el usuario nunca debería ser quien lo encuentre.

Bucle de revisión

En el paso 4 del Studio, el usuario puede:

• editar cualquier subtítulo, título o texto en pantalla y reordenar las escenas: se guarda directamente en storyboard.json, sin solicitud de por medio;
• pausar en un fotograma, fijar una posición y escribir un comentario, luego enviar los comentarios como una solicitud revise.

Maneja revise como se describe en references/studio.md: renderiza el fotograma comentado para ver lo que vieron, cambia lo que trata el comentario y nada más, confirma en un fotograma nuevo que esté corregido y responde a cada comentario. Después de que reordenen escenas, verifica que cada clic todavía lleve a la pantalla que le sigue; una cadena rota es algo que debes comunicarles, no reparar en silencio.

Este bucle se repite hasta que estén satisfechos.

Renderizar

El usuario exporta el MP4 desde el Studio con un botón. Para renderizarlo tú mismo:

node <skill-dir>/scripts/render.mjs video-manual/<slug>/out/manual.html --out video-manual/<slug>/out/manual.mp4

La renderización dura aproximadamente lo mismo que el video en sí, a veces dos o tres veces más en una máquina más lenta; ejecútalo en segundo plano para manuales de más de un minuto. Informa la ruta de salida, la duración y el tamaño del archivo.

Sin el Studio

Realiza los mismos cuatro pasos en la conversación:

1. Proyecto: deduce la edad objetivo, el dominio y B2C/B2B de las pantallas y el texto de la interfaz de usuario, expresa tu interpretación y pide al usuario que la confirme en una pregunta. Luego escribe todo el perfil tú mismo, incluidos el preajuste, el color de acento y el fondo.
2. Escenas: copia las imágenes que te dé el usuario en screens/, o captúralas tú mismo si tienes un navegador o una herramienta de Figma.
3. Borrador: escribe el borrador del guion gráfico, muéstralo como una tabla (paso, pantalla, qué sucede, subtítulo, texto en pantalla) con la duración estimada y espera la aprobación. Si dijeron de antemano que siguieran adelante, continúa e indica dónde está el borrador.
4. Video: produce y verifica como se indicó anteriormente, luego diles dónde está out/manual.html. Esa página independiente reproduce el video y tiene su propio panel para editar texto y orden; "Descargar ediciones" proporciona un storyboard.edited.json que pueden devolverte. Cuando lo hagan, enumera lo que cambió para que puedan confirmar que lo leíste como ellos querían, guárdalo como storyboard.json, reconstruye y vuelve a verificar los fotogramas fijos. Luego renderiza.

Cambios posteriores

• Redacción u orden: el usuario edita en el Studio, o te lo dice.
• Voz ("demasiado formal", "nuestros usuarios son mayores que eso"): cambia el bloque voice del perfil y luego reescribe los subtítulos para que coincidan.
• Sensación ("demasiado lento", "demasiado elástico"): cambia los tokens de movimiento en el perfil, no las escenas individuales; consulta la tabla de ajuste en references/motion-profiles.md.
• Un paso se ve mal: corrige las acciones de esa escena y vuelve a verificar sus fotogramas fijos.

Reconstruye y vuelve a verificar los fotogramas fijos después de cualquier cambio antes de renderizar nuevamente.

Límites

Dilo claramente cuando una solicitud se topa con uno de estos:

• Las pantallas son imágenes estáticas. El desplazamiento, los estados de hover y la animación dentro de la aplicación no se reproducen; muéstralos como capturas de pantalla separadas.
• Sin locución ni música. Los subtítulos y el texto en pantalla llevan la explicación.
• El Studio edita texto y orden de escenas. Lo que un paso clica o resalta cambia a través de un comentario hacia ti.
• La salida es 16:9 por defecto. Establece meta.width y meta.height en el guion gráfico para otras formas.

Solución de problemas

• playwright-core is not installed: ejecuta npm install en la carpeta de scripts.
• no browser found: instala Google Chrome, o ejecuta npx playwright install chromium en la carpeta de scripts.
• ffmpeg not found: instala ffmpeg o establece FFMPEG_PATH. npm install normalmente proporciona uno a través de ffmpeg-static.
• Una solicitud permanece "esperando" en el Studio: nadie está ejecutando studio.mjs wait. Ejecútalo, o studio.mjs pending.
• El paso 4 muestra errores en lugar del video: una escena apunta a una imagen faltante o tiene una coordenada fuera de su pantalla. build.mjs nombra la escena.
• Una fuente se ve mal: el video usa las fuentes instaladas en la máquina. Establece font.family en el perfil a una que esté instalada.