Editor - UGC Inc API Documentation

Overview

The Editor structure defines a complete video or image composition with multiple layers, channels, and segments. It provides frame-accurate control over timing, positioning, effects, and layering.

Video vs Image Output:

Video Rendering: Supports all segment types (video, audio, text, image, nested editors)
Image Rendering: Only supports text and image segments (renders a static frame at time 0)

Editor Configuration

Root Properties

Property	Type	Required	Description
`width`	`number`	✅	Canvas width in pixels (e.g., `1080` for TikTok/Instagram)
`height`	`number`	✅	Canvas height in pixels (e.g., `1920` for vertical video)
`fps`	`number`	✅	Frames per second (typically `30` or `60`)
`duration`	`number`	✅	Total duration in milliseconds (can be auto-calculated from segments)
`channels`	`Channel[]`	✅	Array of channels, each containing segments

Channel Structure

Channels are independent layers that can contain multiple segments. All segments within a channel play sequentially, while segments across different channels play simultaneously.

Property	Type	Required	Description
`id`	`string`	✅	Unique channel identifier (e.g., `"background"`, `"text-layer"`)
`segments`	`Segment[]`	✅	Array of segments in this channel

Segment Types

Base Segment Properties

All segment types inherit these properties:

Property	Type	Required	Description
`id`	`string`	✅	Unique segment identifier
`type`	`string`	✅	Segment type: `video`, `image`, `text`, `audio`, or `editor`
`source`	`string`	✅	Public URL to media file (empty `""` for text segments)
`order`	`number`	✅	Sequence order within channel (0-based)
`offset`	`TimeValue`	✅	Delay after previous segment starts
`startTrim`	`number`	⚪	Trim from start in milliseconds (default: `0`)
`endTrim`	`number`	⚪	Trim from end in milliseconds (default: `0`)
`duration`	`TimeValue`	⚪	Override segment duration (auto-calculated if omitted)

Visual Segment Properties

Video, image, text, and editor segments include these positioning properties:

Property	Type	Default	Description
`xOffset`	`number`	`0`	Horizontal position from left edge in pixels
`yOffset`	`number`	`0`	Vertical position from top edge in pixels
`width`	`number`	Required	Width in pixels
`height`	`number`	Required	Height in pixels
`zIndex`	`number`	`0`	Stacking order (higher values appear on top)
`scale`	`number`	`1`	Scale multiplier (`1.0` = 100%, `2.0` = 200%)
`rotation`	`number`	`0`	Rotation in degrees (clockwise)
`opacity`	`number`	`100`	Opacity percentage (0 = transparent, 100 = opaque)

Video Segment

Displays video content with optional audio. Additional Properties:

Property	Type	Default	Description
`fit`	`'cover' \| 'contain' \| 'fill'`	`'cover'`	How the video fits in the bounds • `cover`: Fill entire area, crop overflow • `contain`: Fit entire video, may have letterboxing • `fill`: Stretch to fill, may distort
`speed`	`number`	`1`	Playback speed multiplier (`0.5` = half speed, `2.0` = double speed)
`volume`	`number`	`100`	Audio volume percentage (0 = muted, 100 = full volume)

Example:

{
  "id": "main-video",
  "type": "video",
  "source": "https://example.com/video.mp4",
  "order": 0,
  "offset": { "type": "absolute", "value": 0 },
  "startTrim": 1000,
  "endTrim": 500,
  "xOffset": 0,
  "yOffset": 0,
  "width": 1080,
  "height": 1920,
  "zIndex": 0,
  "scale": 1,
  "rotation": 0,
  "fit": "cover",
  "speed": 1,
  "opacity": 100,
  "volume": 50
}

Image Segment

Displays static images or animated GIFs. Additional Properties:

Property	Type	Default	Description
`fit`	`'cover' \| 'contain' \| 'fill'`	`'contain'`	How the image fits in the bounds
`loop`	`boolean`	`false`	Loop animated GIFs (only affects GIFs)

Example:

{
  "id": "logo",
  "type": "image",
  "source": "https://example.com/logo.png",
  "order": 0,
  "offset": { "type": "absolute", "value": 0 },
  "duration": { "type": "absolute", "value": 5000 },
  "xOffset": 90,
  "yOffset": 100,
  "width": 300,
  "height": 300,
  "zIndex": 5,
  "scale": 1,
  "rotation": 0,
  "fit": "contain",
  "opacity": 100
}

Text Segment

Rich text overlays with full typography and styling control. Typography Properties:

Property	Type	Default	Description
`text`	`string`	Required	The text content (supports emojis)
`fontType`	`'arial' \| 'tiktok' \| 'apple'`	`'tiktok'`	Font family
`fontSize`	`number`	`40`	Font size in pixels
`fontWeight`	`'normal' \| 'bold'`	`'normal'`	Font weight
`lineHeight`	`number`	`1.2`	Line height multiplier
`letterSpacing`	`number`	`0`	Letter spacing in pixels

Alignment Properties:

Property	Type	Default	Description
`alignment`	`'left' \| 'center' \| 'right' \| 'justify'`	`'left'`	Horizontal text alignment
`verticalAlign`	`'top' \| 'middle' \| 'bottom'`	`'top'`	Vertical alignment within bounds
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Text direction (left-to-right or right-to-left)
`padding`	`number`	`0`	Inner padding in pixels

Text Wrapping Properties:

Property	Type	Default	Description
`textWrap`	`'word' \| 'char' \| 'none'`	`'word'`	How text wraps to new lines
`wordBreak`	`'normal' \| 'break-all' \| 'break-word'`	`'normal'`	How words break across lines
`hyphenation`	`'none' \| 'auto'`	`'none'`	Automatic hyphenation
`maxLines`	`number`	`0`	Maximum lines (0 = unlimited)
`textOverflow`	`'clip' \| 'ellipsis'`	`'clip'`	How overflow is handled
`ellipsis`	`string`	`'...'`	Ellipsis string for overflow

Color Properties:

Property	Type	Default	Description
`color`	`string`	`'#FFFFFF'`	Text color in hex format (e.g., `#FF0000` for red)
`backgroundColor`	`string`	`'transparent'`	Background color with optional alpha (e.g., `#00000080` for 50% black)
`strokeColor`	`string`	`undefined`	Text outline color (e.g., `#000000` for black outline)
`strokeWidth`	`number`	`0`	Outline width in pixels

Example:

{
  "id": "title-text",
  "type": "text",
  "source": "",
  "order": 0,
  "offset": { "type": "absolute", "value": 500 },
  "duration": { "type": "absolute", "value": 4000 },
  "xOffset": 90,
  "yOffset": 800,
  "width": 900,
  "height": 320,
  "zIndex": 10,
  "text": "Hello World! 🎉",
  "alignment": "center",
  "verticalAlign": "middle",
  "direction": "ltr",
  "padding": 20,
  "fontType": "tiktok",
  "fontSize": 80,
  "fontWeight": "bold",
  "lineHeight": 1.2,
  "letterSpacing": 0,
  "textWrap": "word",
  "wordBreak": "break-word",
  "hyphenation": "none",
  "maxLines": 0,
  "textOverflow": "clip",
  "ellipsis": "...",
  "color": "#FFFFFF",
  "backgroundColor": "#00000080",
  "strokeColor": "#000000",
  "strokeWidth": 4,
  "scale": 1,
  "rotation": 0,
  "opacity": 100
}

Audio Segment

Background audio or music tracks. Audio segments don’t have visual properties. Properties:

Property	Type	Default	Description
(base properties)			All base segment properties apply
`volume`	`number`	`100`	Audio volume percentage (0 = muted, 100 = full)

Example:

{
  "id": "background-music",
  "type": "audio",
  "source": "https://example.com/music.mp3",
  "order": 0,
  "offset": { "type": "absolute", "value": 0 },
  "startTrim": 0,
  "endTrim": 0,
  "duration": { "type": "absolute", "value": 5000 },
  "volume": 80
}

Editor Segment (Nested Composition)

Nest entire editor configurations within segments for complex compositions. Additional Properties:

Property	Type	Description
`editor`	`Editor`	Complete nested editor configuration
(all visual properties)		Same as video segments

Example:

{
  "id": "nested-composition",
  "type": "editor",
  "source": "",
  "order": 0,
  "offset": { "type": "absolute", "value": 1000 },
  "editor": {
    "width": 540,
    "height": 960,
    "fps": 30,
    "duration": 3000,
    "channels": [/* nested channels */]
  },
  "xOffset": 270,
  "yOffset": 480,
  "width": 540,
  "height": 960,
  "zIndex": 5,
  "fit": "contain",
  "opacity": 100,
  "speed": 1,
  "volume": 100
}

Time Value Format

Time values can be specified as absolute (milliseconds) or relative (percentage):

// Absolute - exact time in milliseconds
{
  "type": "absolute",
  "value": 500  // 500ms
}

// Relative - percentage of total duration
{
  "type": "relative",
  "value": 0.25  // 25% of total duration
}

Usage Examples:

Offset: { type: "absolute", value: 1000 } = start 1 second after previous segment
Duration: { type: "relative", value: 0.5 } = last for 50% of total video duration

Timing & Duration Calculation

How Segment Timing Works

Sequential within channels: Segments in the same channel play one after another
Parallel across channels: Segments in different channels play simultaneously
Offset delays: Each segment can delay relative to the previous one

Duration Calculation Rules

// Segment duration is calculated as:
const segmentDuration = 
  mediaDuration - startTrim - endTrim + (duration override if specified)

// Segment start time is calculated as:
const startTime = 
  previousSegmentStartTime + offset.value

Example Timeline

{
  "channels": [
    {
      "id": "channel1",
      "segments": [
        {
          "id": "seg1",
          "offset": { "type": "absolute", "value": 0 },
          // Starts at 0ms
        },
        {
          "id": "seg2",
          "offset": { "type": "absolute", "value": 1000 },
          // Starts at 1000ms (1 second after seg1 starts)
        },
        {
          "id": "seg3",
          "offset": { "type": "absolute", "value": 500 },
          // Starts at 1500ms (500ms after seg2 starts)
        }
      ]
    }
  ]
}

Positioning & Transform Properties

Position

Property	Description	Example
`xOffset`	Distance from left edge in pixels	`540` centers a 1080px-wide element in a 1920px canvas
`yOffset`	Distance from top edge in pixels	`0` places at the top

Size

Property	Description	Notes
`width`	Element width in pixels	Combined with `fit` mode for media
`height`	Element height in pixels	Combined with `fit` mode for media

Transforms

Property	Range	Description
`scale`	`0.1` - `10`	Size multiplier (`1` = original size, `2` = 200%, `0.5` = 50%)
`rotation`	`0` - `360`	Rotation in degrees (clockwise)
`opacity`	`0` - `100`	Transparency (`0` = invisible, `100` = fully opaque)
`zIndex`	any integer	Layer order (higher numbers appear on top)

Fit Modes

Controls how media (video/image) fits within specified width/height bounds.

`cover` (Default for video)

Behavior: Fills entire area, crops overflow
Use case: Full-screen backgrounds
Aspect ratio: Maintained
Example: 16:9 video in 9:16 canvas → sides cropped

`contain` (Default for image)

Behavior: Fits entire media, may have letterboxing
Use case: Logos, overlays that must be fully visible
Aspect ratio: Maintained
Example: Square image in rectangular area → bars on sides or top/bottom

`fill`

Behavior: Stretches to fill entire area
Use case: Rare - usually avoid as it distorts
Aspect ratio: Not maintained
Example: Any aspect ratio → stretched to match bounds exactly

Text Styling Reference

Font Options

`fontType`	Description
`'tiktok'`	TikTok Sans font family (default, recommended)
`'apple'`	SF Pro font (Apple system font)
`'arial'`	Arial fallback font

Font Weight Options

`fontWeight`	Rendering
`'normal'`	Regular weight
`'bold'`	Bold weight

Text Alignment

`alignment`	Effect
`'left'`	Align to left edge
`'center'`	Center horizontally
`'right'`	Align to right edge
`'justify'`	Justify text (stretch to fill width)

`verticalAlign`	Effect
`'top'`	Align to top edge
`'middle'`	Center vertically
`'bottom'`	Align to bottom edge

Text Wrapping Modes

`textWrap`	Behavior
`'word'`	Break at word boundaries (recommended)
`'char'`	Break at any character
`'none'`	No wrapping, text may overflow

`wordBreak`	Behavior
`'normal'`	Break at normal word boundaries
`'break-all'`	Break between any two characters
`'break-word'`	Break long words if necessary

Color Format

All colors use hex format with optional alpha channel:

"#RRGGBB"      // RGB (e.g., "#FF0000" = red)
"#RRGGBBAA"    // RGBA (e.g., "#FF000080" = 50% transparent red)

Examples:

#FFFFFF - White
#000000 - Black
#FF0000 - Red
#00000080 - 50% transparent black
#FFFFFF00 - Fully transparent white

Complete Example: Multi-Layer Video

{
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "duration": 10000,
  "channels": [
    {
      "id": "background",
      "segments": [
        {
          "id": "bg-video",
          "type": "video",
          "source": "https://example.com/background.mp4",
          "order": 0,
          "offset": { "type": "absolute", "value": 0 },
          "startTrim": 0,
          "endTrim": 0,
          "xOffset": 0,
          "yOffset": 0,
          "width": 1080,
          "height": 1920,
          "zIndex": 0,
          "scale": 1,
          "rotation": 0,
          "fit": "cover",
          "speed": 1,
          "opacity": 100,
          "volume": 30
        }
      ]
    },
    {
      "id": "overlay-images",
      "segments": [
        {
          "id": "logo",
          "type": "image",
          "source": "https://example.com/logo.png",
          "order": 0,
          "offset": { "type": "absolute", "value": 0 },
          "duration": { "type": "absolute", "value": 10000 },
          "xOffset": 50,
          "yOffset": 50,
          "width": 200,
          "height": 200,
          "zIndex": 5,
          "fit": "contain",
          "opacity": 90
        }
      ]
    },
    {
      "id": "text-overlays",
      "segments": [
        {
          "id": "intro-text",
          "type": "text",
          "source": "",
          "order": 0,
          "offset": { "type": "absolute", "value": 500 },
          "duration": { "type": "absolute", "value": 3000 },
          "xOffset": 90,
          "yOffset": 800,
          "width": 900,
          "height": 320,
          "zIndex": 10,
          "text": "Welcome! 👋",
          "alignment": "center",
          "verticalAlign": "middle",
          "fontType": "tiktok",
          "fontSize": 80,
          "fontWeight": "bold",
          "color": "#FFFFFF",
          "backgroundColor": "#00000080",
          "strokeColor": "#000000",
          "strokeWidth": 4,
          "padding": 20,
          "opacity": 100
        },
        {
          "id": "cta-text",
          "type": "text",
          "source": "",
          "order": 1,
          "offset": { "type": "absolute", "value": 4000 },
          "duration": { "type": "absolute", "value": 2500 },
          "xOffset": 90,
          "yOffset": 1400,
          "width": 900,
          "height": 200,
          "zIndex": 10,
          "text": "Follow for more! 🚀",
          "alignment": "center",
          "verticalAlign": "middle",
          "fontType": "tiktok",
          "fontSize": 60,
          "fontWeight": "bold",
          "color": "#FFD700",
          "strokeColor": "#000000",
          "strokeWidth": 3,
          "opacity": 100
        }
      ]
    },
    {
      "id": "audio-layer",
      "segments": [
        {
          "id": "background-music",
          "type": "audio",
          "source": "https://example.com/music.mp3",
          "order": 0,
          "offset": { "type": "absolute", "value": 0 },
          "duration": { "type": "absolute", "value": 10000 },
          "volume": 50
        }
      ]
    }
  ]
}

Complete Example: Static Image

{
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "duration": 1000,
  "channels": [
    {
      "id": "background",
      "segments": [
        {
          "id": "bg-image",
          "type": "image",
          "source": "https://example.com/background.jpg",
          "order": 0,
          "offset": { "type": "absolute", "value": 0 },
          "xOffset": 0,
          "yOffset": 0,
          "width": 1080,
          "height": 1920,
          "zIndex": 0,
          "fit": "cover"
        }
      ]
    },
    {
      "id": "text-layer",
      "segments": [
        {
          "id": "title",
          "type": "text",
          "source": "",
          "order": 0,
          "offset": { "type": "absolute", "value": 0 },
          "xOffset": 90,
          "yOffset": 800,
          "width": 900,
          "height": 320,
          "zIndex": 10,
          "text": "Thumbnail Title",
          "alignment": "center",
          "verticalAlign": "middle",
          "fontType": "tiktok",
          "fontSize": 100,
          "fontWeight": "bold",
          "color": "#FFFFFF",
          "strokeColor": "#000000",
          "strokeWidth": 5
        }
      ]
    }
  ]
}

Best Practices

Layering

Use zIndex to control stacking order
Background elements: zIndex: 0
Mid-layer elements: zIndex: 5
Text/overlays: zIndex: 10+
Keep zIndex values spaced for easy insertion

Performance

Limit segments: < 50 per composition
Optimize source media: compress before upload
Use appropriate resolutions:
- TikTok/Instagram: 1080x1920 (9:16)
- YouTube Shorts: 1080x1920 (9:16)
- Square: 1080x1080 (1:1)

Timing

Use offset for staggered animations
Combine absolute and relative times for flexibility
Test edge cases (segment boundaries, overlaps)

Text Rendering

Readability: Use high contrast (white text on dark bg or vice versa)
Stroke: Add strokeWidth: 3-5 for text on video backgrounds
Font size: Minimum 40px for mobile readability
Line count: Keep under 3 lines for best engagement
Emojis: Fully supported, render correctly

Color Selection

Text on video: White with black stroke (color: "#FFFFFF", strokeColor: "#000000")
Backgrounds: Use semi-transparent (#00000080 for 50% black)
Highlights: Brand colors with full opacity
Test: Verify colors on different screens/backgrounds

Media Sources

URLs must be publicly accessible: No auth required
Supported formats:
- Video: MP4, MOV, WebM
- Image: PNG, JPEG, GIF, WebP
- Audio: MP3, WAV, OGG
HTTPS required: All source URLs must use HTTPS
CORS: Ensure proper CORS headers on your media server

Common Patterns

Full-Screen Video Background

{
  "xOffset": 0,
  "yOffset": 0,
  "width": 1080,
  "height": 1920,
  "fit": "cover",
  "zIndex": 0
}

Centered Logo Overlay

{
  "xOffset": 440,
  "yOffset": 860,
  "width": 200,
  "height": 200,
  "fit": "contain",
  "zIndex": 5
}

Bottom-Third Text Banner

{
  "xOffset": 90,
  "yOffset": 1400,
  "width": 900,
  "height": 200,
  "alignment": "center",
  "verticalAlign": "middle",
  "zIndex": 10
}

Fade In Effect (Manual)

// Show multiple text segments with increasing opacity
[
  { "opacity": 0, "duration": 100 },
  { "opacity": 25, "duration": 100 },
  { "opacity": 50, "duration": 100 },
  { "opacity": 75, "duration": 100 },
  { "opacity": 100, "duration": 3000 }
]

Troubleshooting

Text Not Appearing

Check zIndex - must be higher than background elements
Verify opacity is > 0
Ensure color contrasts with background
Check timing - verify segment is active during playback

Media Not Loading

Verify URL is publicly accessible (test in browser)
Check CORS headers on media server
Ensure HTTPS (not HTTP)
Verify file format is supported

Unexpected Timing

Review offset values - they’re relative to previous segment
Check startTrim and endTrim values
Verify duration overrides if specified
Remember: segments in same channel are sequential, different channels are parallel

Quality Issues

Use higher resolution source media
Avoid over-scaling (scale > 2.0)
Use fit: 'contain' instead of fill to avoid distortion
Ensure FPS matches source media (typically 30fps)

​Overview

​Editor Configuration

​Root Properties

​Channel Structure

​Segment Types

​Base Segment Properties

​Visual Segment Properties

​Video Segment

​Image Segment

​Text Segment

​Audio Segment

​Editor Segment (Nested Composition)

​Time Value Format

​Timing & Duration Calculation

​How Segment Timing Works

​Duration Calculation Rules

​Example Timeline

​Positioning & Transform Properties

​Position

​Size

​Transforms

​Fit Modes

​cover (Default for video)

​contain (Default for image)

​fill

​Text Styling Reference

​Font Options

​Font Weight Options

​Text Alignment

​Text Wrapping Modes

​Color Format

​Complete Example: Multi-Layer Video

​Complete Example: Static Image

​Best Practices

​Layering

​Performance

​Timing

​Text Rendering

​Color Selection

​Media Sources

​Common Patterns

​Full-Screen Video Background

​Centered Logo Overlay

​Bottom-Third Text Banner

​Fade In Effect (Manual)

​Troubleshooting

​Text Not Appearing

​Media Not Loading

​Unexpected Timing

​Quality Issues

Overview

Editor Configuration

Root Properties

Channel Structure

Segment Types

Base Segment Properties

Visual Segment Properties

Video Segment

Image Segment

Text Segment

Audio Segment

Editor Segment (Nested Composition)

Time Value Format

Timing & Duration Calculation

How Segment Timing Works

Duration Calculation Rules

Example Timeline

Positioning & Transform Properties

Position

Size

Transforms

Fit Modes

`cover` (Default for video)

`contain` (Default for image)

`fill`

Text Styling Reference

Font Options

Font Weight Options

Text Alignment

Text Wrapping Modes

Color Format

Complete Example: Multi-Layer Video

Complete Example: Static Image

Best Practices

Layering

Performance

Timing

Text Rendering

Color Selection

Media Sources

Common Patterns

Full-Screen Video Background

Centered Logo Overlay

Bottom-Third Text Banner

Fade In Effect (Manual)

Troubleshooting

Text Not Appearing

Media Not Loading

Unexpected Timing

Quality Issues