Actions
Layers
8 actions in the Layers group. Each is its own JSON-RPC method, and also runs through action.run.
layer.visibilityShow or hide a layer
Shows, hides or toggles one layer of a scene.
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
Show, hide, or toggle.
Say it was meant to animate (the layer's own show and hide transitions play either way).
Result
layerstring (uuid)alwaysThe layer's id.
visiblebooleanalways
Live state
layers.items[layer].visible bool
On while the layer shows. From the layers topic. How to read it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.visibility",
"params": {
"layer": "<layer id>"
}
}In the SDKs
Task<LayerVisibilityResult> LayerVisibilityAsync(LayerVisibilityParams parameters, CancellationToken cancellationToken = default)layerVisibility(params: LayerVisibilityParams): Promise<LayerVisibilityResult>async def layer_visibility(self, *, layer: str | int, animate: bool | None = None, mode: LayerVisibilityMode | None = None, scene: str | None = None) -> LayerVisibilityResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"animate": {
"default": false,
"description": "Say it was meant to animate (the layer's own show and hide transitions play either way).",
"type": "boolean"
},
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"mode": {
"default": "toggle",
"description": "Show, hide, or toggle.",
"enum": [
"show",
"hide",
"toggle"
],
"type": "string"
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
}
},
"required": [
"layer"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
},
"visible": {
"type": "boolean"
}
},
"required": [
"layer",
"visible"
],
"type": "object"
}
}layer.restartRestart a layer
Plays a layer's show again from its start: its show transition, and a video or animation it shows from its first frame. A hidden layer is shown. (A hide then a show, however close together, does the same.)
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
Result
layerstring (uuid)alwaysThe layer's id.
visiblebooleanalways
Live state
layers.items[layer].visible bool
On while the layer shows. From the layers topic. How to read it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.restart",
"params": {
"layer": "<layer id>"
}
}In the SDKs
Task<LayerRestartResult> LayerRestartAsync(LayerRestartParams parameters, CancellationToken cancellationToken = default)layerRestart(params: LayerRestartParams): Promise<LayerRestartResult>async def layer_restart(self, *, layer: str | int, scene: str | None = None) -> LayerRestartResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
}
},
"required": [
"layer"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
},
"visible": {
"type": "boolean"
}
},
"required": [
"layer",
"visible"
],
"type": "object"
}
}layer.freeze_on_airFreeze when its scene comes on air
Turns a layer's "Freeze when this scene comes on air" setting on, off, or the other way: while on, the layer shows the picture it had when its scene came on air, and the same source stays live everywhere else.
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
On, off, or toggle.
Result
freeze_on_airbooleanalwayslayerstring (uuid)alwaysThe layer's id.
Live state
layers.items[layer].freeze_on_air bool
On while the layer's setting is on. From the layers topic. How to read it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.freeze_on_air",
"params": {
"layer": "<layer id>"
}
}In the SDKs
Task<LayerFreezeOnAirResult> LayerFreezeOnAirAsync(LayerFreezeOnAirParams parameters, CancellationToken cancellationToken = default)layerFreezeOnAir(params: LayerFreezeOnAirParams): Promise<LayerFreezeOnAirResult>async def layer_freeze_on_air(self, *, layer: str | int, mode: LayerFreezeOnAirMode | None = None, scene: str | None = None) -> LayerFreezeOnAirResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"mode": {
"default": "toggle",
"description": "On, off, or toggle.",
"enum": [
"on",
"off",
"toggle"
],
"type": "string"
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
}
},
"required": [
"layer"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"freeze_on_air": {
"type": "boolean"
},
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
}
},
"required": [
"layer",
"freeze_on_air"
],
"type": "object"
}
}layer.copy_styleCopy a layer's style to another
Gives one layer the look of another, as Copy style and Paste style do: its border (with or without its colors), corners, effects, crop, size and place, blend or show and hide transitions. One undo step; parts the other layer can't take are left out.
Parameters
The layer to copy from: its id; or, with scene, its per-scene number or the name of what it places.
The layer to paste onto, named the same way.
The scene both layers are in, when they're given by number or name. Give its id or name.
What to copy; all_style (everything but size and place) when left out.
Result
fromstring (uuid)alwaysThe layer copied from.
pastedarray of stringalwaysThe parts it took.
skippedarray of objectalwaysParts it couldn't take, and why.
Fields of
skippedpartstringalwaysreasonstringalways
tostring (uuid)alwaysThe layer pasted onto.
Live state
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.copy_style",
"params": {
"from": "<layer id>",
"to": "<layer id>"
}
}In the SDKs
Task<LayerCopyStyleResult> LayerCopyStyleAsync(LayerCopyStyleParams parameters, CancellationToken cancellationToken = default)layerCopyStyle(params: LayerCopyStyleParams): Promise<LayerCopyStyleResult>async def layer_copy_style(self, *, from_: str | int, to: str | int, parts: list[LayerCopyStylePart] | None = None, scene: str | None = None) -> LayerCopyStyleResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"from": {
"description": "The layer to copy from: its id; or, with scene, its per-scene number or the name of what it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"parts": {
"description": "What to copy; all_style (everything but size and place) when left out.",
"items": {
"enum": [
"all_style",
"border",
"border_shape",
"corners",
"effects",
"crop",
"transform",
"blend",
"transitions"
],
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"scene": {
"description": "The scene both layers are in, when they're given by number or name. Give its id or name.",
"minLength": 1,
"type": "string"
},
"to": {
"description": "The layer to paste onto, named the same way.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
}
},
"required": [
"from",
"to"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"from": {
"description": "The layer copied from.",
"format": "uuid",
"type": "string"
},
"pasted": {
"description": "The parts it took.",
"items": {
"enum": [
"border",
"border_shape",
"corners",
"effects",
"crop",
"transform",
"blend",
"transitions"
],
"type": "string"
},
"type": "array"
},
"skipped": {
"description": "Parts it couldn't take, and why.",
"items": {
"additionalProperties": false,
"properties": {
"part": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"required": [
"part",
"reason"
],
"type": "object"
},
"type": "array"
},
"to": {
"description": "The layer pasted onto.",
"format": "uuid",
"type": "string"
}
},
"required": [
"from",
"to",
"pasted",
"skipped"
],
"type": "object"
}
}layer.opacityLayer opacity
Sets how see-through a layer is, 0 (gone) to 100 (solid), or moves it by a step (for dials). Its picture, border and glow fade together. Give exactly one of percent or step.
DialKeyscope: control
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
The opacity, 0 to 100.
Move the opacity by this much (a dial's turn), within 0 to 100.
Result
layerstring (uuid)alwaysThe layer's id.
opacitynumberalwaysIts opacity now, 0 to 100.
Live state
layers.items[layer].opacity number
The layer's opacity, 0 to 100. From the layers topic. How to read it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.opacity",
"params": {
"layer": "<layer id>"
}
}In the SDKs
Task<LayerOpacityResult> LayerOpacityAsync(LayerOpacityParams parameters, CancellationToken cancellationToken = default)layerOpacity(params: LayerOpacityParams): Promise<LayerOpacityResult>async def layer_opacity(self, *, layer: str | int, percent: float | None = None, scene: str | None = None, step: float | None = None) -> LayerOpacityResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"percent": {
"description": "The opacity, 0 to 100.",
"maximum": 100.0,
"minimum": 0.0,
"type": "number"
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
},
"step": {
"description": "Move the opacity by this much (a dial's turn), within 0 to 100.",
"maximum": 100.0,
"minimum": -100.0,
"type": "number"
}
},
"required": [
"layer"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
},
"opacity": {
"description": "Its opacity now, 0 to 100.",
"type": "number"
}
},
"required": [
"layer",
"opacity"
],
"type": "object"
}
}layer.clipClip to the layer below
Turns a layer's "Clip to layer below" on, off, or the other way: while on, the layer shows only where the layer under it has a picture (Photoshop's clipping mask).
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
On, off, or toggle.
Result
clippedbooleanalwayslayerstring (uuid)alwaysThe layer's id.
Live state
layers.items[layer].clipped bool
On while the layer clips to the one below. From the layers topic. How to read it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.clip",
"params": {
"layer": "<layer id>"
}
}In the SDKs
Task<LayerClipResult> LayerClipAsync(LayerClipParams parameters, CancellationToken cancellationToken = default)layerClip(params: LayerClipParams): Promise<LayerClipResult>async def layer_clip(self, *, layer: str | int, mode: LayerClipMode | None = None, scene: str | None = None) -> LayerClipResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"mode": {
"default": "toggle",
"description": "On, off, or toggle.",
"enum": [
"on",
"off",
"toggle"
],
"type": "string"
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
}
},
"required": [
"layer"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"clipped": {
"type": "boolean"
},
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
}
},
"required": [
"layer",
"clipped"
],
"type": "object"
}
}layer.framingApply a framing
Moves a layer to one of its framings (a saved position, size and crop), animated as the framing says, from wherever the layer is now.
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
The framing: its id or its name (the layers topic lists each layer's framings).
Result
framingstring (uuid)alwaysThe framing's id.
layerstring (uuid)alwaysThe layer's id.
Live state
layers.items[layer].framing string
The id of the framing the layer sits in now (null when it's somewhere else). From the layers topic. How to read it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.framing",
"params": {
"layer": "<layer id>",
"framing": "<text>"
}
}In the SDKs
Task<LayerFramingResult> LayerFramingAsync(LayerFramingParams parameters, CancellationToken cancellationToken = default)layerFraming(params: LayerFramingParams): Promise<LayerFramingResult>async def layer_framing(self, *, framing: str, layer: str | int, scene: str | None = None) -> LayerFramingResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"framing": {
"description": "The framing: its id or its name (the layers topic lists each layer's framings).",
"maxLength": 200,
"type": "string"
},
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
}
},
"required": [
"layer",
"framing"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"framing": {
"description": "The framing's id.",
"format": "uuid",
"type": "string"
},
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
}
},
"required": [
"layer",
"framing"
],
"type": "object"
}
}layer.nudgeNudge a layer
Moves a layer a step from where it is (dx pixels right, dy pixels down; negative for left or up), gliding there from wherever it is on screen. Every press moves it another step, as far as you like, and a press during a move adds to that move.
Parameters
The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.
The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.
How far to move it right, in pixels of the canvas (negative moves it left).
How far to move it down, in pixels of the canvas (negative moves it up); 0 when left out.
How long the glide takes; 150 when left out, 0 for at once.
Result
layerstring (uuid)alwaysThe layer's id.
xnumberalwaysWhere the layer's anchor point ends up, in pixels of the canvas from its frame's left edge.
ynumberalwaysWhere the layer's anchor point ends up, in pixels of the canvas from its frame's top edge.
Live state
{
"jsonrpc": "2.0",
"id": 1,
"method": "layer.nudge",
"params": {
"layer": "<layer id>",
"dx": -16384
}
}In the SDKs
Task<LayerNudgeResult> LayerNudgeAsync(LayerNudgeParams parameters, CancellationToken cancellationToken = default)layerNudge(params: LayerNudgeParams): Promise<LayerNudgeResult>async def layer_nudge(self, *, dx: float, layer: str | int, duration_ms: int | None = None, dy: float | None = None, scene: str | None = None) -> LayerNudgeResultJSON Schema
{
"params_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"duration_ms": {
"description": "How long the glide takes; 150 when left out, 0 for at once.",
"maximum": 2000,
"minimum": 0,
"type": "integer"
},
"dx": {
"description": "How far to move it right, in pixels of the canvas (negative moves it left).",
"maximum": 16384.0,
"minimum": -16384.0,
"type": "number"
},
"dy": {
"description": "How far to move it down, in pixels of the canvas (negative moves it up); 0 when left out.",
"maximum": 16384.0,
"minimum": -16384.0,
"type": "number"
},
"layer": {
"description": "The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.",
"oneOf": [
{
"description": "The layer's id, or with scene the name of the source or scene it places.",
"minLength": 1,
"type": "string"
},
{
"description": "The layer's per-scene number (scene_item_id), with scene.",
"minimum": 1,
"type": "integer"
}
]
},
"scene": {
"description": "The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.",
"minLength": 1,
"type": "string"
}
},
"required": [
"layer",
"dx"
],
"type": "object"
},
"result_schema": {
"additionalProperties": false,
"properties": {
"layer": {
"description": "The layer's id.",
"format": "uuid",
"type": "string"
},
"x": {
"description": "Where the layer's anchor point ends up, in pixels of the canvas from its frame's left edge.",
"type": "number"
},
"y": {
"description": "Where the layer's anchor point ends up, in pixels of the canvas from its frame's top edge.",
"type": "number"
}
},
"required": [
"layer",
"x",
"y"
],
"type": "object"
}
}
