Overlay (Picture-in-Picture) - Content Management

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:

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"