---
title: Background Replacement (Chroma Key)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/video-editing-background-replacement-chroma-key
---

## Background Replacement (Chroma Key)


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

### KalturaReplaceBackgroundAttributes

| Parameter | Type | Description |
|-----------|------|-------------|
| `objectType` | string | `KalturaReplaceBackgroundAttributes` |
| `resource` | object | Background source (KalturaEntryResource, KalturaAssetResource, or KalturaUrlResource) |
| `backgroundColorCode` | string | Color to key out, format `0xRRGGBB` (default: `0x6FED48` — Kaltura green) |
| `foregroundScalePercentage` | float | Scale factor for keyed foreground (0–5, default 1.0) |
| `foregroundPositionPercentage` | object | Position of foreground: `{x: 0-1, y: 0-1}` (KalturaPosition) |
| `audioAttributes` | object | Audio mixing for background source |

### Basic Green Screen Replacement

Replace a green background with a custom background video:


```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_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%:


```bash
  -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`:


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