Documentación del Formato JSON para Videos

Esta documentación describe el formato JSON utilizado para crear videos con SimpleVideoRenderer.

Estructura General

{
    "output": {
        // Configuración de salida del video
    },
    "timeline": [
        // Array de clips que componen el video
    ]
}

Configuración de Salida (output)

Define las propiedades técnicas del video final.

"output": {
    "fps": 30,                    // Frames por segundo (obligatorio)
    "format": "mp4",              // Formato del video (obligatorio)
    "durationInFrames": 450,      // Duración total en frames (obligatorio)
    "width": 1920,                // Ancho en píxeles (obligatorio)
    "height": 1080,               // Alto en píxeles (obligatorio)
    "codec": "h264"               // Códec de video (obligatorio)
}

Opciones disponibles:

• fps: 30, 60, 24, etc.
• format: "mp4", "mov", "webm"
• codec: "h264", "h265", "vp8", "vp9"

Timeline

Array de clips que se reproducen en secuencia. Cada clip es un objeto con la siguiente estructura:

Propiedades Básicas del Clip

{
    "asset": {
        // Definición del contenido del clip
    },
    "start": 0,          // Tiempo de inicio en segundos (obligatorio)
    "length": 5,         // Duración en segundos (obligatorio)
    "position": "center", // Posición en pantalla (opcional)
    "offsetX": 0,        // Desplazamiento horizontal en píxeles (opcional)
    "offsetY": 0,        // Desplazamiento vertical en píxeles (opcional)
    "fit": "cover",      // Modo de ajuste para imágenes/videos (opcional)
    "scale": 1.0,        // Escala base del elemento (opcional)
    "transition": {},    // Configuración de transiciones (opcional)
    "effects": [],       // Array de efectos (opcional)
    "mask": {}           // Máscara para recortar el clip (opcional)
}

Tipos de Assets

1. Imagen

"asset": {
    "type": "image",
    "src": "https://example.com/image.jpg"  // URL o ruta del archivo
}

2. Video

"asset": {
    "type": "video",
    "src": "https://example.com/video.mp4",  // URL o ruta del archivo
    "volume": 0.5,                          // Volumen del video (0.0 - 1.0, por defecto 1.0)
    "muted": false,                         // Si el video debe estar silenciado (por defecto false)
    "loop": false,                          // Si el video debe reproducirse en bucle (por defecto false)
    "playbackRate": 1.0,                    // Velocidad de reproducción (0.25 - 2.0, por defecto 1.0)
    "delayStart": 0                         // Segundos de delay antes de reproducir (por defecto 0)
}

Propiedades del video:

• src: URL o ruta del archivo de video (obligatorio)
• volume: Volumen del audio del video de 0 a 1 (opcional, por defecto 1.0)
• muted: Si el video debe estar completamente silenciado (opcional, por defecto false)
• loop: Si el video debe reproducirse en bucle para llenar el length del clip (opcional, por defecto false)
• playbackRate: Velocidad de reproducción del video (opcional, por defecto 1.0)
  • 0.25: Cuarta parte de la velocidad (muy lento)
  • 0.5: Mitad de la velocidad (lento)
  • 1.0: Velocidad normal
  • 1.5: Una vez y media la velocidad
  • 2.0: Doble velocidad (rápido)
• delayStart: Segundos de delay antes de empezar a reproducir el video (opcional, por defecto 0)
  • El video se muestra desde el start del clip, pero permanece congelado en el primer frame durante este tiempo
  • Útil para sincronizar videos con audio o crear efectos de pausa inicial
  • Ejemplo: "delayStart": 2.0 → el video se muestra inmediatamente pero no empieza a reproducirse hasta 2 segundos después

Control de audio en videos:

• Video normal con audio: "muted": false, "volume": 1.0
• Video silenciado: "muted": true (ignora el valor de volume)
• Video con audio reducido: "muted": false, "volume": 0.3
• Video de fondo (sin audio): "muted": true

Control de duración con loop:

• Si el video dura 3 segundos pero length es 10 segundos:
  • Sin loop ("loop": false): El video se detiene en el último frame a los 3 segundos
  • Con loop ("loop": true): El video se repite automáticamente hasta completar los 10 segundos

Uso común del asset video:

• Videos de fondo silenciados para crear atmósfera
• Clips con audio controlado para no solaparse con música
• Videos principales con audio completo
• Múltiples capas de video con diferentes niveles de audio
• Videos cortos en bucle (loop: true) cuando el length es mayor que la duración del video

3. Texto

"asset": {
    "type": "text",
    "text": "Tu texto aquí",
    "style": {
        "fontSize": 48,
        "fontFamily": "Arial, sans-serif",
        "color": "#ffffff",
        "textAlign": "center",
        "fontWeight": "bold",
        "textShadow": "0 0 20px rgba(255, 255, 255, 0.8)",
        "letterSpacing": "4px",
        "lineHeight": 1.2,
        "padding": "20px",
        "backgroundColor": "rgba(0, 0, 0, 0.5)",
        "width": "800px",           // Ancho fijo del contenedor de texto
        "maxWidth": "90%",          // Ancho máximo (útil para responsividad)
        "borderRadius": "8px"       // Bordes redondeados
    }
}

4. Color (Overlay/Fondo)

"asset": {
    "type": "color",
    "color": "#000000",    // Color en formato hex, rgb o rgba
    "opacity": 0.7,        // Opacidad del color (0.0 - 1.0)
    "width": 1920,         // Ancho del rectángulo de color (número en px o string con unidad). Default: "100%"
    "height": 1080         // Alto del rectángulo de color (número en px o string con unidad). Default: "100%"
}

Propiedades del asset color:

• color: Color en formato hex (#000000), rgb (rgb(0,0,0)) o rgba (rgba(0,0,0,0.5))
• opacity: Opacidad del color de 0.0 (transparente) a 1.0 (opaco). Default: 1.0
• width: Ancho del rectángulo. Puede ser número (se convierte a px) o string ("50%", "1920px"). Default: "100%"
• height: Alto del rectángulo. Puede ser número (se convierte a px) o string ("50%", "1080px"). Default: "100%"

Uso común del asset color:

• Overlays semitransparentes sobre imágenes/videos
• Fondos sólidos cuando no necesitas imagen
• Transiciones de color entre secciones
• Efectos de fade to black/white
• Capas de ambiente para crear atmósferas
• Rectángulos de color con tamaño personalizado usando width y height

5. Audio (Banda Sonora)

"asset": {
    "type": "audio",
    "src": "https://example.com/music.mp3",  // URL o ruta del archivo
    "volume": 0.8,                          // Volumen (0.0 - 1.0, por defecto 1.0)
    "fadeIn": 1.0,                          // Duración del fade in en segundos
    "fadeOut": 2.0,                         // Duración del fade out en segundos
    "loop": false,                          // Si el audio debe repetirse
    "startFrom": 5                          // Segundo desde el cual empezar el audio
}

Propiedades del audio:

• src: URL o ruta del archivo de audio (obligatorio)
• volume: Volumen del audio de 0 a 1 (opcional, por defecto 1.0)
• fadeIn: Duración del efecto fade in en segundos (opcional)
• fadeOut: Duración del efecto fade out en segundos (opcional)
• loop: Si el audio debe repetirse cuando termina (opcional, por defecto false)
• startFrom: Segundo específico desde el cual empezar la reproducción del audio (opcional)

Uso común del asset audio:

• Música de fondo para todo el video
• Efectos de sonido sincronizados con transiciones
• Narración o voz en off
• Capas de ambiente sonoras
• Múltiples pistas de audio superpuestas

6. Text-to-Speech (TTS)

"asset": {
    "type": "tts",
    "text": "Este es el texto que se convertirá en voz",  // Texto a sintetizar (obligatorio)
    "voice": "Lucia",                                   // Nombre de la voz (obligatorio)
    "languageCode": "es-ES",                           // Código de idioma (obligatorio)
    "engine": "neural",                                // Motor TTS: "neural" o "standard" (opcional, por defecto "neural")
    "volume": 1.0,                                     // Volumen (0.0 - 1.0, opcional)
    "fadeIn": 0.2,                                     // Fade in en segundos (opcional)
    "fadeOut": 0.2,                                    // Fade out en segundos (opcional)
    "generateSubtitles": {                             // Generar subtítulos automáticos (opcional)
        "enabled": true,
        "wordsPerLine": 10,                            // Palabras por línea de subtítulo (por defecto 10)
        "subtitleStyle": {                             // Estilo de los subtítulos (opcional)
            "fontSize": 48,
            "color": "#FFFFFF",
            "backgroundColor": "#000000",
            "backgroundOpacity": 0.8
        },
        "subtitlePosition": "bottom",                  // "top" | "center" | "bottom"
        "subtitleAnimation": "fade",                   // "none" | "fade" | "slide"
        "subtitleAnimationOut": "fade"                 // "none" | "fade" | "slide" (opcional)
    }
}

Propiedades del TTS:

• text: Texto que se convertirá en voz (obligatorio)
• voice: Nombre de la voz de AWS Polly (obligatorio)
  • Español: Lucia, Sergio, Mia, Andres, Lupe, Pedro
  • Inglés US: Joanna, Matthew, Ivy, Justin, Kendra, Kimberly, Salli, Joey, Ruth, Stephen
  • Inglés UK: Amy, Emma, Brian, Arthur, Olivia
  • Y muchas más en otros idiomas
• languageCode: Código de idioma (obligatorio)
  • Español: es-ES (España), es-MX (México), es-US (Estados Unidos)
  • Inglés: en-US (Estados Unidos), en-GB (Reino Unido), en-AU (Australia)
  • Otros: fr-FR, de-DE, it-IT, pt-BR, ja-JP, etc.
• engine: Motor de síntesis (opcional, por defecto "neural")
  • "neural": Voces más naturales y expresivas (recomendado)
  • "standard": Voces clásicas (menos naturales)
• volume: Volumen del audio de 0 a 1 (opcional, por defecto 1.0)
• fadeIn: Duración del fade in en segundos (opcional)
• fadeOut: Duración del fade out en segundos (opcional)
• generateSubtitles: Configuración para generar subtítulos automáticos (opcional)
  • enabled: Si se deben generar subtítulos (obligatorio dentro de generateSubtitles)
  • wordsPerLine: Número de palabras por línea de subtítulo (opcional, por defecto 10)
  • subtitleStyle: Estilo visual de los subtítulos (opcional)
  • subtitlePosition: Posición de los subtítulos (opcional, por defecto "bottom")
  • subtitleAnimation: Animación de entrada de los subtítulos (opcional, por defecto "fade")
  • subtitleAnimationOut: Animación de salida de los subtítulos (opcional, por defecto "none")

Duración dinámica con expresiones: El TTS genera audio de duración variable según el texto. Usa expresiones dinámicas para ajustar la duración:

{
    "asset": {
        "type": "tts",
        "text": "Tu texto aquí",
        "voice": "Lucia",
        "languageCode": "es-ES"
    },
    "start": 0,
    "length": "{{tts.duration}}"    // Se resuelve automáticamente a la duración real del audio
}

Uso común del asset TTS:

• Narración automática de textos
• Voces en off generadas dinámicamente
• Locuciones sin necesidad de grabar audio
• Contenido multiidioma fácil de generar
• Generación masiva de videos con diferentes textos

7. Subtítulos (Archivos .ass)

"asset": {
    "type": "subtitle",
    "src": "subtitles.ass",                    // Ruta del archivo .ass
    "subtitleStyle": {                         // Estilo personalizado (opcional)
        "fontSize": 56,
        "fontFamily": "Impact, sans-serif",
        "color": "#FFD700",
        "backgroundColor": "rgba(0, 0, 0, 0.8)",
        "backgroundOpacity": 1,
        "textShadow": "2px 2px 4px rgba(0,0,0,0.8)",
        "borderRadius": 12,
        "padding": "15px 30px",
        "lineHeight": 1.2,
        "fontWeight": "900",
        "italic": false,
        "uppercase": false,
        "letterSpacing": "2px"
    },
    "subtitlePosition": "bottom",              // "top" | "center" | "bottom" | "custom"
    "subtitleAlign": "center",                 // "left" | "center" | "right"
    "subtitleOffsetY": -20,                    // Desplazamiento vertical en píxeles
    "subtitleAnimation": "fade",               // "none" | "fade" | "slide" | "typewriter" | "bounce"
    "subtitleAnimationOut": "slide",           // "none" | "fade" | "slide" | "typewriter" | "bounce" (opcional)
    "subtitleEffect": {                        // Efecto visual (opcional)
        "type": "glow",                        // "glow" | "outline" | "3d" | "neon" | "gradient"
        "color": "#FFD700",
        "intensity": 1.5
    },
    "stripStyles": false                       // Ignorar estilos del archivo .ass
}

Propiedades de subtítulos:

Estilo (subtitleStyle):

• fontSize: Tamaño del texto en píxeles
• fontFamily: Familia tipográfica
• color: Color del texto
• backgroundColor: Color de fondo del contenedor
• backgroundOpacity: Opacidad del fondo (0-1)
• textShadow: Sombra del texto (sintaxis CSS)
• borderRadius: Radio de bordes en píxeles
• padding: Espaciado interno
• lineHeight: Altura de línea
• fontWeight: Peso de la fuente
• italic: Texto en cursiva
• uppercase: Convertir a mayúsculas
• letterSpacing: Espaciado entre letras

Posicionamiento:

• subtitlePosition: Posición vertical del subtítulo
  • "top": Parte superior de la pantalla
  • "center": Centro de la pantalla
  • "bottom": Parte inferior (por defecto)
  • "custom": Posición personalizada con offset
• subtitleAlign: Alineación horizontal
• subtitleOffsetY: Desplazamiento vertical adicional

Animaciones de entrada (subtitleAnimation):

• none: Sin animación
• fade: Desvanecimiento suave (aparece gradualmente)
• slide: Deslizamiento desde abajo hacia arriba
• typewriter: Efecto máquina de escribir (letra por letra)
• bounce: Rebote elástico al aparecer

Animaciones de salida (subtitleAnimationOut):

• none: Sin animación de salida (por defecto)
• fade: Desvanecimiento suave (desaparece gradualmente)
• slide: Deslizamiento hacia abajo
• typewriter: Efecto máquina de escribir inverso (letra por letra desapareciendo)
• bounce: Rebote elástico al desaparecer

Si no se especifica subtitleAnimationOut, el subtítulo desaparecerá sin animación.

Efectos visuales (subtitleEffect):

• glow: Resplandor alrededor del texto
• outline: Contorno sólido
• 3d: Efecto de profundidad 3D
• neon: Efecto neón luminoso
• gradient: Degradado de colores

Uso común de subtítulos:

• Traducción del contenido hablado
• Karaoke con sincronización precisa
• Información contextual durante el video
• Créditos y títulos animados
• Accesibilidad para personas con discapacidad auditiva

Propiedades de estilo para texto:

• fontSize: Tamaño de fuente en píxeles
• fontFamily: Familia tipográfica (soporta fuentes web estándar)
• color: Color del texto (hex, rgb, rgba)
• textAlign: Alineación del texto ("left", "center", "right", "justify")
• fontWeight: Peso de la fuente ("normal", "bold", "900", etc.)
• textShadow: Sombra del texto (sintaxis CSS)
• letterSpacing: Espaciado entre letras
• lineHeight: Altura de línea (número o string con unidades)
• padding: Espaciado interno
• backgroundColor: Color de fondo del contenedor
• width: Ancho fijo del contenedor de texto (ej: "1800px", "80%")
• maxWidth: Ancho máximo del contenedor (por defecto "90%")
• borderRadius: Radio de bordes redondeados
• border: Borde del contenedor (sintaxis CSS)
• boxShadow: Sombra del contenedor (sintaxis CSS)

Posicionamiento

Posiciones Básicas (position)

• "top-left" - Esquina superior izquierda
• "top" - Centro superior
• "top-right" - Esquina superior derecha
• "center-left" - Centro izquierda
• "center" - Centro (por defecto)
• "center-right" - Centro derecha
• "bottom-left" - Esquina inferior izquierda
• "bottom" - Centro inferior
• "bottom-right" - Esquina inferior derecha
• "left" - Centro izquierda (equivalente a center-left)
• "right" - Centro derecha (equivalente a center-right)

Ajustes de Imagen/Video (fit)

• "cover" - Cubre todo el área (puede recortar)
• "contain" - Ajusta dentro del área (puede tener barras negras)
• "fill" - Estira para llenar (puede deformar)

Transiciones

Las transiciones controlan cómo aparece o desaparece un clip. Puedes usar una sola transición o un array de múltiples transiciones que se aplicarán simultáneamente.

Una sola transición

"transition": {
    "in": {
        "type": "fade",           // Tipo de transición
        "duration": 0.5,          // Duración en segundos
        "easing": "easeOut"       // Función de easing
    },
    "out": {
        "type": "slide",
        "direction": "left",
        "duration": 0.8,
        "easing": "easeInOut"
    }
}

Múltiples transiciones (array)

"transition": {
    "in": [
        {
            "type": "fade",
            "duration": 0.5
        },
        {
            "type": "slide",
            "direction": "left",
            "duration": 0.8
        }
    ],
    "out": [
        {
            "type": "fade",
            "duration": 0.5
        },
        {
            "type": "slide",
            "direction": "right",
            "duration": 0.8
        }
    ]
}

Tipos de Transición

• "fade" - Desvanecimiento
• "slide" - Deslizamiento
• "circle" - Expansión/contracción circular
• "horzopen" - Apertura horizontal
• "hrzslice" - Corte horizontal
• "wipe" - Barrido
• "move" - Movimiento desde/hacia una posición específica

Transición Move

La transición move permite mover un clip desde una posición inicial a su posición final (para in) o desde su posición a una posición final (para out).

Para transición IN:

{
    "type": "move",
    "fromX": -500,        // Posición X inicial (opcional, por defecto: offsetX del clip)
    "fromY": -300,        // Posición Y inicial (opcional, por defecto: offsetY del clip)
    "duration": 0.8,
    "easing": "easeOut"
}

Para transición OUT:

{
    "type": "move",
    "toX": 1000,          // Posición X final (opcional, por defecto: offsetX del clip)
    "toY": -500,          // Posición Y final (opcional, por defecto: offsetY del clip)
    "duration": 0.5,
    "easing": "easeIn"
}

• Si no especificas fromX o fromY, se usa la posición definida en offsetX/offsetY del clip
• Si no especificas toX o toY, se usa la posición definida en offsetX/offsetY del clip
• Puedes especificar solo fromX o fromY para mover en un solo eje

Direcciones (para slide, wipe, etc.)

• "left" - Hacia la izquierda
• "right" - Hacia la derecha
• "up" - Hacia arriba
• "down" - Hacia abajo
• "in" - Hacia adentro (para circle)
• "out" - Hacia afuera (para circle)

Funciones de Easing

• "linear" - Velocidad constante
• "easeIn" - Aceleración al inicio
• "easeOut" - Desaceleración al final
• "easeInOut" - Aceleración y desaceleración
• "easeOutElastic" - Efecto elástico al final
• "easeOutBounce" - Efecto rebote al final
• "easeOutBack" - Sobrepasa y vuelve

Efectos

Los efectos modifican las propiedades del clip durante su reproducción.

1. Zoom

{
    "type": "zoom",
    "from": 1.0,        // Escala inicial
    "to": 1.2,          // Escala final
    "duration": 2.0,    // Duración del efecto en segundos
    "startTime": 0,     // Tiempo de inicio relativo al clip
    "easing": "easeOut" // Función de easing (opcional)
}

2. Panorámica Horizontal (Pan)

{
    "type": "pan",
    "to": -10,          // Posición final relativa (negativo = izquierda)
    "duration": 3.0,
    "startTime": 0,
    "easing": "easeOut" // Función de easing (opcional)
}

3. Panorámica Vertical (PanY)

{
    "type": "panY",
    "to": 15,           // Posición final relativa (positivo = abajo)
    "duration": 2.5,
    "startTime": 1.0,
    "easing": "easeInOut" // Función de easing (opcional)
}

4. Desenfoque (Blur)

{
    "type": "blur",
    "from": 0,          // Desenfoque inicial
    "to": 5,            // Desenfoque final
    "duration": 1.0,
    "startTime": 0,
    "easing": "linear"  // Función de easing (opcional)
}

5. Rotación (Rotate)

Aplica una rotación progresiva al elemento. Los valores son en grados (360° = una vuelta completa).

{
    "type": "rotate",
    "from": 0,          // Ángulo inicial en grados
    "to": 360,          // Ángulo final en grados
    "duration": 2.0,    // Duración del efecto en segundos
    "startTime": 0,     // Tiempo de inicio relativo al clip
    "easing": "easeOut" // Función de easing (opcional)
}

Ejemplos de uso:

• Rotación completa: from: 0, to: 360 - Una vuelta completa
• Doble rotación: from: 0, to: 720 - Dos vueltas completas
• Rotación parcial: from: 0, to: 45 - Giro de 45 grados
• Rotación invertida: from: 360, to: 0 - Giro en sentido contrario
• Múltiples rotaciones encadenadas: Usa múltiples efectos rotate con diferentes startTime

"effects": [
    {
        "type": "rotate",
        "from": 0,
        "to": 360,
        "duration": 1.5,
        "startTime": 0,
        "easing": "easeOutQuint"
    },
    {
        "type": "rotate",
        "from": 360,
        "to": 720,
        "duration": 1.2,
        "startTime": 1.5,
        "easing": "easeInQuint"
    }
]

6. Easing Independiente

Efecto independiente que aplica una función de easing específica a la escala del elemento. Útil para crear efectos de rebote, elásticos, etc. Se combina multiplicativamente con otros efectos.

{
    "type": "easing",
    "property": "easeOutElastic",  // Tipo de easing (obligatorio)
    "from": 1.0,                   // Escala inicial (opcional, por defecto 1.0)
    "to": 1.3,                     // Escala final (opcional, por defecto 1.2)
    "duration": 1.5,               // Duración del efecto en segundos
    "startTime": 0.8               // Tiempo de inicio relativo al clip
}

Tipos de easing disponibles para property:

• "easeOutElastic" - Efecto elástico al final
• "easeOutBounce" - Efecto rebote al final
• "easeOutBack" - Sobrepasa y vuelve
• "easeIn" - Aceleración al inicio
• "easeOut" - Desaceleración al final
• "easeInOut" - Aceleración y desaceleración
• "linear" - Velocidad constante

Máscaras (Masks)

Las máscaras permiten recortar el contenido de un clip en formas específicas. El contenido solo se muestra dentro de la forma de la máscara.

Tipos de Máscaras

1. Máscara Circular

"mask": {
    "type": "circle",
    "radius": 300,              // Radio del círculo en píxeles
    "position": "center",       // Posición de la máscara (igual que clips)
    "offsetX": 0,               // Ajuste horizontal (opcional)
    "offsetY": 0                // Ajuste vertical (opcional)
}

Propiedades:

• radius: Radio del círculo en píxeles (obligatorio para circle)
• position: Posición base de la máscara (opcional, por defecto "center")
• offsetX/offsetY: Ajustes finos de posición en píxeles (opcional)

2. Máscara Rectangular

"mask": {
    "type": "rectangle",
    "width": 800,               // Ancho del rectángulo en píxeles
    "height": 600,              // Alto del rectángulo en píxeles
    "borderRadius": 20,         // Bordes redondeados (opcional)
    "position": "center",       // Posición de la máscara
    "offsetX": 0,
    "offsetY": 0
}

Propiedades:

• width: Ancho del rectángulo en píxeles (obligatorio para rectangle)
• height: Alto del rectángulo en píxeles (obligatorio para rectangle)
• borderRadius: Radio de las esquinas redondeadas en píxeles (opcional)
• position: Posición base de la máscara (opcional, por defecto "center")
• offsetX/offsetY: Ajustes finos de posición en píxeles (opcional)

3. Máscara Elíptica

"mask": {
    "type": "ellipse",
    "radiusX": 400,             // Radio horizontal en píxeles
    "radiusY": 200,             // Radio vertical en píxeles
    "position": "center",
    "offsetX": 0,
    "offsetY": 0
}

Propiedades:

• radiusX: Radio horizontal de la elipse en píxeles (obligatorio para ellipse)
• radiusY: Radio vertical de la elipse en píxeles (obligatorio para ellipse)
• position: Posición base de la máscara (opcional, por defecto "center")
• offsetX/offsetY: Ajustes finos de posición en píxeles (opcional)

Posiciones Disponibles para Máscaras

Las máscaras usan el mismo sistema de posicionamiento que los clips:

• "center" - Centro del clip (por defecto)
• "top-left", "top", "top-right"
• "center-left", "center-right" (o simplemente "left", "right")
• "bottom-left", "bottom", "bottom-right"

Ejemplos de Uso

Imagen circular (perfil):

{
    "asset": {
        "type": "image",
        "src": "portrait.jpg"
    },
    "start": 0,
    "length": 5,
    "position": "center",
    "scale": 0.5,
    "mask": {
        "type": "circle",
        "radius": 200,
        "position": "center"
    }
}

Video en ventana redondeada:

{
    "asset": {
        "type": "video",
        "src": "clip.mp4"
    },
    "start": 0,
    "length": 10,
    "position": "top-right",
    "offsetX": -50,
    "offsetY": 50,
    "scale": 0.3,
    "mask": {
        "type": "rectangle",
        "width": 400,
        "height": 300,
        "borderRadius": 30,
        "position": "center"
    }
}

Imagen en forma elíptica:

{
    "asset": {
        "type": "image",
        "src": "background.jpg"
    },
    "start": 0,
    "length": 8,
    "position": "center",
    "mask": {
        "type": "ellipse",
        "radiusX": 600,
        "radiusY": 300,
        "position": "center",
        "offsetY": -100
    }
}

Notas Importantes sobre Máscaras

• Combinación con transiciones: Las transiciones tienen prioridad sobre las máscaras. Durante una transición, la máscara no se aplica.
• Posición relativa: La posición de la máscara es relativa al clip, no al canvas del video.
• Rendimiento: Las máscaras son eficientes ya que usan clip-path de CSS.
• Uso común:
  • Crear videos picture-in-picture circulares o redondeados
  • Recortar imágenes en formas específicas
  • Efectos de spotlight o viñeta
  • Diseños creativos con múltiples capas

Ejemplo Completo

{
    "output": {
        "fps": 30,
        "format": "mp4",
        "durationInFrames": 450,
        "width": 1920,
        "height": 1080,
        "codec": "h264"
    },
    "timeline": [
        {
            "asset": {
                "type": "audio",
                "src": "https://example.com/music.mp3",
                "volume": 0.7,
                "fadeIn": 1,
                "fadeOut": 2
            },
            "start": 0,
            "length": 15
        },
        {
            "asset": {
                "type": "image",
                "src": "https://example.com/background.jpg"
            },
            "start": 0,
            "length": 5,
            "position": "center",
            "fit": "cover",
            "scale": 1.1,
            "transition": {
                "in": {
                    "type": "circle",
                    "direction": "in",
                    "duration": 0.8,
                    "easing": "easeOut"
                }
            },
            "effects": [
                {
                    "type": "zoom",
                    "from": 1.1,
                    "to": 1.3,
                    "duration": 5,
                    "easing": "linear"
                }
            ]
        },
        {
            "asset": {
                "type": "color",
                "color": "#000000",
                "opacity": 0.6
            },
            "start": 0,
            "length": 5,
            "position": "center"
        },
        {
            "asset": {
                "type": "text",
                "text": "BIENVENIDOS",
                "style": {
                    "fontSize": 120,
                    "fontFamily": "Arial Black, sans-serif",
                    "color": "#ffffff",
                    "textAlign": "center",
                    "fontWeight": "900",
                    "textShadow": "0 0 30px rgba(255, 255, 255, 0.8)",
                    "letterSpacing": "8px",
                    "width": "1600px",
                    "maxWidth": "90%"
                }
            },
            "start": 1.5,
            "length": 3.5,
            "position": "center",
            "transition": {
                "in": {
                    "type": "circle",
                    "direction": "in",
                    "duration": 0.8,
                    "easing": "easeIn"
                }
            },
            "effects": [
                {
                    "type": "zoom",
                    "from": 0.3,
                    "to": 1.2,
                    "duration": 1.2,
                    "startTime": 0,
                    "easing": "easeOutElastic"
                }
            ]
        }
    ]
}

Ejemplo con Control de Audio en Videos

{
    "output": {
        "fps": 30,
        "format": "mp4",
        "durationInFrames": 600,
        "width": 1920,
        "height": 1080,
        "codec": "h264"
    },
    "timeline": [
        {
            "asset": {
                "type": "video",
                "src": "https://example.com/background-video.mp4",
                "muted": true
            },
            "start": 0,
            "length": 20,
            "position": "center",
            "fit": "cover",
            "scale": 1.1
        },
        {
            "asset": {
                "type": "audio",
                "src": "https://example.com/music.mp3",
                "volume": 0.6,
                "fadeIn": 2,
                "fadeOut": 2
            },
            "start": 0,
            "length": 20
        },
        {
            "asset": {
                "type": "video",
                "src": "https://example.com/main-content.mp4",
                "volume": 0.8,
                "muted": false
            },
            "start": 5,
            "length": 10,
            "position": "center",
            "scale": 0.7,
            "transition": {
                "in": {
                    "type": "circle",
                    "direction": "in",
                    "duration": 1,
                    "easing": "easeOut"
                },
                "out": {
                    "type": "fade",
                    "duration": 0.5
                }
            }
        },
        {
            "asset": {
                "type": "video",
                "src": "https://example.com/outro-video.mp4",
                "volume": 0.3,
                "muted": false
            },
            "start": 16,
            "length": 4,
            "position": "bottom-right",
            "scale": 0.4,
            "offsetX": -50,
            "offsetY": -50
        }
    ]
}

En este ejemplo:

• Video de fondo: Completamente silenciado (muted: true) para no interferir
• Música de ambiente: Volumen reducido (0.6) con fades suaves
• Video principal: Audio controlado (volumen 0.8) durante la parte importante
• Video secundario: Audio muy bajo (volumen 0.3) para no dominar

Expresiones Dinámicas para start y length

Los campos start y length de los clips pueden usar expresiones dinámicas en lugar de valores fijos. Esto permite crear videos donde el timing se calcula automáticamente basándose en otros clips.

Placeholders Legacy para Audio/TTS

Para clips de tipo audio y tts, puedes usar:

{
  "type": "tts",
  "text": "Hello world",
  "voice": "Joanna",
  "language": "en-US",
  "start": 0,
  "length": "{{audio.duration}} + 0.5"
}

Placeholders soportados:

• {{audio.duration}} - Duración del audio procesado
• {{audio.length}} - Alias de audio.duration
• {{tts.duration}} - Duración del TTS generado

Referencias a Otros Clips

Puedes referenciar valores de otros clips usando la sintaxis clipN.propiedad:

{
  "assets": [
    {
      "type": "video",
      "src": "video.mp4",
      "start": 0,
      "length": "clip3.duration"
    },
    {
      "type": "text",
      "text": "Title",
      "start": 1,
      "length": 5
    },
    {
      "type": "text",
      "text": "Subtitle",
      "start": "prev.end",
      "length": 3
    },
    {
      "type": "tts",
      "text": "Long text to speech",
      "voice": "Joanna",
      "start": "clip1.end + 1",
      "length": "{{audio.duration}}"
    }
  ]
}

Propiedades disponibles:

• clipN.start - Tiempo de inicio del clip N
• clipN.end - Tiempo de fin del clip N (start + length)
• clipN.length - Duración del clip N
• clipN.duration - Alias de length

Atajo para clip anterior:

• prev.start - Start del clip anterior
• prev.end - End del clip anterior
• prev.length - Length del clip anterior
• prev.duration - Alias de prev.length

Expresiones Matemáticas

Puedes usar operadores matemáticos y funciones:

{
  "start": "clip1.end + 2",
  "length": "(clip2.length + clip3.length) / 2"
}

Operadores soportados:

• Aritméticos: +, -, *, /, %
• Paréntesis: ( )
• Funciones: min(), max(), abs(), floor(), ceil(), round()

Resolución Multi-Paso

El sistema soporta referencias adelante (forward references). Por ejemplo, clip 0 puede referenciar clip3.duration incluso si clip 3 aún no ha sido procesado:

{
  "assets": [
    {
      "type": "video",
      "src": "background.mp4",
      "start": 0,
      "length": "clip3.duration"  // ✅ Funciona! Se resolverá cuando clip 3 esté listo
    },
    {
      "type": "tts",
      "text": "This determines the video duration",
      "voice": "Joanna",
      "start": 0,
      "length": "{{audio.duration}}"
    }
  ]
}

El sistema procesa los clips en múltiples pasadas:

1. Procesa clips con valores concretos
2. Resuelve expresiones que dependen de clips ya procesados
3. Re-intenta clips pendientes hasta resolver todos
4. Si no se puede resolver, usa valores por defecto (0)

Ejemplos de Uso

Video de fondo con duración del audio:

{
  "assets": [
    {
      "type": "video",
      "src": "background.mp4",
      "length": "clip1.duration"
    },
    {
      "type": "audio",
      "src": "music.mp3"
    }
  ]
}

Secuencia de títulos automática:

{
  "assets": [
    {
      "type": "text",
      "text": "First title",
      "start": 0,
      "length": 3
    },
    {
      "type": "text",
      "text": "Second title",
      "start": "prev.end + 0.5",
      "length": 3
    },
    {
      "type": "text",
      "text": "Third title",
      "start": "prev.end + 0.5",
      "length": 3
    }
  ]
}

TTS con padding:

{
  "type": "tts",
  "text": "Long narration...",
  "voice": "Matthew",
  "start": 5,
  "length": "{{audio.duration}} + 1"
}

Comandos de Renderizado

Renderizar con SimpleVideoRenderer

node render-simple.js nombre-archivo.json

Renderizar con JsonVideoRenderer (estructura diferente)

node render-json.js nombre-archivo.json

Consejos y Mejores Prácticas

1. Timing: Asegúrate de que start + length no exceda durationInFrames / fps
2. Overlapping: Los clips pueden superponerse en tiempo para crear capas
3. Performance: Evita demasiados efectos simultáneos para mejor rendimiento
4. Escalas: Usa scale base + efectos de zoom para control granular
5. Easing: Combina múltiples efectos de easing para animaciones complejas
6. Transiciones: Ajusta las duraciones según el ritmo deseado del video
7. Easing en Transiciones: Todos los tipos de easing funcionan correctamente en transiciones
8. Efectos Combinados: El efecto easing independiente se multiplica con otros efectos de escala
9. Duración de Transiciones: Para efectos elásticos/bounce, usa duraciones más largas (1.5-3s) para mejor visibilidad
10. Width en Textos: Usa width para controlar el ancho exacto del texto, útil para títulos largos
11. MaxWidth para Responsividad: Combina width con maxWidth para textos que se adapten mejor

Valores por Defecto

• position: "center"
• fit: "cover"
• scale: 1.0
• offsetX, offsetY: 0
• startTime (efectos): 0
• duration (efectos): duración del clip
• easing: "linear"
• volume (audio/video): 1.0
• muted (video): false
• from (efecto easing): 1.0
• to (efecto easing): 1.2

Notas Técnicas

• Tiempo de renderizado: Mostrado al final de cada renderizado
• Compatibilidad: Todos los efectos de easing funcionan tanto en efectos como en transiciones
• Multiplicación de efectos: Los efectos de escala se multiplican entre sí (zoom × easing × scale base)
• Precedencia: Los efectos se aplican en el orden que aparecen en el array effects