Estructura JSON y reglas de campos

1. Estructura de nivel superior

La forma JSON completa de nivel superior es:

{
  "meta": {},
  "assets": {},
  "tracks": []
}

Reglas:

meta es obligatorio
tracks es obligatorio y debe contener al menos un track
assets es opcional

No se admite:

video heredado en el nivel superior
audio heredado en el nivel superior

2. `meta`

interface Meta {
  version: string;
  title?: string;
  description?: string;
  author?: string;
  createdAt?: string;
  tags?: string[];
  width: number;
  height: number;
  fps: number;
  background?: string | "transparent" | Gradient;
}

`version`

Tipo: string
Obligatorio: sí
Propósito: marcador de versión del esquema
Valor recomendado: "2.0.0"

`title`

Tipo: string
Obligatorio: no
Propósito: metadatos del título del video

`description`

Tipo: string
Obligatorio: no
Propósito: metadatos de descripción del video

`author`

Tipo: string
Obligatorio: no
Propósito: metadatos del autor

`createdAt`

Tipo: string
Obligatorio: no
Propósito: metadatos de fecha de creación

`tags`

Tipo: string[]
Obligatorio: no
Propósito: metadatos de etiquetado

`width`

Tipo: number
Obligatorio: sí
Restricción: entero positivo
Propósito: ancho del canvas

`height`

Tipo: number
Obligatorio: sí
Restricción: entero positivo
Propósito: alto del canvas

`fps`

Tipo: number
Obligatorio: sí
Restricción: entero positivo
Propósito: tasa de fotogramas

`background`

Tipo: string | "transparent" | Gradient
Obligatorio: no
Valor por defecto: "#000000"
Propósito: fondo global

Forma de Gradient:

interface Gradient {
  type: "linear" | "radial" | "conic";
  angle?: number;
  stops: Array<{
    offset: number;
    color: string;
  }>;
}

3. `assets`

interface Assets {
  fonts?: FontAsset[];
  images?: ImageAsset[];
  videos?: VideoAsset[];
  audios?: AudioAsset[];
  subtitles?: SubtitleAsset[];
}

`fonts`

interface FontAsset {
  id: string;
  src: string;
  family: string;
}

Estado actual en runtime:

Puede aparecer en el JSON
El runtime no descarga ni registra fuentes automáticamente
No lo trates como un sistema completo de carga de fuentes

`images`

interface ImageAsset {
  id: string;
  src: string;
}

`videos`

interface VideoAsset {
  id: string;
  src: string;
}

`audios`

interface AudioAsset {
  id: string;
  src: string;
}

`subtitles`

interface SubtitleAsset {
  id: string;
  words: SubtitleWord[];
}

Uso de `$ref`

Pools de recursos compatibles con $ref:

images
videos
audios
subtitles

Ejemplo:

{
  "src": { "$ref": "video-hero" }
}

{
  "words": { "$ref": "subtitle-main" }
}

4. `tracks`

interface Track {
  id?: string;
  clips: Clip[];
}

`id`

Tipo: string
Obligatorio: no
Propósito: identificador del track

`clips`

Tipo: Clip[]
Obligatorio: sí
Restricción: al menos un clip

5. Forma compartida de `Clip`

interface BaseClip {
  id?: string;
  type: ClipType;
  start: number;
  duration: number;
  transform?: Transform;
  zIndex?: number;
  opacity?: number;
  style?: Style;
  animations?: Animation[];
  keyframes?: Keyframe[];
  transition?: Transition;
}

Campos base compartidos:

`id`

Tipo: string
Obligatorio: no
Propósito: identificador del clip

`type`

Tipo: ClipType
Obligatorio: sí

Compatibles actualmente:

video
image
text
rect
circle
polygon
audio
subtitle
layout
template

`start`

Tipo: number
Obligatorio: sí
Unidad: segundos
Propósito: hora de inicio del clip

`duration`

Tipo: number
Obligatorio: sí
Unidad: segundos
Propósito: duración del clip

`transform`

Tipo: Transform
Obligatorio: no

`zIndex`

Tipo: number
Obligatorio: no
Valor por defecto: 0

`opacity`

Tipo: number
Obligatorio: no
Valor por defecto: 1
Propósito: atajo de opacidad para elementos visibles
Regla de compatibilidad: style.opacity tiene prioridad sobre opacity en el nivel superior

`style`

Tipo: Style
Obligatorio: no

`animations`

Tipo: Animation[]
Obligatorio: no

`keyframes`

Tipo: Keyframe[]
Obligatorio: no

`transition`

Tipo: Transition
Obligatorio: no

6. Reglas de coordenadas y porcentajes

Las coordenadas porcentuales se basan en el sistema de coordenadas centrado de Revideo, no en un origen superior izquierdo estilo DOM.

Ejemplos:

x: "50%" significa centrado horizontalmente
y: "50%" significa centrado verticalmente
x: "0%" significa totalmente a la izquierda
x: "100%" significa totalmente a la derecha
y: "0%" significa arriba
y: "100%" significa abajo

7. JSON mínimo válido

{
  "meta": {
    "version": "2.0.0",
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "background": "#000000"
  },
  "tracks": [
    {
      "clips": [
        {
          "type": "text",
          "start": 0,
          "duration": 3,
          "text": "Hello, world",
          "transform": {
            "x": "50%",
            "y": "50%"
          },
          "style": {
            "fontSize": 72,
            "fill": "#ffffff",
            "textAlign": "center"
          }
        }
      ]
    }
  ]
}

8. Nota para integraciones públicas

Para integraciones externas, usa el flujo documentado en API y uso:

Envía tu esquema mediante POST /api/preview
Envía el JSON completo del esquema como cuerpo de la solicitud
La ausencia de meta o tracks en el nivel superior debe seguir tratándose como entrada no válida
Un nombre de campo incorrecto dentro de un clip no siempre fallará en el momento de la solicitud
Algunos errores solo se harán visibles durante la vista previa, la reproducción o el renderizado

On this page