Developer
Log in

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.

Keyscope: control

Parameters

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

  • modechoiceoptional

    Show, hide, or toggle.

    One of show hide toggle · Default "toggle"

  • animatebooloptional

    Say it was meant to animate (the layer's own show and hide transitions play either way).

    Default false

Result

  • layerstring (uuid)always

    The layer's id.

  • visiblebooleanalways

Live state

layers.items[layer].visible bool

On while the layer shows. From the layers topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.visibility",
  "params": {
    "layer": "<layer id>"
  }
}

In the SDKs

C#
Task<LayerVisibilityResult> LayerVisibilityAsync(LayerVisibilityParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerVisibility(params: LayerVisibilityParams): Promise<LayerVisibilityResult>
Python
async def layer_visibility(self, *, layer: str | int, animate: bool | None = None, mode: LayerVisibilityMode | None = None, scene: str | None = None) -> LayerVisibilityResult
JSON Schema
JSON
{
  "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.)

Keyscope: control

Parameters

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

Result

  • layerstring (uuid)always

    The layer's id.

  • visiblebooleanalways

Live state

layers.items[layer].visible bool

On while the layer shows. From the layers topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.restart",
  "params": {
    "layer": "<layer id>"
  }
}

In the SDKs

C#
Task<LayerRestartResult> LayerRestartAsync(LayerRestartParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerRestart(params: LayerRestartParams): Promise<LayerRestartResult>
Python
async def layer_restart(self, *, layer: str | int, scene: str | None = None) -> LayerRestartResult
JSON Schema
JSON
{
  "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.

Keyscope: manage

Parameters

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

  • modechoiceoptional

    On, off, or toggle.

    One of on off toggle · Default "toggle"

Result

  • freeze_on_airbooleanalways
  • layerstring (uuid)always

    The 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.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.freeze_on_air",
  "params": {
    "layer": "<layer id>"
  }
}

In the SDKs

C#
Task<LayerFreezeOnAirResult> LayerFreezeOnAirAsync(LayerFreezeOnAirParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerFreezeOnAir(params: LayerFreezeOnAirParams): Promise<LayerFreezeOnAirResult>
Python
async def layer_freeze_on_air(self, *, layer: str | int, mode: LayerFreezeOnAirMode | None = None, scene: str | None = None) -> LayerFreezeOnAirResult
JSON Schema
JSON
{
  "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.

Keyscope: manage

Parameters

  • fromlayerrequired

    The layer to copy from: its id; or, with scene, its per-scene number or the name of what it places.

    Choices in layers

  • tolayerrequired

    The layer to paste onto, named the same way.

    Choices in layers

  • scenesceneoptional

    The scene both layers are in, when they're given by number or name. Give its id or name.

    Choices in scenes

  • partschoice_listoptional

    What to copy; all_style (everything but size and place) when left out.

    Any of all_style border border_shape corners effects crop transform blend transitions

Result

  • fromstring (uuid)always

    The layer copied from.

  • pastedarray of stringalways

    The parts it took.

    Each: One of "border" "border_shape" "corners" "effects" "crop" "transform" "blend" "transitions"

  • skippedarray of objectalways

    Parts it couldn't take, and why.

    Fields of skipped
    • partstringalways
    • reasonstringalways
  • tostring (uuid)always

    The layer pasted onto.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.copy_style",
  "params": {
    "from": "<layer id>",
    "to": "<layer id>"
  }
}

In the SDKs

C#
Task<LayerCopyStyleResult> LayerCopyStyleAsync(LayerCopyStyleParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerCopyStyle(params: LayerCopyStyleParams): Promise<LayerCopyStyleResult>
Python
async def layer_copy_style(self, *, from_: str | int, to: str | int, parts: list[LayerCopyStylePart] | None = None, scene: str | None = None) -> LayerCopyStyleResult
JSON Schema
JSON
{
  "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

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

  • percentnumberoptional

    The opacity, 0 to 100.

    0 to 100 %

  • stepnumberoptional

    Move the opacity by this much (a dial's turn), within 0 to 100.

    -100 to 100 %

Result

  • layerstring (uuid)always

    The layer's id.

  • opacitynumberalways

    Its 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.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.opacity",
  "params": {
    "layer": "<layer id>"
  }
}

In the SDKs

C#
Task<LayerOpacityResult> LayerOpacityAsync(LayerOpacityParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerOpacity(params: LayerOpacityParams): Promise<LayerOpacityResult>
Python
async def layer_opacity(self, *, layer: str | int, percent: float | None = None, scene: str | None = None, step: float | None = None) -> LayerOpacityResult
JSON Schema
JSON
{
  "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).

Keyscope: manage

Parameters

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

  • modechoiceoptional

    On, off, or toggle.

    One of on off toggle · Default "toggle"

Result

  • clippedbooleanalways
  • layerstring (uuid)always

    The 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.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.clip",
  "params": {
    "layer": "<layer id>"
  }
}

In the SDKs

C#
Task<LayerClipResult> LayerClipAsync(LayerClipParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerClip(params: LayerClipParams): Promise<LayerClipResult>
Python
async def layer_clip(self, *, layer: str | int, mode: LayerClipMode | None = None, scene: str | None = None) -> LayerClipResult
JSON Schema
JSON
{
  "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.

Keyscope: control

Parameters

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

  • framingtextrequired

    The framing: its id or its name (the layers topic lists each layer's framings).

    Up to 200 characters

Result

  • framingstring (uuid)always

    The framing's id.

  • layerstring (uuid)always

    The 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.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.framing",
  "params": {
    "layer": "<layer id>",
    "framing": "<text>"
  }
}

In the SDKs

C#
Task<LayerFramingResult> LayerFramingAsync(LayerFramingParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerFraming(params: LayerFramingParams): Promise<LayerFramingResult>
Python
async def layer_framing(self, *, framing: str, layer: str | int, scene: str | None = None) -> LayerFramingResult
JSON Schema
JSON
{
  "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.

Keyscope: control

Parameters

  • layerlayerrequired

    The layer: its id; or, with scene, its per-scene number (scene_item_id) or the name of the source or scene it places.

    Choices in layers

  • scenesceneoptional

    The scene the layer is in, when layer is a per-scene number or a name. Give its id or name.

    Choices in scenes

  • dxnumberrequired

    How far to move it right, in pixels of the canvas (negative moves it left).

    -16384 to 16384 px

  • dynumberoptional

    How far to move it down, in pixels of the canvas (negative moves it up); 0 when left out.

    -16384 to 16384 px

  • duration_msintegeroptional

    How long the glide takes; 150 when left out, 0 for at once.

    0 to 2000 ms

Result

  • layerstring (uuid)always

    The layer's id.

  • xnumberalways

    Where the layer's anchor point ends up, in pixels of the canvas from its frame's left edge.

  • ynumberalways

    Where the layer's anchor point ends up, in pixels of the canvas from its frame's top edge.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "layer.nudge",
  "params": {
    "layer": "<layer id>",
    "dx": -16384
  }
}

In the SDKs

C#
Task<LayerNudgeResult> LayerNudgeAsync(LayerNudgeParams parameters, CancellationToken cancellationToken = default)
TypeScript
layerNudge(params: LayerNudgeParams): Promise<LayerNudgeResult>
Python
async def layer_nudge(self, *, dx: float, layer: str | int, duration_ms: int | None = None, dy: float | None = None, scene: str | None = None) -> LayerNudgeResult
JSON Schema
JSON
{
  "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"
  }
}

to open · ↑ ↓ to move · Esc to close