Skip to main content
View as Markdown

Background Replacement (Chroma Key) - Content Management

Background Replacement (Chroma Key)​

Remove a solid-color background from the foreground video and replace it with another video or image.

KalturaReplaceBackgroundAttributes​

ParameterTypeDescription
objectTypestringKalturaReplaceBackgroundAttributes
resourceobjectBackground source (KalturaEntryResource, KalturaAssetResource, or KalturaUrlResource)
backgroundColorCodestringColor to key out, format 0xRRGGBB (default: 0x6FED48 — Kaltura green)
foregroundScalePercentagefloatScale factor for keyed foreground (0–5, default 1.0)
foregroundPositionPercentageobjectPosition of foreground: {x: 0-1, y: 0-1} (KalturaPosition)
audioAttributesobjectAudio mixing for background source

Basic Green Screen Replacement​

Replace a green background with a custom background video:

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_GREEN_SCREEN_ENTRY_ID" \
  -d "resource[resource][flavorParamsId]=0" \
  -d "resource[operationAttributes][0][objectType]=KalturaClipAttributes" \
  -d "resource[operationAttributes][0][offset]=0" \
  -d "resource[operationAttributes][0][duration]=30000" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][objectType]=KalturaReplaceBackgroundAttributes" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][objectType]=KalturaEntryResource" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][entryId]=$KALTURA_BACKGROUND_ENTRY_ID" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][flavorParamsId]=0" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][backgroundColorCode]=0x6FED48"

Custom Foreground Position and Scale​

Position the keyed foreground at center-bottom, scaled to 60%:

  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][foregroundScalePercentage]=0.6" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][foregroundPositionPercentage][x]=0.5" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][foregroundPositionPercentage][y]=0.8"

Using an Image as Background​

Image resources (JPEG, PNG) are auto-looped to match the foreground video duration via FFmpeg's -loop 1 with shortest=1:

  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][objectType]=KalturaUrlResource" \
  -d "resource[operationAttributes][0][mediaCompositionAttributesArray][0][resource][url]=https://example.com/office-background.jpg"