---
title: Overlay (Picture-in-Picture)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/video-editing-overlay-picture-in-picture
---

## Overlay (Picture-in-Picture)


Compose one video on top of another at a specified position, size, and shape.

### KalturaOverlayAttributes

| Parameter | Type | Description |
|-----------|------|-------------|
| `objectType` | string | `KalturaOverlayAttributes` |
| `resource` | object | Overlay source (KalturaEntryResource or KalturaAssetResource) |
| `overlayPlacement` | int | Position on 9-point grid (see alignment table) |
| `overlayScalePercentage` | float | Size relative to main video (0.1–0.9) |
| `marginsPercentage` | float | Margin from edges (0.1–0.9) |
| `overlayShape` | int | Shape of overlay window |
| `audioAttributes` | object | Audio mixing settings |
| `resourceMediaCompositionAttributesArray` | array | Nested composition (max 1 — for background replacement on the overlay source) |

### Overlay Placement (KalturaMediaCompositionAlignment)

| Value | Position |
|-------|----------|
| 1 | Top-Left |
| 2 | Top-Center |
| 3 | Top-Right |
| 4 | Center |
| 6 | Bottom-Left |
| 7 | Bottom-Center |
| 8 | Bottom-Right |

### Overlay Shape

| Value | Shape |
|-------|-------|
| 1 | CIRCLE |
| 2 | RECTANGLE |
| 3 | RECTANGLE_ROUNDED_CORNERS |
| 4 | ELLIPSE |

### Basic PiP Example

Place a speaker video (circle, bottom-right, 25% size) over the main presentation:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/media/action/addContent" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "entryId=$KALTURA_ENTRY_ID" \
  -d "resource[objectType]=KalturaOperationResource" \
  -d "resource[resource][objectType]=KalturaEntryResource" \
  -d "resource[resource][entryId]=$KALTURA_MAIN_VIDEO_ENTRY_ID" \
  -d "resource[resource][flavorParamsId]=0" \
  -d "resource[operationAttributes][0][objectType]=KalturaClipAttributes" \
  -d "resource[operationAttributes][0][offset]=0" \
  -d "resource[operationAttributes][0][duration]=60000" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][objectType]=KalturaOverlayAttributes" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][objectType]=KalturaEntryResource" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][entryId]=$KALTURA_OVERLAY_ENTRY_ID" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][flavorParamsId]=0" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][overlayPlacement]=8" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][overlayScalePercentage]=0.25" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][marginsPercentage]=0.1" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][overlayShape]=1"
```