Squeezebacks

effects

The Squeezebacks API allows you to adjust the live video presentation by resizing the primary program video and positioning it within a defined region of the frame. This creates space on screen for additional elements such as graphics or promotional content.

Squeezeback effects take effect immediately when the request is received.

Enabling Squeezebacks

To enable squeezeback support, configure your live pipeline or slicer with:

squeezeback: 1

Once enabled, layout changes can be controlled through the /effects API.

How-to

POST /effects
Content-Type: application/json

The request body defines the current presentation mode. Only one mode is active at a time.

You can switch between:

fullscreen - standard video presentation
squeezeback - reduced video frame positioned within the canvas

Effects apply instantly. Scheduling or timed offsets are not supported.

Request Parameters

The following table describes all available fields in the fullscreen and squeezeback request bodies. Parameters are validated before execution and will prevent invalid configurations, including out-of-bounds positioning or unsupported sizing.

Parameter Reference

Request Parameter	Required	Type	Description
mode	Yes	string	Defines the presentation mode. Accepted values: `squeezeback`, `fullscreen`.
x	Yes (pixel-based squeezeback only)	integer	X-coordinate (top-left corner) of the squeezed video. Not required when using `layout`.
y	Yes (pixel-based squeezeback only)	integer	Y-coordinate (top-left corner) of the squeezed video. Not required when using `layout`.
width	Yes (pixel-based squeezeback only)	integer	Width of the squeezed video region in pixels. Not required when using `layout`.
height	Yes (pixel-based squeezeback only)	integer	Height of the squeezed video region in pixels. Not required when using `layout`.
layout	Yes (layout-based squeezeback only)	string	Preset layout name. Currently supports `l-bar`. When provided, you do not need `x`, `y`, `width`, or `height`.
width_percentage	Optional (layout-based squeezeback only)	integer	Squeezed video width as a percentage of full-frame width (e.g., `75`).
background	Optional	string (file path or URL)	Background image displayed behind the squeezed video. Defaults to solid black.
transition	Optional	object	Optional transition applied when switching layouts. If omitted, the switch is instant.
transition.type	Optional	string	Transition type. Valid options include `move` and `fade`.
transition.duration	Optional	number (seconds)	Duration of the transition.

Modes

You can define a squeezeback in two ways:

Full pixel-based control (x/y/width/height)
Simplified layout control (layout: l-bar)

If you select a layout such as l-bar, you do not need to specify any pixel-based coordinates. Layouts handle sizing and positioning automatically.

Full Pixel-Based Squeezeback Parameters

Use this mode for fully customized placement and sizing.

{
  "mode": "squeezeback",
  "x": <int>,
  "y": <int>,
  "width": <int>,
  "height": <int>,
  "background": "<url|file>",
  "transition": {
    "type": "move|fade",
    "duration": <seconds>
  }
}

Simplified Layout-Based Squeezeback Parameters

This mode avoids manual pixel calculations and uses a preset layout.

{
  "mode": "squeezeback",
  "layout": "l-bar",
  "background": "<url|file>",
  "width_percentage": 75,
  "transition": {
    "type": "move|fade",
    "duration": <seconds>
  }
}

📘
Notes

l-bar places the video in the top-right region.

Pixel values (x, y, width, height) are unnecessary when a layout is used.

Background images remain static behind the squeezed area.

Fullscreen Parameters

Use this mode to return to the standard full-frame video.

{
  "mode": "fullscreen",
  "transition": {
    "type": "move|fade",
    "duration": <seconds>
  }
}

Examples

Squeezeback (1280×720)

{
  "mode": "squeezeback",
  "x": 320,
  "y": 0,
  "width": 960,
  "height": 540,
  "background": "<image-url-or-file>",
  "transition": {
    "type": "move",
    "duration": 1
  }
}

Squeezeback (1920×1080 with fade)

{
  "mode": "squeezeback",
  "x": 480,
  "y": 0,
  "width": 1440,
  "height": 810,
  "background": "<image-url-or-file>",
  "transition": {
    "type": "fade",
    "duration": 2
  }
}

Return to Fullscreen

{
  "mode": "fullscreen",
  "transition": {
    "type": "fade",
    "duration": 2
  }
}