Developer
Log in

Actions

Scenes

4 actions in the Scenes group. Each is its own JSON-RPC method, and also runs through action.run.

scene.switchSwitch scene

Puts a scene on air.

Keyscope: control

Parameters

  • scenescenerequired

    The scene to put on air. Give its id or name.

    Choices in scenes

  • transitiontextoptional

    This switch only: a type (fade, slide, move, layer_by_layer…), an effect, a pack transition or a saved transition's name, as for transition.set. Left out, the scene's own or the default plays.

    Up to 120 characters

  • duration_msintegeroptional

    This switch only: how long it takes (Layer by layer takes as long as its layers' own shows and hides).

    0 to 20000 ms

  • reversebooloptional

    This switch only: play it backward with its pictures swapped.

Result

  • namestringalwayscan be null

    Its name.

  • scenestring (uuid)always

    The id of the scene on air now.

  • transitionTransitionSummaryoptional

    The transition this switch played, when it was given one of its own.

    Fields of transition
    • duration_msintegeralways

      How long it takes; a stinger lasts as long as its video.

    • namestringalways

      Its saved name, else its type's (or effect's, or pack transition's) name.

    • reversebooleanalways

      Whether it plays backward with its pictures swapped.

    • typestringalways

      cut, fade, fade_to_color, slide, swipe, luma_wipe, move, effect, shader, pack or stinger.

Live state

scenes.program == scene bool

On while this scene is on air. From the scenes topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "scene.switch",
  "params": {
    "scene": "<scene id or name>"
  }
}

In the SDKs

C#
Task<SceneSwitchResult> SceneSwitchAsync(SceneSwitchParams parameters, CancellationToken cancellationToken = default)
TypeScript
sceneSwitch(params: SceneSwitchParams): Promise<SceneSwitchResult>
Python
async def scene_switch(self, *, scene: str, duration_ms: int | None = None, reverse: bool | None = None, transition: str | None = None) -> SceneSwitchResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "duration_ms": {
        "description": "This switch only: how long it takes (Layer by layer takes as long as its layers' own shows and hides).",
        "maximum": 20000,
        "minimum": 0,
        "type": "integer"
      },
      "reverse": {
        "description": "This switch only: play it backward with its pictures swapped.",
        "type": "boolean"
      },
      "scene": {
        "description": "The scene to put on air. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "transition": {
        "description": "This switch only: a type (fade, slide, move, layer_by_layer…), an effect, a pack transition or a saved transition's name, as for transition.set. Left out, the scene's own or the default plays.",
        "maxLength": 120,
        "type": "string"
      }
    },
    "required": [
      "scene"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "Its name.",
        "type": [
          "string",
          "null"
        ]
      },
      "scene": {
        "description": "The id of the scene on air now.",
        "format": "uuid",
        "type": "string"
      },
      "transition": {
        "additionalProperties": false,
        "description": "The transition this switch played, when it was given one of its own.",
        "properties": {
          "duration_ms": {
            "description": "How long it takes; a stinger lasts as long as its video.",
            "type": "integer"
          },
          "name": {
            "description": "Its saved name, else its type's (or effect's, or pack transition's) name.",
            "type": "string"
          },
          "reverse": {
            "description": "Whether it plays backward with its pictures swapped.",
            "type": "boolean"
          },
          "type": {
            "description": "cut, fade, fade_to_color, slide, swipe, luma_wipe, move, effect, shader, pack or stinger.",
            "type": "string"
          }
        },
        "required": [
          "type",
          "name",
          "duration_ms",
          "reverse"
        ],
        "title": "TransitionSummary",
        "type": "object"
      }
    },
    "required": [
      "scene",
      "name"
    ],
    "type": "object"
  }
}

scene.nextNext scene

Puts the scene after the one on air on air, in the Scenes list's order (wrapping around).

KeyDialscope: control

Parameters

None. Leave params out.

Result

  • namestringalwayscan be null

    Its name.

  • scenestring (uuid)always

    The id of the scene on air now.

Live state

scenes.program_name string

The name of the scene on air. From the scenes topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "scene.next"
}

In the SDKs

C#
Task<SceneNextResult> SceneNextAsync(CancellationToken cancellationToken = default)
TypeScript
sceneNext(): Promise<SceneNextResult>
Python
async def scene_next(self) -> SceneNextResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {},
    "required": [],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "Its name.",
        "type": [
          "string",
          "null"
        ]
      },
      "scene": {
        "description": "The id of the scene on air now.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "scene",
      "name"
    ],
    "type": "object"
  }
}

scene.previousPrevious scene

Puts the scene before the one on air on air, in the Scenes list's order (wrapping around).

KeyDialscope: control

Parameters

None. Leave params out.

Result

  • namestringalwayscan be null

    Its name.

  • scenestring (uuid)always

    The id of the scene on air now.

Live state

scenes.program_name string

The name of the scene on air. From the scenes topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "scene.previous"
}

In the SDKs

C#
Task<ScenePreviousResult> ScenePreviousAsync(CancellationToken cancellationToken = default)
TypeScript
scenePrevious(): Promise<ScenePreviousResult>
Python
async def scene_previous(self) -> ScenePreviousResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {},
    "required": [],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "Its name.",
        "type": [
          "string",
          "null"
        ]
      },
      "scene": {
        "description": "The id of the scene on air now.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "scene",
      "name"
    ],
    "type": "object"
  }
}

vertical.pinPin the vertical canvas

Keeps the vertical canvas on one scene while the main (landscape) canvas switches scenes, or lets it follow the scene on air again. pin keeps it on the scene; follow lets it follow the scene on air (no scene needed); toggle pins it to the scene, or lets it follow again when it's already pinned there (with no scene, a pinned canvas follows again). A scene with no vertical layout shows its horizontal layout, fitted. Needs the vertical canvas (Settings › Video › Vertical canvas); while it's off, the choice is kept for when it's back on. If the pinned scene is deleted, the vertical canvas follows the scene on air again.

Keyscope: control

Parameters

  • scenesceneoptional

    The scene to keep the vertical canvas on (for pin and toggle). Give its id or name.

    Choices in scenes

  • modechoiceoptional

    Pin, follow the scene on air, or toggle.

    One of pin follow toggle · Default "toggle"

Result

  • namestringalwayscan be null

    That scene's name.

  • pinnedstring (uuid)alwayscan be null

    The id of the scene the vertical canvas is pinned to; null while it follows the scene on air.

Live state

scenes.vertical_pinned == scene bool

On while the vertical canvas is pinned to this scene. From the scenes topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "vertical.pin"
}

In the SDKs

C#
Task<VerticalPinResult> VerticalPinAsync(CancellationToken cancellationToken = default)
Python
async def vertical_pin(self, *, mode: VerticalPinMode | None = None, scene: str | None = None) -> VerticalPinResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "mode": {
        "default": "toggle",
        "description": "Pin, follow the scene on air, or toggle.",
        "enum": [
          "pin",
          "follow",
          "toggle"
        ],
        "type": "string"
      },
      "scene": {
        "description": "The scene to keep the vertical canvas on (for pin and toggle). Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "That scene's name.",
        "type": [
          "string",
          "null"
        ]
      },
      "pinned": {
        "description": "The id of the scene the vertical canvas is pinned to; null while it follows the scene on air.",
        "format": "uuid",
        "type": [
          "string",
          "null"
        ]
      }
    },
    "required": [
      "pinned",
      "name"
    ],
    "type": "object"
  }
}

to open · ↑ ↓ to move · Esc to close