Cuando esta habilidad se active, comienza siempre tu primera respuesta con el emoji :pencil:.
Redacción de Guiones de Video
La redacción de guiones de video para video programático es la práctica de planificar, estructurar y escribir guiones que se traducen directamente en producción de video basada en código. A diferencia de la escritura de guiones tradicional, los guiones de video programáticos son datos estructurados: cada escena tiene una duración explícita, un recuento de fotogramas, una descripción de animación y un texto de narración que un motor de renderizado puede consumir. Esta habilidad cubre la realización de entrevistas a las partes interesadas, la generación de guiones YAML estructurados, el cálculo del ritmo y los recuentos de fotogramas, la redacción de narraciones y la revisión de guiones.
Cuándo usar esta habilidad
Activa esta habilidad cuando el usuario:
- Quiere escribir un guión para un video programático o generado por código
- Necesita planificar la estructura de la escena, el tiempo o las transiciones de un video
- Pregunta sobre la creación de guiones gráficos en un formato estructurado (YAML, JSON)
- Quiere calcular recuentos de fotogramas a partir de la duración y los FPS
- Necesita ayuda para escribir texto de narración para escenas de video
- Pregunta sobre el ritmo del video para diferentes tipos de contenido (demo, explicativo, social)
- Quiere ejecutar un flujo de trabajo de entrevista para recopilar requisitos de video
- Necesita revisar o reestructurar un guión de video existente
NO actives esta habilidad para:
- Cine de acción real o escritura de guiones tradicional
- Tutoriales de software de edición de video (Premiere, Final Cut, DaVinci Resolve)
- Contenido solo de audio como podcasts o producción musical
- Diseño de imágenes fijas o diapositivas de presentación estáticas
Principios clave
-
Impulsado por entrevistas - Realiza una entrevista estructurada (hasta 30 preguntas en 7 categorías) antes de generar una sola escena. Nunca escribas basándote en suposiciones.
-
Salida estructurada - Cada guión es YAML válido con un bloque
metay una matrizscenes. Cada escena tiene los camposid,duration,frames,narration,visual,animation,music,sfxytransition_to_next. -
Primero lo visual - Escribe el campo
visualantes quenarration. La narración debe complementar lo visual, nunca describir de manera redundante lo que está en pantalla. -
Conciencia del ritmo - Ajusta el número de escenas y la duración por escena al tipo de video: los clips sociales necesitan escenas de 3-8s; los videos explicativos pueden tener más espacio con escenas de 5-12s.
-
Sincronización narración-visual - Cada línea de narración debe coincidir con lo que es visible en ese momento. Una idea por escena. El tiempo de la narración debe ajustarse a la duración de la escena.
Conceptos clave
Marco de entrevista
Recopila requisitos a través de 7 categorías antes de escribir:
| Categoría | Preguntas | Ejemplos |
|---|---|---|
| Producto/Tema | 5-7 | ¿Cuál es el producto? ¿Características clave? ¿Problema resuelto? ¿Diferenciador? |
| Audiencia | 3-5 | ¿Espectador objetivo? ¿Nivel técnico? ¿Puntos débiles? |
| Objetivos del video | 3-4 | Tipo (demo/explicativo/social/anuncio)? ¿Duración? ¿Canal? |
| Tono y estilo | 3-5 | ¿Formal o informal? ¿Energético o tranquilo? ¿Videos de referencia? |
| Activos | 3-5 | ¿Logotipo? ¿Capturas de pantalla? ¿Colores de marca? ¿Fuentes? |
| Contenido | 4-6 | ¿Mensajes clave? ¿Características imprescindibles? ¿CTA? ¿Apertura impactante? |
| Preferencias visuales | 3-5 | ¿Estilo de animación? ¿Paleta de colores? ¿Preferencias de diseño? |
Formato de guión YAML
meta:
title: "string - título descriptivo"
duration: "string - duración total (ej. 60s)"
type: "enum - demo | explainer | social | announcement"
resolution: "string - ej. 3840x2160, 1920x1080"
fps: "number - 24, 30, o 60"
audience: "string - quién está viendo"
tone: "string - descriptores separados por comas"
total_frames: "number - duración_segundos * fps"
scenes:
- id: "string - identificador único en kebab-case"
duration: "string - ej. 4s, 8s"
frames: "number - duración_escena_segundos * fps"
narration: "string - máximo 15 palabras por oración"
visual: "string - lo que el espectador ve en pantalla"
animation: "string - cómo se mueven los elementos, con referencias de fotogramas"
music:
track: "string - nombre de la pista musical"
volume: "number - 0.0 a 1.0"
duck: "boolean - bajar música durante la narración"
sfx:
- type: "string - nombre del efecto de sonido"
at: "string - marca de tiempo dentro de la escena"
duration: "string - cuánto tiempo suena"
transition_to_next: "enum - hard-cut | cross-dissolve | fade-to-black | wipe-left | wipe-right | none"
Ritmo de escena por tipo de video
| Tipo de video | Duración | Escenas | Por escena | Notas |
|---|---|---|---|---|
| Demo de producto | 30-120s | 6-15 | 5-10s | Centrado en características, CTAs claros |
| Explicativo | 60-180s | 8-20 | 5-12s | Con muchos conceptos, más espacio para respirar |
| Clip social | 15-60s | 3-8 | 3-8s | Gancho en los primeros 3s, ritmo rápido |
| Anuncio | 15-45s | 3-6 | 4-8s | Contundente, enfoque en un solo mensaje |
Cálculo de fotogramas
total_frames = duración_segundos * fps
scene_frames = duración_escena_segundos * fps
Ejemplo: Video de 60s a 30fps = 1800 fotogramas totales
| Duración | 24 fps | 30 fps | 60 fps |
|---|---|---|---|
| 4s | 96 | 120 | 240 |
| 8s | 192 | 240 | 480 |
| 30s | 720 | 900 | 1800 |
| 60s | 1440 | 1800 | 3600 |
| 90s | 2160 | 2700 | 5400 |
Siempre valida que la suma de los recuentos de fotogramas de las escenas sea igual a total_frames en meta.
Tareas comunes
1. Ejecutar el flujo de trabajo de entrevista
Recorre las 7 categorías en secuencia. Pregunta una a la vez, resume las respuestas y luego continúa. Consulta references/interview-questions.md para el marco completo de 30 preguntas. La versión comprimida para plazos ajustados utiliza 10 preguntas esenciales: nombre del producto, características clave, problema resuelto, espectador objetivo, nivel técnico, tipo de video, duración, canal, mensaje clave y CTA.
2. Generar un guión de demo de producto
meta:
title: "Demo de producto - Acme Dashboard"
duration: "60s"
type: demo
resolution: 3840x2160
fps: 30
audience: "Fundadores de SaaS y gerentes de producto"
tone: "profesional, seguro, minimalista"
total_frames: 1800
scenes:
- id: intro
duration: "4s"
frames: 120
narration: "Conoce Acme, el panel que se construye solo."
visual: "Logotipo centrado sobre fondo blanco cálido, aparece gradualmente desde transparente"
animation: "aparición gradual en 30 fotogramas, mantener durante 90 fotogramas"
music:
track: "upbeat-corporate"
volume: 0.4
duck: false
sfx: []
transition_to_next: "hard-cut"
- id: feature-1
duration: "8s"
frames: 240
narration: "Solo describe lo que necesitas. Acme se encarga del resto."
visual: "Maqueta de navegador que muestra la entrada de texto, escribiendo el texto"
animation: "el navegador se desliza hacia arriba desde abajo en 20 fotogramas, la escritura comienza en el fotograma 40"
music:
track: "upbeat-corporate"
volume: 0.2
duck: true
sfx:
- type: "keyboard-typing"
at: "1.3s"
duration: "3s"
transition_to_next: "cross-dissolve"
- id: feature-2
duration: "8s"
frames: 240
narration: "Arrastra, suelta, redimensiona. Tu diseño, tus reglas."
visual: "Editor de panel con widgets siendo reorganizados por el cursor"
animation: "el cursor se mueve al widget en el fotograma 30, lo arrastra a una nueva posición en 60 fotogramas"
music:
track: "upbeat-corporate"
volume: 0.2
duck: true
sfx:
- type: "soft-click"
at: "1.0s"
duration: "0.2s"
transition_to_next: "cross-dissolve"
- id: cta
duration: "6s"
frames: 180
narration: "Prueba Acme gratis en acme.dev. Crea tu primer panel en minutos."
visual: "Texto de CTA centrado con URL, fondo degradado animado sutil"
animation: "el texto aparece gradualmente en 20 fotogramas, el fondo degradado cambia lentamente"
music:
track: "upbeat-corporate"
volume: 0.4
duck: false
sfx: []
transition_to_next: "fade-to-black"
Los guiones de demostración completos suelen tener de 6 a 15 escenas. Amplía agregando escenas de problema, prueba social, precios y cierre siguiendo la misma estructura YAML.
3. Generar un guión de clip social
meta:
title: "Acme en 30 Segundos"
duration: "30s"
type: social
resolution: 1080x1920
fps: 30
audience: "Desarrolladores navegando por feeds sociales"
tone: "enérgico, contundente, moderno"
total_frames: 900
scenes:
- id: hook
duration: "3s"
frames: 90
narration: "Deja de construir paneles desde cero."
visual: "Texto en negrita sobre fondo degradado vibrante"
animation: "el texto aparece bruscamente desde arriba en 8 fotogramas, la pantalla tiembla durante 4 fotogramas"
music:
track: "electronic-pulse"
volume: 0.5
duck: true
sfx:
- type: "impact-hit"
at: "0.2s"
duration: "0.3s"
transition_to_next: "hard-cut"
- id: demo
duration: "12s"
frames: 360
narration: "Escribe lo que necesitas. Acme lo construye en vivo."
visual: "Grabación de pantalla: escribiendo una solicitud, el panel se genera en tiempo real"
animation: "escritura durante 120 fotogramas, el panel se construye en los 240 fotogramas restantes"
music:
track: "electronic-pulse"
volume: 0.3
duck: true
sfx:
- type: "keyboard-typing"
at: "0.5s"
duration: "4s"
transition_to_next: "hard-cut"
- id: result
duration: "8s"
frames: 240
narration: "Completamente interactivo. Datos en tiempo real. Listo para compartir."
visual: "Panel terminado con interacciones de desplazamiento, datos actualizándose en vivo"
animation: "el cursor se desplaza activando información sobre herramientas, los datos se actualizan en el fotograma 120"
music:
track: "electronic-pulse"
volume: 0.3
duck: true
sfx: []
transition_to_next: "hard-cut"
- id: cta
duration: "7s"
frames: 210
narration: "Prueba gratis en acme.dev."
visual: "Texto de CTA grande y centrado, URL debajo, fondo degradado de marca"
animation: "el texto escala de 0 a tamaño completo en 15 fotogramas, se mantiene"
music:
track: "electronic-pulse"
volume: 0.5
duck: false
sfx: []
transition_to_next: "none"
4. Calcular recuentos de fotogramas a partir de la duración
Entrada: duración = 60s, fps = 30
Salida: total_frames = 1800
Desglose de escenas:
intro: 4s * 30 = 120 fotogramas
feature-1: 8s * 30 = 240 fotogramas
feature-2: 8s * 30 = 240 fotogramas
proof: 6s * 30 = 180 fotogramas
cta: 6s * 30 = 180 fotogramas
---
Suma: 32s = 960 fotogramas (los 840 fotogramas restantes necesitan más escenas)
Siempre verifica la suma. Si las escenas no suman, ajusta o agrega escenas.
5. Escribir texto de narración efectivo
Reglas:
- Máximo 15 palabras por oración - las más largas no se pueden leer a tiempo
- Voz activa, tiempo presente - "Acme construye tu panel" no "será construido"
- Haz coincidir la narración con lo visual - habla sobre lo que está en pantalla
- Una idea por escena - no incluyas dos conceptos en una sola línea
- Lidera con el beneficio - "Ahorra 10 horas a la semana" no "Nuestra función de seguimiento de tiempo"
- Incluye pausas - narración vacía (
"") para dar espacio para respirar - Velocidad de lectura - aproximadamente 2.5 palabras por segundo
| Malo | Bueno | Por qué |
|---|---|---|
| "Nuestro producto ha sido diseñado para ayudar a los equipos a construir paneles más rápido" | "Construye paneles en minutos, no en semanas." | Demasiado largo, pasivo |
| "Haz clic en el botón más en la esquina superior derecha" | "Agrega un widget con un solo clic." | Deja que lo visual muestre la ubicación |
| "Como puedes ver, los datos se actualizan en tiempo real" | "Datos en tiempo real. Siempre actualizados." | "Como puedes ver" es relleno |
6. Planificar transiciones de escena
| Transición | Cuándo usarla |
|---|---|
hard-cut | Mismo tema, ritmo rápido, o contraste abrupto |
cross-dissolve | Cambio de tema suave, contenido relacionado fluyendo |
fade-to-black | Final de sección, pausa dramática, escena final |
wipe-left / wipe-right | Comparaciones antes/después, progresión de línea de tiempo |
none | Escena final del video |
Regla: usa como máximo 2 tipos de transición diferentes por video para mantener la coherencia.
7. Revisar un guión basándose en comentarios
- Identifica el tipo de comentario: ritmo, narración, visuales, estructura o tono
- Localiza las escenas afectadas por
iden el YAML - Aplica cambios solo a los campos afectados, conserva el cálculo de fotogramas
- Vuelve a validar: las duraciones de las escenas deben sumar la duración total
- Vuelve a calcular los fotogramas si cambió alguna duración
- Documenta lo que cambió:
# Revisión: se acortó la intro de 6s a 4s según los comentarios (v2)
- id: intro
duration: "4s" # era 6s
frames: 120 # era 180
Antipatrones / errores comunes
| Error | Por qué está mal | Qué hacer en su lugar |
|---|---|---|
| Escribir la narración antes que lo visual | Lleva el video a un territorio de "cabeza parlante" | Escribe visual primero, luego narración para complementar |
| Escenas de más de 12 segundos | Los espectadores pierden la atención, el ritmo se siente lento | Divide en dos escenas más cortas |
| Recuentos de fotogramas no coincidentes | El motor de renderizado produce tiempos incorrectos o falla | Siempre calcula frames = duration * fps y verifica las sumas |
| Narración de más de 15 palabras por oración | No se puede leer dentro de la duración de la escena | Divide en oraciones más cortas |
| Sin gancho en los primeros 3 segundos | Los espectadores sociales pasan de largo, los espectadores integrados se desconectan | Abre con una declaración audaz, una pregunta o una sorpresa visual |
| Transiciones inconsistentes | El video se siente entrecortado y poco profesional | Usa como máximo 2 tipos de transición por video |
| Saltarse la entrevista | Produce guiones genéricos que no dan en el blanco | Siempre recopila los requisitos primero |
| Descripciones visuales vacías | El ingeniero de renderizado no puede construir la escena | Sé específico sobre el diseño, los colores, el movimiento y los elementos |
Trampas
-
Redondeo del recuento de fotogramas - Cuando la duración no se divide uniformemente (ej., 3.5s a 24fps = 84 fotogramas), redondea al entero más cercano y ajusta la última escena. Nunca dejes fotogramas fraccionarios: los motores de renderizado los truncan o generan errores.
-
Desbordamiento de tiempo de la narración - A 2.5 palabras/segundo, una escena de 4s contiene aproximadamente 10 palabras. Escribir 20 palabras para una escena de 4s significa narración apresurada o recorte. Siempre verifica el recuento de palabras con la duración de la escena.
-
Resolución vertical vs horizontal - Los clips sociales (TikTok, Reels, Shorts) usan 1080x1920 (vertical). Las inserciones de YouTube/sitios web usan 1920x1080 o 3840x2160. Confirma el canal de distribución antes de establecer la resolución.
-
Conflictos de reducción de volumen de música - Si cada escena tiene
duck: true, el volumen de la música sube y baja constantemente. Usa la reducción de volumen solo cuando haya narración. Las escenas con narración vacía deben tenerduck: false. -
Desviación de la duración total - Después de las revisiones, las duraciones de las escenas pueden cambiar. Siempre vuelve a calcular la duración total sumando todas las duraciones de las escenas. Si la suma se desvía de la duración prevista, ajusta las escenas o actualiza la meta.
Ejemplo de guión completo
A continuación se muestra un guión de demostración de producto de 60 segundos completo con 10 escenas:
meta:
title: "Acme Dashboard - Demostración de producto"
duration: "60s"
type: demo
resolution: 3840x2160
fps: 30
audience: "Fundadores de SaaS y gerentes de producto"
tone: "profesional, seguro, minimalista"
total_frames: 1800
scenes:
- id: hook
duration: "4s"
frames: 120
narration: "¿Cansado de los paneles que requieren días de configuración?"
visual: "Primer plano de un cronómetro corriendo, con fallos al final"
animation: "cronómetro de 0 a 4 días en 100 fotogramas, congelación y fallo en los últimos 20 fotogramas"
music:
track: "tension-buildup"
volume: 0.3
duck: true
sfx:
- type: "clock-ticking"
at: "0.5s"
duration: "3.5s"
transition_to_next: "hard-cut"
- id: problem
duration: "6s"
frames: 180
narration: "Los paneles tradicionales te obligan a codificar cada widget manualmente."
visual: "Desarrollador frustrado mirando código complejo en una pantalla dividida"
animation: "código desplazándose rápidamente en el lado izquierdo, panel vacío en el derecho"
music:
track: "tension-buildup"
volume: 0.2
duck: true
sfx: []
transition_to_next: "cross-dissolve"
- id: solution
duration: "8s"
frames: 240
narration: "Acme cambia eso. Describe lo que necesitas. El panel se construye solo."
visual: "Entrada de texto en la interfaz de Acme, el usuario escribe: 'panel de ventas con gráfico de barras'"
animation: "animación de escritura en 60 fotogramas, panel generándose en 180 fotogramas"
music:
track: "upbeat-corporate"
volume: 0.2
duck: true
sfx:
- type: "keyboard-typing"
at: "0.3s"
duration: "2s"
- type: "whoosh"
at: "4s"
duration: "1s"
transition_to_next: "cross-dissolve"
- id: results
duration: "10s"
frames: 300
narration: "Arrastra para reorganizar. Haz clic para profundizar. Datos en vivo."
visual: "Panel terminado con widgets interactivos, efectos de desplazamiento"
animation: "el cursor arrastra un widget en el fotograma 30, se activa información sobre herramientas en el fotograma 120, los datos se actualizan en el fotograma 200"
music:
track: "upbeat-corporate"
volume: 0.3
duck: true
sfx:
- type: "soft-click"
at: "1.0s"
duration: "0.2s"
- type: "data-chime"
at: "6.7s"
duration: "1.0s"
transition_to_next: "hard-cut"
- id: cta
duration: "6s"
frames: 180
narration: "Prueba Acme gratis en acme.dev. Crea tu primer panel en minutos."
visual: "Pantalla final: CTA grande, URL, fondo degradado de marca"
animation: "texto que aparece y se mantiene, fondo degradado animado sutil"
music:
track: "upbeat-corporate"
volume: 0.5
duck: false
sfx: []
transition_to_next: "fade-to-black"
Referencias
- Consulta
references/interview-questions.mdpara el marco completo de preguntas de la entrevista - Consulta
references/tone-style.mdpara descripciones detalladas de tono y estilo - Consulta
references/animation-library.mdpara animaciones disponibles y sus parámetros