> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Branded video-room backgrounds

> Register your organization's virtual background images once in the Voice → Video → Backgrounds console or the background-library API — every meeting participant then picks them alongside the built-in presets in the in-call Background panel.

# Branded video-room backgrounds

A branded background is a virtual background image your organization
registers once — a label plus an `https://` image URL — that then appears in
the in-call background picker of **every** video room in your workspace,
alongside the built-in presets. Use them to put a consistent, on-brand scene
behind every participant: an HQ lobby, a product wall, an event backdrop.

Registered backgrounds are **workspace-wide**. Any participant in any room
opens the in-meeting **Background** panel and sees their own workspace's
library listed next to the built-in images and the blur option. The image
lives on your own CDN or brand-asset host; Orbit stores the URL, and each
participant's browser fetches the image directly at pick time — you keep
control of your own assets and retention.

## Where it lives

The library console sits at **Voice → Video → Backgrounds**. Owners and
admins manage it there; over the API the same surface is the
`/api/v1/video/background-library` routes: list (read scope), register, and
remove (write scope + `owner`, `admin`, or `developer` role).

## Register a background

Each entry is a **name** (the label shown in the picker, up to 80
characters) plus an **image URL**. The console and the API apply the same
checks:

* **HTTPS only.** Plain `http://` URLs are rejected; a participant's browser
  would block the mixed-content fetch and the image would silently never
  load.
* **Standard web formats.** Serve a JPEG, PNG, or WebP. Any image host you
  control works — a CDN, a public bucket, your own asset store.
* **Sensible dimensions.** A 16:9 image (for example 1280×720) replaces the
  camera scene edge to edge; other aspect ratios still work but letterbox or
  crop.
* **Reachable by every participant.** The URL must be publicly fetchable —
  nothing behind VPN-only hosts — and an empty or unreachable URL shows as a
  muted broken tile in the picker rather than a black backdrop.
* **CORS-friendly.** Because each participant's browser fetches the image
  directly, your host should allow cross-origin reads; hosts that block them
  mark the tile as unreachable for participants.

The library holds **up to 50 backgrounds** per workspace. Once you're at the
cap, remove an entry before adding another. Registering the same URL twice
is rejected.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/video/background-library" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HQ lobby",
    "url": "https://cdn.example.com/backgrounds/hq-lobby.jpg"
  }'
```

The POST returns the registered asset (`201`), read its id (`vbg_…`) for
removals. `GET /api/v1/video/background-library` lists every registered
entry; `DELETE /api/v1/video/background-library/:assetId` removes one and
returns `404` when the id was never registered.

```json theme={null}
{
  "background": {
    "id": "vbg_3f9a…",
    "name": "HQ lobby",
    "url": "https://cdn.example.com/backgrounds/hq-lobby.jpg",
    "created_at": "2026-09-04T12:00:00Z",
    "created_by": "usr_8c1…"
  }
}
```

<Note>
  Removing an entry is shared and instant — it disappears from the picker in
  every room immediately and there is no undo. The console gates removal
  behind a confirmation dialog for that reason.
</Note>

## Room policy: off, allowed, or required

A room's media policy decides whether a virtual background is even an option
for its participants. The `virtual_background` knob accepts three values:

| Policy              | Effect on the picker                                                                          |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `allowed` (default) | Participants may turn on blur or pick any image — built-in or branded.                        |
| `off`               | The picker is disabled for that room.                                                         |
| `required`          | Participants must run a virtual background; the branded library is what forces it onto-brand. |

The policy lives on the room itself (`POST /video/rooms-scheduled`), or on a
saved **room template** so every meeting created from that template inherits
it — the room-default versus per-room behavior:

* **Room default** — an operator sets the policy once on the template and
  every meeting spun up from it behaves the same.
* **Per-meeting override** — set the policy on the individual room when it
  is created instead of inheriting from a template.
* **Participant choice** — a participant can never force the picker open
  when the room says `off`; an `allowed` or `required` room still leaves
  each person free to switch their own background mid-call among the
  workspace library, the built-in presets, blur, and (in the dashboard room
  surface) a one-off upload for their own session.

## What participants see

Every participant — guests on an invite link included — opens the
**Background** control in the in-meeting toolbar. The panel shows, in order:
background off, **Blur**, the built-in images, the workspace's branded
entries, and (dashboard rooms) a personal upload. Picking one applies it to
that participant's own camera only; the choice never affects anyone else in
the room, and it persists on that person's device for their next session.
Guests and panelists get the same picker, so an invited external attendee
also respects your brand when your policy requires a background.

## Worked example: brand-team admin

You want your sales rooms to show the lobby backdrop behind every
consultant. Do it once:

1. Open **Voice → Video → Backgrounds** in the dashboard.
2. Name the entry `HQ lobby`.
3. Paste the image URL — `https://cdn.acme.example/backgrounds/hq-lobby.jpg`.
4. Choose **Add**. The thumbnail preview confirms the image renders.
5. Update the **Rooms → Templates** sales template to `required` on virtual
   backgrounds, so every room from that template now sources the library.

Every consultant's next meeting shows `HQ lobby` in the same workspace
section of the picker panel.

## Worked example: invited participant

You were sent a meeting link for a branded sales call:

1. Open the invite link and redeem it — you land in the room.
2. Open the **Background** control in the meeting toolbar.
3. Pick **HQ lobby** from the workspace section of the panel — the built-in
   *Blur* and presets work too.
4. The camera preview swaps on your own tile; nobody else's view changes.

<Warning>
  An unreachable or non-HTTPS image URL shows a muted broken tile in the
  picker — register the URL again with a publicly fetchable `https://` endpoint
  if participants see that.
</Warning>

## Where to go next

* [Video meetings and conferences](/guides/video-meetings) — schedule the
  room, hand out invite links, set the media policy the background lives
  under.
* [Room access tokens](/guides/video-room-access-tokens) — how a join gets
  into a room with the right participant tier.
* [The video room model](/concepts/video-room-model) — how rooms, sessions,
  and the template that carries their policy fit together.
* [Embed a video-consultation button](/guides/embed-video-consultation-button)
  — the widget surfaces the same in-call picker on your own site.
* [Video API reference](/api-reference/video) — the full room-config field
  list, including `virtual_background` on rooms and templates.