Synthome Docs
Operations

Layers

Composite media with positioning, overlays, and effects

layers()

Composite multiple media items with precise positioning, overlays, and chroma key effects.

import { compose, layers } from "@synthome/sdk";

const execution = await compose(
  layers([
    { media: "https://example.com/background.mp4" },
    { media: "https://example.com/logo.png", placement: "top-right" },
  ]),
).execute();

Basic Usage

Picture-in-Picture

layers([
  { media: "https://example.com/main.mp4" },
  { media: "https://example.com/webcam.mp4", placement: "pip" },
]);

Logo Overlay

layers([
  { media: "https://example.com/video.mp4" },
  { media: "https://example.com/logo.png", placement: "top-right" },
]);

Centered Overlay

layers([
  { media: "https://example.com/background.mp4" },
  { media: "https://example.com/title.png", placement: "center" },
]);

Placement Presets

Use simple presets for common layouts:

PresetDescription
"full"Full screen (default)
"center"Centered, original size
"pip"Small overlay in bottom-right
"picture-in-picture"Same as pip
layers([
  { media: "https://example.com/main.mp4" },
  { media: "https://example.com/overlay.mp4", placement: "pip" },
]);

Tailwind-Style Placement

Combine size and position using a familiar syntax:

Size Classes

ClassDescription
w-1/250% width
w-1/333% width
w-1/425% width
w-2/366% width
w-3/475% width
h-1/250% height
h-1/333% height
h-1/425% height

Position Classes

ClassDescription
top-leftTop-left corner
top-rightTop-right corner
bottom-leftBottom-left corner
bottom-rightBottom-right corner
centerCentered
topTop center
bottomBottom center
leftLeft center
rightRight center

Combined Examples

// 1/4 width overlay in bottom-right
layers([
  { media: "https://example.com/main.mp4" },
  { media: "https://example.com/pip.mp4", placement: "w-1/4 bottom-right" },
]);

// Half-width overlay centered
layers([
  { media: "https://example.com/background.mp4" },
  { media: "https://example.com/content.mp4", placement: "w-1/2 center" },
]);

// 1/3 height overlay at top
layers([
  { media: "https://example.com/main.mp4" },
  { media: "https://example.com/banner.png", placement: "h-1/3 top" },
]);

Custom Placement

For precise control, use custom placement objects:

layers([
  { media: "https://example.com/background.mp4" },
  {
    media: "https://example.com/overlay.png",
    placement: {
      width: "300", // Fixed width in pixels
      height: "200", // Fixed height in pixels
      position: {
        x: "50", // 50px from left
        y: "100", // 100px from top
      },
    },
  },
]);

Percentage-Based

placement: {
  width: "50%",
  height: "50%",
  position: {
    x: "25%",
    y: "25%",
  },
}

With Padding

placement: {
  width: "25%",
  position: { x: "100%", y: "100%" }, // Bottom-right
  padding: 20, // 20px padding from edge
}

Chroma Key (Green Screen)

Remove green backgrounds from overlays:

layers([
  { media: "https://example.com/background.mp4" },
  {
    media: "https://example.com/greenscreen-speaker.mp4",
    placement: "w-1/3 bottom-right",
    chromaKey: true,
  },
]);

Custom Chroma Key Settings

layers([
  { media: "https://example.com/background.mp4" },
  {
    media: "https://example.com/bluescreen.mp4",
    chromaKey: true,
    chromaKeyColor: "0000ff", // Blue instead of green
    similarity: 0.3, // Color match threshold
    blend: 0.1, // Edge blending
  },
]);

Duration Control

Main Layer

Mark a layer as the duration reference:

layers([
  { media: "https://example.com/background.mp4", main: true }, // Duration from this
  { media: "https://example.com/logo.png", placement: "top-right" },
]);

Explicit Duration

layers(
  [
    { media: "https://example.com/background.jpg" },
    { media: "https://example.com/overlay.png" },
  ],
  { duration: 10 }, // 10 second output
);

Output Dimensions

layers(
  [
    { media: "https://example.com/video.mp4" },
    { media: "https://example.com/overlay.png" },
  ],
  { width: 1920, height: 1080 },
);

Timeline Arrays

Create sequential content within a layer:

layers([
  { media: "https://example.com/background.mp4", main: true },
  [
    // Timeline: plays sequentially on this layer
    { media: "https://example.com/title1.png", duration: 3 },
    { media: "https://example.com/title2.png", duration: 3 },
    { media: "https://example.com/title3.png", duration: 3 },
  ],
]);

With Generated Content

Generated Background

layers([
  {
    media: generateVideo({
      model: videoModel("bytedance/seedance-1-pro", "replicate"),
      prompt: "Abstract flowing colors",
    }),
  },
  { media: "https://example.com/logo.png", placement: "center" },
]);

Generated Overlay

layers([
  { media: "https://example.com/video.mp4" },
  {
    media: generateImage({
      model: imageModel("google/nano-banana", "replicate"),
      prompt: "Watermark logo",
    }),
    placement: "w-1/6 bottom-right",
  },
]);

Multiple Generated Layers

layers([
  {
    media: generateVideo({
      model: videoModel("minimax/video-01", "replicate"),
      prompt: "Ocean waves",
    }),
    main: true,
  },
  {
    media: generateVideo({
      model: videoModel("bytedance/seedance-1-pro", "replicate"),
      prompt: "Person speaking on green screen",
    }),
    placement: "w-1/3 bottom-right",
    chromaKey: true,
  },
]);

API Reference

layers(items, options?)

ParameterTypeDescription
itemsArray<LayerItem | TimelineItem[]>Array of layers
optionsLayersOptionsOptional configuration

LayerItem

PropertyTypeDescription
mediastring | VideoOperation | ImageOperationMedia URL or generated content
placementPlacementPreset | CustomPlacementPosition and size
chromaKeybooleanEnable green screen removal
chromaKeyColorstringHex color to remove (default: green)
similaritynumberColor match threshold
blendnumberEdge blending amount
mainbooleanUse this layer's duration

LayersOptions

PropertyTypeDescription
durationnumberExplicit output duration
widthnumberOutput width in pixels
heightnumberOutput height in pixels
mainLayernumberLayer index to use for duration

CustomPlacement

PropertyTypeDescription
widthstringWidth (pixels or percentage)
heightstringHeight (pixels or percentage)
position{ x?: string, y?: string }Position coordinates
paddingnumberPadding in pixels
aspectRatiostringAspect ratio (e.g., "16:9")

How is this guide?