StreamCrafter — Compositor

The compositor enables multi-source layout control — arrange camera and screen share into layouts with scenes, layers, and animated transitions.

On by Default in the Drop-in Components

The React, Svelte, and Web Component drop-in components enable the compositor by default. It works with a single source (fullscreen solo layout) and scales to multi-source layouts automatically. The vanilla createStreamCrafter() facade and the headless controllers leave it off until you call enableCompositor().

Enabling and Disabling the Compositor

In the drop-in components, disable it if you need raw source streaming without compositing overhead:

React:

<StreamCrafter whipUrl="..." enableCompositor={false} />

Svelte:

<StreamCrafter whipUrl="..." enableCompositor={false} />

Web Components:

<!-- Disable via JS property -->
<fw-streamcrafter id="studio" whip-url="..."></fw-streamcrafter>
<script>
  document.getElementById("studio").enableCompositor = false;
</script>

Vanilla: the compositor is off by default. Enable it with a method call, and optionally pass compositor settings:

const studio = createStreamCrafter({ whipUrl: "..." });

await studio.enableCompositor({ width: 1920, height: 1080, frameRate: 30 });

// Later, return to raw source streaming
studio.disableCompositor();

Layout Modes

The compositor ships with 17 built-in layout presets:

Mode	Label	Min Sources	Description
solo	Solo	1	Single source fullscreen
pip-br	PiP (bottom-right)	2	Main + small overlay bottom-right
pip-bl	PiP (bottom-left)	2	Main + small overlay bottom-left
pip-tr	PiP (top-right)	2	Main + small overlay top-right
pip-tl	PiP (top-left)	2	Main + small overlay top-left
split-h	Split Horizontal	2	Side-by-side split
split-v	Split Vertical	2	Top/bottom split
focus-l	Focus Left	2	Large left, small right
focus-r	Focus Right	2	Small left, large right
pip-dual-br	Main + 2 PiP	3	Main with two small overlays
pip-dual-bl	Main + 2 PiP Left	3	Main with two small left overlays
split-pip-l	Split + PiP Left	3	Side-by-side with left overlay
split-pip-r	Split + PiP Right	3	Side-by-side with right overlay
featured	Featured	3	Large center, small sides
featured-r	Featured Right	3	Large right, small left stack
grid	Grid	2+	Equal-size grid
stack	Stack	2+	Vertical stack

Applying Layouts

React (via hook):

const crafter = useStreamCrafterV2({ whipUrl: "..." });
const compositor = useCompositor({
  controller: crafter.getController(),
  autoEnable: true,
});

compositor.applyLayout({ mode: "pip-br", scalingMode: "letterbox", pipScale: 0.25 });

Vanilla:

studio.sceneManager?.applyLayout({
  mode: "split-h",
  scalingMode: "crop",
});

Web Components:

studio.pc
  .getController()
  ?.getSceneManager()
  ?.applyLayout({ mode: "grid", scalingMode: "letterbox" });

Cycling Source Order

In the built-in compositor controls, clicking the active layout again cycles the source order: the first source moves to the back. Hold Shift to cycle backward.

Calling applyLayout() again with the same layout does not cycle. Call cycleSourceOrder() instead:

// React useCompositor hook or Svelte createCompositorStore
compositor.cycleSourceOrder(); // forward
compositor.cycleSourceOrder("backward");

// Core SceneManager
studio.sceneManager?.cycleSourceOrder("forward");

Scaling Modes

Each layout supports three scaling modes that control how sources fill their allocated space:

Mode	Description
letterbox	Fit entire source, add black bars if aspect ratios don’t match
crop	Fill the space completely, cropping edges if needed
stretch	Stretch to fill exactly, ignoring aspect ratio

Scenes

Scenes are named collections of layers with their own layout configurations. Switch between scenes for different broadcast segments.

// React useCompositor hook or Svelte createCompositorStore
const interview = compositor.createScene("interview");
const soloCam = compositor.createScene("solo-cam");

if (interview) {
  await compositor.transitionTo(interview.id, {
    type: "fade",
    durationMs: 500,
    easing: "ease-in-out",
  });
}

When you work directly with the core SceneManager, use the returned scene ID for later calls:

const sceneManager = studio.sceneManager;

// Create a scene
const interview = sceneManager?.createScene("interview");
sceneManager?.createScene("solo-cam");

// Switch to a scene with a transition
if (interview) {
  await sceneManager?.transitionTo(interview.id, {
    type: "fade",
    durationMs: 500,
    easing: "ease-in-out",
  });
}

Transition Types

Type	Description
cut	Instant switch (0ms)
fade	Cross-fade between scenes
slide-left	New scene slides in from right
slide-right	New scene slides in from left
slide-up	New scene slides in from bottom
slide-down	New scene slides in from top

Layers

Each source in a scene becomes a layer with independent controls:

Property	Type	Description
id	string	Layer identifier
sourceId	string	Linked media source
visible	boolean	Show/hide layer
zIndex	number	Stack order (higher = on top)
transform.opacity	number	Layer opacity (0-1)

Layer Operations

const sceneId = compositor.activeSceneId;
if (!sceneId) return;

// Toggle visibility
compositor.setLayerVisibility(sceneId, layerId, false);

// Change opacity
compositor.updateLayerTransform(sceneId, layerId, { opacity: 0.7 });

// Reorder layers by layer ID
compositor.reorderLayers(sceneId, ["layer-1", "layer-2", "layer-3"]);

// Remove a layer
compositor.removeLayer(sceneId, layerId);

Renderer

The compositor automatically selects the best available renderer:

Renderer	Requirements	Performance
webgpu	WebGPU API	Best — GPU-accelerated compositing
webgl	WebGL 2	Good — hardware-accelerated fallback
canvas2d	Canvas API	Baseline — software rendering

The active renderer type and FPS are shown in the compositor controls overlay.

UI Components

Each framework provides compositor UI components:

React:

import {
  CompositorControls,
  SceneSwitcher,
  LayerList,
} from "@livepeer-frameworks/streamcrafter-react";

Svelte:

<script lang="ts">
  import {
    CompositorControls,
    SceneSwitcher,
    LayerList,
  } from "@livepeer-frameworks/streamcrafter-svelte";
</script>

Web Components:

<fw-streamcrafter> renders its own compositor overlay. The standalone <fw-sc-compositor>, <fw-sc-scene-switcher>, and <fw-sc-layer-list> elements are presentational: they do not connect to a <fw-streamcrafter> on their own, so you set their data through JS properties and handle their events or callbacks. See Standalone Sub-Components for the wiring.

The compositor overlay shows layout icons and scaling mode buttons. Click a layout icon to apply it; click the active layout to cycle source order.