Video Generation Layer Types

JsonCut supports multiple layer types specifically designed for video content. Each layer type serves different purposes in creating engaging videos. Layers are rendered in the order they appear in your configuration, from bottom to top within each clip.

Video vs Image Layers

Video layer types have different properties and behaviors than image generation layers. Some layer types are unique to video processing, while others work differently than their image counterparts.

Video Layers

Display video files with advanced control over timing, scaling, and effects including Ken Burns zoom effects.

{
  "type": "video", 
  "config": {
    "width": 1400,
    "height": 720,
    "clips": [
      {
        "duration": 8,
        "layers": [
          {
            "type": "video",
            "path": "/video/2025-09-12/cmejszvz00000t5afm8qcr6bq/e0dd43e2-a779-48c1-b39f-fff31ebe328c.mp4",
            "resizeMode": "cover",
            "cutFrom": 2,
            "cutTo": 10,
          }
        ]
      },
      {
        "duration": 5,
        "layers": [
          {
            "type": "video",
            "path": "/video/2025-09-12/cmejszvz00000t5afm8qcr6bq/79de71b0-60f7-48c2-9a9d-6b73d35e3df7.mp4", 
            "resizeMode": "contain-blur",
            "cutFrom": 0,
            "cutTo": 5
          }
        ]
      }
    ]
  }
}

Properties

Property	Type	Required	Description
`path`	string	✅	Path to uploaded video file
`resizeMode`	string	❌	How to fit video: `contain`, `contain-blur`, `cover`, `stretch`
`cutFrom`	number	❌	Start time in source video (seconds)
`cutTo`	number	❌	End time in source video (seconds)
`width`	number	❌	Video width (conflicts with resizeMode)
`height`	number	❌	Video height (conflicts with resizeMode)
`mixVolume`	number	❌	Relative volume when mixing this video's audio track (0-1 , default: 1)

Video Clip Duration

For video layers, if parent clip.duration is specified, the video will be slowed/sped-up to match clip.duration. If cutFrom/cutTo is set, the resulting segment (cutTo-cutFrom) will be slowed/sped-up to fit clip.duration. If the layer has audio, it will be kept (and mixed with other audio layers if present.)

Resize Modes (ResizeMode)

contain - Video fits within frame with letterboxing (preserves aspect ratio)
contain-blur - Like contain, but fills letterbox with blurred background (default)
cover - Video fills frame completely, may crop content (preserves aspect ratio)
stretch - Video stretches to fill frame exactly (may distort aspect ratio)

Resize Mode Conflict

You cannot use both resizeMode and explicit width/height properties together. Choose either automatic resize mode OR manual dimensions.

Image Layers

Display static images throughout clip duration with positioning options and Ken Burns effects.

{
  "type": "video",
  "config": {
    "width": 720,
    "height": 1280,
    "clips": [
      {
        "duration": 3,
        "layers": [
          {
            "type": "image",
            "path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/f5c45bc9-20a5-43de-a2ef-5f09f858184f.jpg",
            "resizeMode": "cover",
            "zoomDirection": null
          }
        ]
      },
      {
        "duration": 3,
        "layers": [
          {
            "type": "image",
            "path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/d6571cc7-c111-4921-af01-4aeeb9533a74.png",
            "resizeMode": "contain",
            "zoomDirection": null
          }
        ]
      },
      {
        "duration": 3,
        "layers": [
          {
            "type": "image",
            "path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/a79951a6-8e16-42b3-99a2-9b71753ea560.jpg",
            "resizeMode": "stretch",
            "zoomDirection": "in",
            "zoomAmount": 0.15
          }
        ]
      }
    ]
  }
}

Properties

Property	Type	Required	Description
`path`	string	✅	Path to uploaded image file
`resizeMode`	string	❌	How to fit image: `contain`, `cover`, `stretch`
`position`	string/object	❌	Position within frame
`width`, `height`	number	❌	Relative size (0-1) or absolute pixels
`zoomDirection`	string	❌	Ken Burns effect: `in`, `out`, `left`, `right`, `null` (default: in)
`zoomAmount`	number	❌	Zoom intensity (default: 0.1)

Ken Burns on Static Images

Apply cinematic movement to still images. Here's a complete example demonstrating different Ken Burns effects with title-background layers explaining each effect:

{
   "type":"video",
   "config":{
      "width":1920,
      "height":1080,
      "fps":30,
      "clips":[
         {
            "layers":[
               {
                  "text":"Zoom In",
                  "type":"title-background",
                  "textColor":"#ffffff"
               }
            ],
            "duration":3,
            "transition":{
               "name":"fade",
               "duration":1
            }
         },
         {
            "layers":[
               {
                  "path":"/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/f5c45bc9-20a5-43de-a2ef-5f09f858184f.jpg",
                  "type":"image",
                  "resizeMode":"cover",
                  "zoomAmount":0.2,
                  "zoomDirection":"in"
               }
            ],
            "duration":5,
            "transition":{
               "name":"fade",
               "duration":1
            }
         },
         {
            "layers":[
               {
                  "text":"Zoom Out",
                  "type":"title-background",
                  "textColor":"#ffffff"
               }
            ],
            "duration":3,
            "transition":{
               "name":"fade",
               "duration":1
            }
         },
         {
            "layers":[
               {
                  "path":"/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/f5c45bc9-20a5-43de-a2ef-5f09f858184f.jpg",
                  "type":"image",
                  "resizeMode":"cover",
                  "zoomAmount":0.15,
                  "zoomDirection":"out"
               }
            ],
            "duration":5,
            "transition":{
               "name":"fade",
               "duration":1
            }
         },
         {
            "layers":[
               {
                  "text":"Pan left",
                  "type":"title-background",
                  "textColor":"#ffffff"
               }
            ],
            "duration":3,
            "transition":{
               "name":"fade",
               "duration":1
            }
         },
         {
            "layers":[
               {
                  "path":"/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/f5c45bc9-20a5-43de-a2ef-5f09f858184f.jpg",
                  "type":"image",
                  "resizeMode":"cover",
                  "zoomAmount":0.18,
                  "zoomDirection":"left"
               }
            ],
            "duration":5
         }
      ]
   }
}

This example demonstrates:

Zoom In: Creates a dramatic zoom effect into the image
Zoom Out: Pulls back to reveal more of the image
Pan Left: Moves left while zooming for dynamic motion

Image Overlay Layers

Position images as overlays over other content with precise control.

{
  "type": "video",
  "config": {
    "width": 1280,
    "height": 720,
    "clips": [
      {
        "duration": 5,
        "layers": [
          {
            "type": "video",
            "path": "/video/2025-09-12/cmejszvz00000t5afm8qcr6bq/70bc99e3-fd1a-449a-9400-31dbaa34a264.mp4",
            "resizeMode": "cover"
          },
          {
            "type": "image-overlay",
            "path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/052cd380-f78c-45ca-8307-f0d8673d5f11.png",
            "position": "center",
            "width": 0.5,
            "zoomDirection": "in",
            "zoomAmount": "0.3"
          },
          {
            "type": "image-overlay",
            "path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/562dc2e2-ebd8-4e6d-9877-3bcedb7e6835.png",
            "position": "top",
            "width": 0.3,
            "height": 0.1
          }
        ]
      }
    ]
  }
}

Properties

Property	Type	Required	Description
`path`	string	✅	Path to uploaded image file
`position`	string/object	❌	Position within frame
`width`	number	❌	Relative width (0-1) or absolute pixels
`height`	number	❌	Relative height (0-1) or absolute pixels
`start`	number	❌	Start time in seconds (when overlay appears)
`stop`	number	❌	Stop time in seconds (when overlay disappears)
`zoomDirection`	string	❌	Ken Burns effect: `in`, `out`, `left`, `right`, `null`
`zoomAmount`	number	❌	Zoom intensity (default: 0.1)

Timing Control

Image overlays can appear and disappear at specific times within a clip:

{
  "type": "image-overlay",
  "path": "/image/2024-01-15/user123/emoji.png",
  "position": "center",
  "width": 0.2,
  "start": 0.5,  // Appears at 0.5 seconds
  "stop": 2.0    // Disappears at 2.0 seconds
}

Text Layers

Title Layers

Large headline text with custom fonts and positioning.

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 3,
        "layers": [
          {
            "type": "radial-gradient",
            "colors": ["#667eea", "#764ba2"]
          },
          {
            "type": "title",
            "text": "Welcome to JsonCut",
            "fontSize": 64,
            "textColor": "#ffffff",
            "fontPath": "/font/2025-09-12/cmejszvz00000t5afm8qcr6bq/3cc3d2b5-d20d-4be9-9b5e-4128954ace64.ttf",
            "position": "center"
          }
        ]
      }
    ]
  }
}

Properties

Property	Type	Required	Description
`text`	string	✅	Title text to show, keep it short
`textColor`	string	❌	Text color (default: #ffffff)
`fontSize`	number	❌	Font size in pixels
`fontPath`	string	❌	Custom font file path
`position`	string/object	❌	Position within frame
`zoomDirection`	string	❌	Ken Burns effect: `in`, `out`, `left`, `right`, `null`
`zoomAmount`	number	❌	Zoom intensity (default: 0.1)

Subtitle Layers

Smaller text for captions, descriptions, and secondary information.

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 4,
        "layers": [
          {
            "type": "image",
            "path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/59a9ec4d-e6b4-4b7f-81fe-32adfa451f90.png",
            "resizeMode": "cover"
          },
          {
            "type": "subtitle",
            "text": "Create amazing videos with JSON",
            "textColor": "#ffffff",
            "fontPath": "/font/2025-09-12/cmejszvz00000t5afm8qcr6bq/55711891-2431-46e7-acd6-f1b2b9bc3228.ttf",
            "fontSize": 32
          }
        ]
      }
    ]
  }
}

Properties

Property	Type	Required	Description
`text`	string	✅	Title text to show, keep it short
`textColor`	string	❌	Text color (default: #ffffff)
`fontSize`	number	❌	Font size in pixels
`fontPath`	string	❌	Custom font file path

News Title Layers

Breaking news style titles with colored backgrounds.

{
  "type": "video",
  "config": {
  "width": 1280,
  "height": 720,
  "clips": [
    {
      "layers": [
        {
          "path": "/video/2025-09-12/cmejszvz00000t5afm8qcr6bq/7fa33354-9629-47d4-8f34-d5ade8a5e58b.mp4",
          "type": "video",
          "resizeMode": "cover"
        },
        {
          "text": "BREAKING NEWS",
          "type": "news-title",
          "fontPath": "/font/2025-09-12/cmejszvz00000t5afm8qcr6bq/de6b0a12-3512-4c4f-82fa-d65867990b30.ttf",
          "position": "bottom",
          "textColor": "#ffffff",
          "backgroundColor": "#d02a42"
        }
      ],
      "duration": 5
    }
  ]
}
}

Properties

Property	Type	Required	Description
`text`	string	✅	News title text content
`textColor`	string	❌	Text color (default: #ffffff)
`backgroundColor`	string	❌	Background color
`fontPath`	string	❌	Custom font file path
`position`	string/object	❌	Position within frame

Title Background Layers

Titles with full-screen background colors or gradients. The background covers the entire video frame, not just behind the text.

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 3,
        "layers": [
          {
            "type": "title-background",
            "text": "Welcome to JsonCut",
            "textColor": "#ffffff",
            "fontSize": 64,
            "position": "center",
            "background": {
              "type": "radial-gradient",
              "colors": ["#667eea", "#764ba2"]
            }
          }
        ]
      }
    ]
  }
}

Background Types

Title background layers support three background types. Here's a complete example showcasing all three:

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 3,
        "layers": [
          {
            "type": "title-background",
            "text": "Fill Color Background",
            "textColor": "#ffffff",
            "background": {
              "type": "fill-color",
              "color": "#05D9E8"
            }
          }
        ],
        "transition": {
          "name": "fade",
          "duration": 1
        }
      },
      {
        "duration": 3,
        "layers": [
          {
            "type": "title-background",
            "text": "Linear Gradient",
            "textColor": "#ffffff",
            "background": {
              "type": "linear-gradient",
              "colors": ["#ff6b6b", "#693FD1"],
              "direction": "diagonal"
            }
          }
        ],
        "transition": {
          "name": "fade",
          "duration": 1
        }
      },
      {
        "duration": 3,
        "layers": [
          {
            "type": "title-background",
            "text": "Radial Gradient",
            "textColor": "#ffffff",
            "background": {
              "type": "radial-gradient",
              "colors": ["#D1B43F", "#CC3FD1"]
            }
          }
        ]
      }
    ]
  }
}

Random Background

If the background object property is not explicitly specified, a random background type and colors will be automatically chosen for the title background layer.

Properties

Property	Type	Required	Description
`text`	string	✅	Title text content
`textColor`	string	❌	Text color (default: #ffffff)
`fontSize`	number	❌	Font size in pixels
`fontPath`	string	❌	Custom font file path
`position`	string/object	❌	Text position
`background`	object	❌	Background configuration
`background.type`	string	✅	Background type: `fill-color`, `linear-gradient`, `radial-gradient`
`background.color`	string	❌	Fill color (for fill-color type)
`background.colors`	array	❌	Gradient colors (for gradient types)
`background.direction`	string	❌	Gradient direction (for linear-gradient)

Full-Screen Background

Title background layers create a full-screen background that covers the entire video frame. Do not combine with other background layers (image, video, fill-color, gradients) as they will be hidden behind the title background.

Slide-in Text Layers

Animated text that slides into view with motion effects.

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 4,
        "layers": [
          {
            "type": "linear-gradient",
            "colors": ["#667eea", "#764ba2"],
            "direction": "horizontal"
          },
          {
            "type": "slide-in-text",
            "text": "Animated Introduction",
            "fontSize": 0.05,
            "textColor": "#ffffff",
            "position": "center"
          }
        ]
      }
    ]
  }
}

Relative Font Size

For slide-in text layers, fontSize is specified as a relative value between 0 and 1, where 1 represents the full video height. This allows the text to scale appropriately across different video resolutions.

Text Properties

Property	Type	Description
`text`	string	Text content to display
`fontSize`	number	Font size in pixels (relative 0-1 for slide-in-text)
`textColor`	string	Text color
`fontPath`	string	Path to custom font file
`position`	string/object	Text position
`backgroundColor`	string	Background color (some text types)

Background Layers

Background layers provide solid colors, gradients, and animated effects for your video clips. Here's a complete example showcasing all four background types:

{
  "type": "video",
  "config": {
    "defaults": {
      "duration": 3
    },
    "clips": [
      {

        "layers": [
          {
            "type": "fill-color",
            "color": "#007acc"
          },
          {
            "type": "title",
            "text": "Fill Color Background",
            "textColor": "#ffffff",
            "position": "center"
          }
        ],
        "transition": {
          "name": "fade",
          "duration": 1
        }
      },
      {
        "layers": [
          {
            "type": "linear-gradient",
            "colors": ["#ff6b6b", "#4ecdc4", "#45b7d1"],
            "direction": "vertical"
          },
          {
            "type": "title",
            "text": "Linear Gradient",
            "textColor": "#ffffff",
            "position": "center"
          }
        ],
        "transition": {
          "name": "fade",
          "duration": 1
        }
      },
      {
        "layers": [
          {
            "type": "radial-gradient",
            "colors": ["#667eea", "#764ba2"]
          },
          {
            "type": "title",
            "text": "Radial Gradient",
            "textColor": "#ffffff",
            "position": "center"
          }
        ],
        "transition": {
          "name": "fade",
          "duration": 1
        }
      },
      {
        "layers": [
          {
            "type": "rainbow-colors"
          },
          {
            "type": "title",
            "text": "Rainbow Effect",
            "textColor": "#ffffff",
            "position": "center"
          }
        ]
      }
    ]
  }
}

Background Types

Fill Color - Solid color backgrounds
Linear Gradient - Linear color transitions with direction control
Radial Gradient - Circular color gradients from center outward
Rainbow Colors - Animated rainbow gradient effects

Gradient Properties

Property	Type	Description
`colors`	array	Array of color values
`direction`	string	Direction for linear gradients: `horizontal`, `vertical`, `diagonal`

Gradient Transparency

Gradient layers support transparency in color values. Use 8-digit hex colors (e.g., #ffffffff for opaque white, #ffffff00 for transparent white) or rgba values to create transparent gradients that blend with underlying layers.

Audio Layers

Audio tracks tied to specific clips. Audio layers will be mixed together and can be slowed/sped-up to fit clip duration.

{
  "type": "video",
  "config": {
    "keepSourceAudio": true,
    "clips": [
      {
        "duration": 5,
        "layers": [
          {
            "type": "image",
            "path": "/image/2025-09-14/cmejszvz00000t5afm8qcr6bq/ee290ffe-8040-44de-ba63-11e52f9b6ab1.jpg",
            "resizeMode": "cover"
          },
          {
            "type": "audio",
            "path": "/audio/2025-09-14/cmejszvz00000t5afm8qcr6bq/5cf55beb-e8d6-40d8-92be-e8c435bb7958.mp3",
            "cutFrom": 2,
            "cutTo": 7,
            "mixVolume": 0.8
          }
        ]
      }
    ]
  }
}

Audio Layer Requirements

Audio layers require keepSourceAudio: true in the video config to function properly. Without this flag, audio layers will be ignored.

Audio Speed Adjustment

If cutFrom/cutTo is set, the resulting segment will be slowed/sped-up to fit clip.duration. Speed adjustment is limited to values between 0.5x and 100x.

Detached Audio Layers

Audio tracks that start relative to each clip's beginning, rather than the global video timeline. This makes it easier to synchronize audio with specific clips without calculating absolute start times across the entire video.

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 4,
        "layers": [
          {
            "type": "fill-color",
            "color": "#2c3e50"
          },
          {
            "type": "title",
            "text": "Clip 1",
            "textColor": "#ffffff",
            "position": "center"
          },
          {
            "type": "detached-audio",
            "path": "/audio/2025-09-14/cmejszvz00000t5afm8qcr6bq/a21ecdd2-af07-4abd-ad35-04337add70bd.wav",
            "start": 1,
            "mixVolume": 0.9,
            "cutFrom": 0
          }
        ],
        "transition": {
          "name": "fade",
          "duration": 1
        }
      },
      {
        "duration": 3,
        "layers": [
          {
            "type": "fill-color",
            "color": "#e74c3c"
          },
          {
            "type": "title",
            "text": "Clip 2",
            "textColor": "#ffffff",
            "position": "center"
          },
          {
            "type": "detached-audio",
            "path": "/audio/2025-09-14/cmejszvz00000t5afm8qcr6bq/5cf55beb-e8d6-40d8-92be-e8c435bb7958.mp3",
            "start": 0.5,
            "mixVolume": 0.6
          }
        ]
      }
    ]
  }
}

This example demonstrates:

Clip 1: Voiceover starts 1 second after clip 1 begins, continues playing through the rest of the video
Clip 2: Music sting starts 0.5 seconds after clip 2 begins, plays until the end of the video
Relative timing: Each detached audio start time is relative to its own clip's start time, not the global video timeline

Audio Properties

Property	Type	Required	Default	Description
`path`	string	✅	-	Path to uploaded audio file
`mixVolume`	number	❌	`1`	Relative volume when mixing (0-1)
`cutFrom`	number	❌	`0`	Start time in audio file (seconds)
`cutTo`	number	❌	`clip.duration`	End time in audio file (seconds)
`start`	number	❌	`0`	Start time in video timeline (detached audio only)

Special Layers

Pause Layers

Create black screen pauses or breaks in content.

{
  "type": "video",
  "config": {
    "clips": [
      {
        "duration": 1,
        "layers": [
          {
            "type": "pause"
          }
        ]
      }
    ]
  }
}

Position System

Video layers support flexible positioning:

String Positions

center, top, bottom
top-left, top-right, center-left, center-right
bottom-left, bottom-right

Object Positions

{
  "position": {
    "x": 0.8,
    "y": 0.1,
    "originX": "right",
    "originY": "top"
  }
}

x, y: Relative coordinates (0-1)
originX: left, center, right
originY: top, center, bottom

Best Practices

Performance Optimization

Layer efficiency - Use appropriate layer types for content
Video compression - Optimize input video files
Audio quality - Balance quality vs file size
Layer count - Limit layers per clip for better performance

Design Guidelines

Visual hierarchy - Order layers by importance
Consistent timing - Use appropriate clip durations
Readable text - Ensure text contrast against backgrounds
Audio balance - Mix audio levels appropriately

Next Steps

Clips & Transitions - Learn about clip structure and transitions
Audio & Sound - Master audio integration and mixing
Examples - See layer types in complete video examples

Video Layers​

Properties​

Resize Modes (ResizeMode)​

Image Layers​

Properties​

Ken Burns on Static Images​

Image Overlay Layers​

Properties​

Timing Control​

Text Layers​

Title Layers​

Properties​

Subtitle Layers​

Properties​

News Title Layers​

Properties​

Title Background Layers​

Background Types​

Properties​

Slide-in Text Layers​

Text Properties​

Background Layers​

Background Types​

Gradient Properties​

Audio Layers​

Audio Layers​

Detached Audio Layers​

Audio Properties​

Special Layers​

Pause Layers​

Position System​

String Positions​

Object Positions​

Best Practices​

Performance Optimization​

Design Guidelines​

Next Steps​

Video Layers

Properties

Resize Modes (ResizeMode)

Image Layers

Properties

Ken Burns on Static Images

Image Overlay Layers

Properties

Timing Control

Text Layers

Title Layers

Properties

Subtitle Layers

Properties

News Title Layers

Properties

Title Background Layers

Background Types

Properties

Slide-in Text Layers

Text Properties

Background Layers

Background Types

Gradient Properties

Audio Layers

Audio Layers

Detached Audio Layers

Audio Properties

Special Layers

Pause Layers

Position System

String Positions

Object Positions

Best Practices

Performance Optimization

Design Guidelines

Next Steps