> For the complete documentation index, see [llms.txt](https://docs.digitalsamba.com/reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalsamba.com/reference/sdk/methods/configurevirtualbackground.md).

# configureVirtualBackground()

configureVirtualBackground(options: VirtualBackgroundOptions)

Enables or modifies (if already enabled) the virtual background for local user with given options. Either `blur`, `image` or `imageUrl` field needs to be specified.

For a video background you must specify both `videoUrl` and `thumbnailUrl`. The `thumbnailUrl` is the preview image in the virtual background selector.

{% hint style="warning" %}
We don't post-process or modify the video background file. You must ensure you provide a reasonable sized video background (e.g. a few MBs at most).
{% endhint %}

The **enforce** param is optional and if set to true, then it will make it impossible for the local user to manually change the virtual background once entered inside the room.

```typescript
VirtualBackgroundOptions {
    enforce?: boolean;
    blur?: 'balanced' | 'strong';
    image?: string;
    imageUrl?: string;
    videoUrl?: string;
    thumbnailUrl?: string;
}
```

Possible predefined values for image are:\
"**office**", "**office2**", "**beach**", "**fireworks**", "**bookshelf**", "**forest**", "**mountain**", "**savannah**"

```javascript
//Enables strong blur of the background for the local user
sambaFrame.configureVirtualBackground({blur: 'strong'});

/*Enables balanced blur of the background for the local user and enforces it,
  so the user cannot change it once inside the room*/
sambaFrame.configureVirtualBackground({blur: 'balanced', enforce: true});

//Sets a forest virtual background for the local user
sambaFrame.configureVirtualBackground({image: 'forest'});

//Sets an image from a public url as a virtual background for the local user
sambaFrame.configureVirtualBackground({imageUrl: 'https://someUrlOfAnImageHere'});

//Sets a video from a public url as a virtual background for the local user
sambaFrame.configureVirtualBackground({
    videoUrl: 'https://someUrlOfAVideoHere',
    thumbnailUrl: 'https://someUrlOfTheVideoThumbnailImage'
});
```

**Sample use cases**:

* You may want to control virtual background for the local user dynamically during the meeting.

{% hint style="info" %}
The related events are [virtualBackgroundChanged](/reference/sdk/events/virtualbackgroundchanged.md) and [virtualBackgroundDisabled](/reference/sdk/events/virtualbackgrounddisabled.md)\
if you want to be informed when the virtual background settings have been changed.
{% endhint %}

## When the background is not applied

This method does not return a promise and does not throw — it is a one-way command to the room. Not every participant's device can run a virtual background, and applying one can fail. When that happens the participant keeps their **raw camera**.

To detect it, listen for [appError](/reference/sdk/events/apperror.md) with `name: 'virtual-bg'` and a `data.reason` of `'unsupported'` or `'failed'`:

```javascript
sambaFrame.on('appError', (event) => {
  const error = event.data;
  if (error.name !== 'virtual-bg' || !error.data?.reason) return;

  // error.data.reason                  -> 'unsupported' | 'failed'
  // error.data.virtualBackgroundConfig -> the background you requested
  console.warn('Virtual background not applied:', error.data.reason);
});
```

{% hint style="warning" %}
With `enforce: true` the virtual background panel is hidden from the participant, so a refused device is invisible to everyone in the session unless your application listens for this event.
{% endhint %}

See [appError](/reference/sdk/events/apperror.md) for the full payload, and for the timing caveats — an `unsupported` report can arrive up to \~30 seconds after this call and before the participant joins, and a `failed` report can occur more than once per session.