Overlays

Overlays let you place content on top of other content using multi-track composition. Common use cases include picture-in-picture (PiP), watermarks, lower thirds, and logo placement.

How Overlays Work

In the timeline, tracks are layered from top (track 0) to bottom. Place your overlay content on a lower-numbered track, and it will render on top of content on higher-numbered tracks.

Track 0: Overlay (logo, PiP, watermark)
Track 1: Main content (video, slideshow)

Positioning

Use offset and scale to control overlay placement and size.

Property	Type	Range	Description
offset.x	number	-1 to 1	Horizontal position (-1 = left, 0 = center, 1 = right)
offset.y	number	-1 to 1	Vertical position (-1 = top, 0 = center, 1 = bottom)
scale	number	0.01 to 2	Size multiplier (1 = full frame)
opacity	number	0 to 1	Transparency

Position Reference

(-1, -1)  (0, -1)  (1, -1)
   TL       TC       TR

(-1,  0)  (0,  0)  (1,  0)
   ML       MC       MR

(-1,  1)  (0,  1)  (1,  1)
   BL       BC       BR

Picture-in-Picture Example

curl

curl -X POST https://api.vidiking.com/v1/render \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeline": {
      "tracks": [
        {
          "clips": [
            {
              "asset": {
                "type": "video",
                "src": "https://example.com/webcam.mp4"
              },
              "start": 0,
              "length": 30,
              "scale": 0.25,
              "offset": { "x": 0.7, "y": 0.7 },
              "opacity": 1
            }
          ]
        },
        {
          "clips": [
            {
              "asset": {
                "type": "video",
                "src": "https://example.com/screencast.mp4"
              },
              "start": 0,
              "length": 30,
              "fit": "cover"
            }
          ]
        }
      ]
    },
    "output": { "format": "mp4", "resolution": "1080" }
  }'

Node.js

const { jobId } = await client.render({
  timeline: {
    tracks: [
      {
        clips: [
          {
            asset: { type: 'video', src: 'https://example.com/webcam.mp4' },
            start: 0,
            length: 30,
            scale: 0.25,
            offset: { x: 0.7, y: 0.7 },
          },
        ],
      },
      {
        clips: [
          {
            asset: { type: 'video', src: 'https://example.com/screencast.mp4' },
            start: 0,
            length: 30,
            fit: 'cover',
          },
        ],
      },
    ],
  },
  output: { format: 'mp4', resolution: '1080' },
});

Python

result = client.render({
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {"type": "video", "src": "https://example.com/webcam.mp4"},
                        "start": 0,
                        "length": 30,
                        "scale": 0.25,
                        "offset": {"x": 0.7, "y": 0.7},
                    }
                ]
            },
            {
                "clips": [
                    {
                        "asset": {"type": "video", "src": "https://example.com/screencast.mp4"},
                        "start": 0,
                        "length": 30,
                        "fit": "cover",
                    }
                ]
            },
        ],
    },
    "output": {"format": "mp4", "resolution": "1080"},
})

Logo Watermark Example

Place a semi-transparent logo in the top-right corner for the entire video duration.

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "image",
              "src": "https://example.com/logo-white.png"
            },
            "start": 0,
            "length": 60,
            "scale": 0.1,
            "offset": { "x": 0.85, "y": -0.85 },
            "opacity": 0.6
          }
        ]
      },
      {
        "clips": [
          {
            "asset": { "type": "video", "src": "https://example.com/main.mp4" },
            "start": 0,
            "length": 60
          }
        ]
      }
    ]
  }
}

Lower Third Example

Display a name and title graphic in the lower third of the frame.

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<div class='lower-third'><h2>Jane Smith</h2><p>CEO, Acme Corp</p></div>",
              "css": ".lower-third { background: rgba(0,0,0,0.7); color: white; padding: 16px 32px; border-left: 4px solid #00d4ff; } h2 { margin: 0; font-size: 28px; } p { margin: 4px 0 0; font-size: 18px; opacity: 0.8; }",
              "width": 400,
              "height": 100
            },
            "start": 2,
            "length": 5,
            "offset": { "x": -0.5, "y": 0.7 },
            "transition": { "in": "slideUp", "out": "slideDown" }
          }
        ]
      },
      {
        "clips": [
          {
            "asset": { "type": "video", "src": "https://example.com/interview.mp4" },
            "start": 0,
            "length": 30
          }
        ]
      }
    ]
  }
}

Tips

• Use scale values between 0.1 and 0.3 for PiP overlays.
• PNG images with transparency work best for logos and watermarks.
• Combine opacity with transition for appearing/disappearing overlays.
• Use HTML assets for dynamic lower thirds with custom styling.