themoltnet/Product Demo Recording

Grabación de Demostraciones de Producto

Trata el encuadre, la privacidad, la narrativa y la salida decodificada como compuertas de lanzamiento separadas. Una ejecución exitosa del producto no prueba que la grabación sea segura, legible o esté bien compuesta.

Para mecánicas de captura nativas de macOS o navegador, lee references/capture-macos.md. Para constructores de flujos de trabajo en navegador con bucles de sondeo o reintentos, lee references/browser-workflows.md. Para tarjetas de título, tercios inferiores, diagramas, leyendas y tarjetas de cierre, lee references/infographic-style.md.

Establece primero el marco de entrega

Antes de grabar:

1. Elige el tipo de narrativa antes de escribir la lista de tomas:
   • Una visión general enseña la forma del producto: muestra la secuencia de nodos o pantallas representativa más pequeña, usa copia genérica y omite explicación específica del escenario.
   • Una demo de escenario responde a una pregunta concreta: plantea el caso, muestra las etapas reales de ejecución y termina con el resultado verificado.
   • Prefiere videos cortos separados cuando ambos son útiles. No mezcles explicación genérica del producto con un caso específico del dominio a menos que el usuario quiera explícitamente un tutorial combinado.
2. Establece una referencia visual:
   • Si existe una grabación anterior, revísala de principio a fin. Extrae un muestrario cuando sea útil y anota su ritmo, encuadre, anotaciones y sus momentos explicativos más fuertes.
   • Si no hay una grabación anterior, usa la biblioteca @themoltnet/design-system, los medios de documentación vecinos y la interfaz nativa del producto integrado—en ese orden—para crear una imagen de tarjeta de título, la imagen anotada más densa de la interfaz y una imagen de tarjeta de cierre antes de grabar. Estas imágenes aprobadas se convierten en la línea base para videos posteriores de la serie.
3. Lee la página donde aparecerá el video. Escribe una lista corta de tomas que nombre el resultado para el usuario, la configuración necesaria, la interacción principal, el comportamiento de espera o reintento, y el resultado exitoso.
4. Elige la relación de aspecto y resolución finales antes de organizar la aplicación. Prefiere un marco 16:9 convencional como 1440x810 o 1920x1080.
5. Organiza la aplicación para que el área de contenido deseada completa quepa en ese marco. Oculta las barras laterales opcionales dentro de la aplicación cuando sea necesario; no elimines la mitad de una barra lateral o control con un recorte arbitrario en postproducción.
6. Decide si el chrome del navegador es parte de la composición. Prefiere una captura limpia del viewport del navegador. Si eso no está disponible, mantén la ventana completa del navegador o colócala dentro de un marco deliberado. Una ventana completa es más limpia que pestañas recortadas, bordes o contenido de la aplicación.
7. Revisa los tres fotogramas de estilo representativos a su tamaño de visualización real. No grabes el tutorial completo mientras el sistema de superposiciones, las áreas seguras o la jerarquía de información aún se están inventando.

Usa un límite de captura seguro

• Captura una ventana de aplicación o un viewport de navegador, nunca un rectángulo del escritorio donde otra aplicación pueda entrar.
• Resuelve y bloquea el identificador exacto de la ventana antes de grabar. Vuelve a verificarlo después de navegación, ventanas emergentes o reinicios de la aplicación.
• Desactiva las notificaciones y usa datos de demostración dedicados, pero no confíes en esas precauciones como el límite de privacidad.
• Mantén credenciales, tokens, identificadores personales, URL privadas y datos de cuenta no relacionados fuera de la superficie capturada. El enmascaramiento de contraseñas es necesario pero no hace que la grabación de ingreso de credenciales sea deseable.
• Haz que el puntero sea intencional. Colócalo lejos del texto mientras se lee un resultado estático.

Graba para la comprensión

• Usa una idea por toma. Mantén la configuración importante y los resultados el tiempo suficiente para leerlos a velocidad de reproducción normal.
• Muestra la configuración solo cuando ayude al espectador a reproducir el resultado. Para demos de integración, esto a menudo significa instalar, autenticar sin revelar el secreto, importar el flujo de trabajo, ejecutarlo e inspeccionar el resultado en la terminal.
• Prefiere el zoom nativo de la aplicación y los cambios de diseño sobre agrandar un raster recortado posteriormente.
• Captura la ejecución exitosa real. Las tarjetas de título y anotaciones reconstruidas pueden explicarla, pero no deben implicar una acción o resultado que no fue observado.
• Una edición basada en estados puede usar imágenes fijas limpias capturadas de una ejecución real cuando el movimiento en sí mismo no es instructivo. Mantén los estados en el orden observado, conserva la evidencia visible de la tarea y usa transiciones solo para comunicar progresión.
• Completa la creación de credenciales y las pruebas de conexión fuera de la toma grabada. Comienza la narrativa desde un estado autenticado seguro, a menos que la configuración de credenciales sea el tema documentado.
• Graba tomas cortas e independientemente utilizables cuando el flujo tenga etapas estables. Esto limita la re-grabación y hace que la revisión de privacidad sea más precisa.
• Para un bucle largo de sondeo o reintento, conserva los estados reales ordenados pero acelera o recorta la parte inactiva repetida. Mantén la acción inicial, el estado final del flujo de trabajo y el resultado aceptado a velocidad legible.

Edita sin ocultar el producto

• Conserva todos los bordes de la aplicación previstos. Reduce la escala y añade relleno al marco de entrega en lugar de recortar contenido para forzar una relación de aspecto.
• Usa tarjetas de título y cierre solo cuando mejoren la orientación o los próximos pasos.
• Mantén los tercios inferiores dentro de un área segura preplanificada. No deben cubrir controles, estado, salida, errores o identificadores necesarios para entender el flujo.
• Para demos de escenario, deja que las anotaciones avancen con la ejecución. Nombra la etapa actual y explica su consecuencia en una línea corta, por ejemplo INTENCIÓN — Extraer lugar y marco temporal seguido de INTENCIÓN COMPLETA — Obtener el pronóstico. Usa los nombres de etapa reales del producto y el estado observable; no narres razonamientos ocultos.
• Mantén un video de visión general visualmente más silencioso que su demo de escenario acompañante. Las etiquetas de nodo y los indicadores de estado nativos deben llevar la explicación cuando ya son suficientes.
• Coincide con el lenguaje visual de la documentación establecida al reemplazar un video existente. No hagas que un reemplazo se sienta menos deliberado que el activo que reemplaza.
• Para una amplia compatibilidad con navegadores, el valor predeterminado es H.264 High, yuv420p, 30 fps constantes, sin audio a menos que la narración sea intencional, y MP4 con fast-start.
• En esta cadena de herramientas macOS, prefiere libx264 de un solo hilo para la renderización final cuando sea práctico. Usa el script auxiliar incluido en lugar de la búsqueda rápida de entrada al extraer fotogramas de QA con marca de tiempo exacta.
• Si un fotograma parece corrupto en una vista previa del artefacto, vuelve a abrir el artefacto con suma de verificación estable e inspecciona el video en un reproductor nativo. La ruta de vista previa ha renderizado de forma intermitente bytes de imagen idénticos de manera diferente; no modifiques un video a menos que el defecto sea reproducible de forma independiente.
• Si un fotograma permanece corrupto en la reproducción normal y en la extracción repetida, reemplaza el segmento afectado desde una fuente limpia y recodifica el máster final con -threads 1.

Añade audio solo cuando se gane su lugar

• Mantén la reproducción silenciosa como predeterminada para los videos incrustados en la documentación. Añade narración cuando explique materialmente el tiempo, la causalidad o el contexto que las anotaciones visuales concisas no pueden.
• Escribe y sincroniza la narración con la imagen bloqueada. Los subtítulos o una transcripción de texto deben conservar la misma información, y el video debe seguir siendo comprensible cuando esté silenciado.
• Usa una voz clonada o sintética modelada a partir de una persona identificable solo con la autorización explícita de esa persona. Revela que la voz es sintética en la página circundante o en los créditos; no la presentes como una grabación auténtica en vivo.
• Mantén las muestras de voz, los archivos de modelo y los intermedios generados fuera del repositorio a menos que el usuario elija explícitamente publicarlos. Trata la autorización para crear una demo narrada como limitada a ese entregable, no como un consentimiento permanente para la generación futura de voz.
• Vuelve a ejecutar el QA de entrega después de multiplexar el audio. Verifica la inteligibilidad, los niveles, la sincronización, los subtítulos, la disposición de canales y que el contenedor final cumpla con la especificación de entrega de video.

Revisa el entregable decodificado

Ejecuta el script auxiliar incluido contra el archivo final, no uno intermedio:

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  path/to/final.mp4 /private/tmp/demo-video-qa --interval 2 4 5 6

El script auxiliar escribe metadatos del flujo, un muestrario decodificado secuencialmente y fotogramas de inicio/medio/fin más las marcas de tiempo solicitadas como JPEG. Usa un directorio de salida nuevo.

Luego realiza todas estas comprobaciones:

1. Mira el video final completo a velocidad normal.
2. Inspecciona el muestrario en cada cambio de aplicación, modal, toma, anotación y estado de resultado.
3. Inspecciona fotogramas exactos inmediatamente antes, en y después de cada límite de edición. Siempre agrega marcas de tiempo nombradas en los comentarios de revisión; no infieras que los fotogramas adyacentes son representativos.
4. Confirma que no haya otras aplicaciones, áreas del escritorio, notificaciones, credenciales, datos privados, bordes recortados, chrome de navegador parcial, bordes negros extraños o controles obstruidos.
5. Confirma que el texto sea legible, la colocación del puntero sea tranquila, las transiciones sean limpias y el resultado visible coincida con la documentación circundante.
6. Verifica el códec, formato de píxel, dimensiones, velocidad de fotogramas, duración, elección de audio y el requisito de fast-start contra la especificación de entrega.

No describas la grabación como revisada hasta que estas comprobaciones se hayan realizado en el archivo exacto que se va a confirmar.

Entrega y conserva deliberadamente

• Prepara solo el activo final y los cambios intencionales de documentación. No agregues tomas sin procesar, credenciales, perfiles de navegador o exportaciones de QA.
• Mantén las tomas sin procesar hasta que el archivo final sea revisado y confirmado o subido de forma segura. Luego sigue la elección de retención del operador; elimina las capturas temporales sensibles explícitamente en lugar de con patrones de eliminación amplios.
• En la transferencia, indica qué se mostró, las propiedades técnicas finales, qué marcas de tiempo se inspeccionaron y dónde reside el activo final.