​

Video room templates and the background library

Two artifact models back Orbit’s video rooms: room templates — a saved, named graph of room defaults — and the background library — a curated registry of branded virtual-background images for the workspace. Both are workspace-level artifacts that rooms consume at creation or join time. This page explains the artifact model: what a template freezes, what cloning a template copies into a mutable room, where the drift trade-off lives, and how the background library validates the assets it registers. The endpoint-by-endpoint reference lives in the Video API reference; the click-by-click flows live in the video room templates guide and the branded backgrounds guide. This page is the model those endpoints and guides implement.

​

What a room template is

A room template is a frozen graph of room-creation defaults: a named, saved snapshot of the settings a newly created room should open with. Where a plain room-create body mixes identity (name, scheduled_at, consent receipts) with policy (participant cap, recording, media policy), a template captures only the policy half — the reusable, non-secret subset:

• Capacity and duration — max_participants, max_duration_minutes.
• Recording defaults — recording_enabled, recording_format (composite / per-participant tracks / both), recording_output encoding.
• Media tuning — simulcast, spatial_layers, max_bitrate_kbps, video_codec, svc_scalability_mode, spatial_audio.
• Privacy and accessibility — e2ee, virtual_background, noise_suppression, audio_only, captions_required.
• Region and lobby — region, waiting_room, waiting_room_auto_promote.

What the graph deliberately never holds:

• Per-instance identity — a room’s name and scheduled_at are supplied on every instantiate call, so one template serves every occasion.
• Secrets — recording-storage credentials never persist into workspace settings; a two-party-consent receipt id is passed per instantiation, not stored.

The template config schema rejects unknown keys (.strict()) precisely so credentials or arbitrary blobs can’t be smuggled into the settings blob by a buggy or hostile client. That is what “frozen” buys you: a saved template is a safe, identifiable, reviewable unit of room policy — not a bag of raw create-body fields.

​

The background library: curated assets, not uploads

The second artifact is the background library: a registry of branded virtual-background images that shows up in the in-call picker of every room in the workspace, next to the built-in presets and blur. The library is curated, not uploaded. Each entry is a label (up to 80 characters) plus an https:// image URL the tenant hosts on its own CDN or asset store. Orbit validates the reference; the tenant’s CDN serves the bytes. That split is the distinction from a custom upload flow: The HTTPS-only rule is a hard validation, not a recommendation: the in-call background processor fetches the URL client-side on the HTTPS dashboard, so http:// would die on mixed-content blocking, and non-HTTP schemes (data:, file:, javascript:) are either unbounded blobs or injection vectors. The library holds up to 50 entries per workspace; room templates hold up to 100. A room then decides whether participants may use these images at all through its virtual_background media policy: off (picker disabled), allowed (participants may pick), or required (participants must run a virtual background) — the tenant-owned control that pins the workspace library onto every room from a template.

​

Clone semantics: what instantiating copies, what stays template-bound

POST /video/room-templates/:id/instantiate clones the template into a real room definition. The clone is a snapshot copy, not a live reference: Copied into the room, permanently detached:

• The whole config graph — capacity, duration, recording defaults, media tuning, privacy flags, region, and the waiting-room lobby, which is folded into the room’s stored settings as waiting_room_enabled / auto_promote_from_waiting_room (the same keys a runtime waiting-room update writes).
• Tier and deployment gates, evaluated at clone time: the participant cap is clamped to your plan’s ceiling, and a template that mandates live captions refuses instantiation on a deployment with no caption service configured.

Stays on the template (template-bound):

• The template itself — its name, description, and config graph — which rooms reference only by template_id on their audit trail.
• Editing or deleting a template after rooms were cloned from it changes future clones only; rooms already created keep the configuration the clone captured, down to the recording format.
• What instantiation deliberately does not inherit: a per-template room name (supplied per call) and the live moderator room-lock (a runtime-only action on a live room, valid nowhere else).

That asymmetry is the whole model: clone-copied defaults are mutable room state from the moment of creation; template-bound fields stay immutable and central. A template is a stamp, and instantiate presses it.

​

Versioning: platform stamps versus clone drift

Orbit ships no platform-version stamps on templates. Templates are tenant content — the only clocks on them are the created_at and updated_at recorded when an owner, admin, or developer saves a change. The platform never auto-rewrites your template graph on upgrade, and no version marker is consulted at clone time. That choice has a direct drift consequence: when the platform widens a knob (a new codec, a new region), an old template may clone a stale value, and clones taken before a fix keep the old value while the template row itself still reads as current. The tenant-owned controls to manage that drift:

• updated_at is the freeze marker — audit it before relying on a template whose defaults you last touched a quarter ago.
• An update full-replaces the config (a validated, whole-preset write), not a deep-merge — so re-saving revalidates every field, including the cross-field rule that svc_scalability_mode only makes sense on a vp9/av1 codec.
• Because clones detach at create time, “re-save the template” heals future rooms only; live rooms are reconfigured by editing the room itself.

​

Tenant trust: likeness and adult-safety scoped to what you register

For the background library the likeness and adult-safe question collapses into a hosting claim: the library stores URLs you registered, and your participants’ browsers fetch your CDN directly. The platform control is validation at registration time — HTTPS-scheme, length bound, and duplicate rejection — plus the workspace-level removal action every owner/admin can take. What the platform does not do on curated assets: pixel-level likeness or content screening, because the bytes never touch an Orbit bucket. If you need screened, platform-hosted imagery instead, use the file-upload pipeline with its own moderation surface and register the resulting hosted URL here.

​

API surface

All routes below require video:read to list and video:write plus an owner / admin / developer role to mutate; both libraries are scoped to the tenant and audited on every create, update, and delete. Room templates — /api/v1/video/room-templates: Background library — /api/v1/video/background-library: Both libraries persist on the organization’s settings as bounded JSONB arrays — template ids are vrtpl_-prefixed and background ids vbg_ -prefixed — read on the room-create and join paths without touching per-call media plane state.

​

Related