Developer
Log in

Actions

Sources

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

source.copy_settingsCopy a source's settings to another

Gives one source the settings of another of the same kind, as Copy settings and Paste settings do: two Auroras made to glow alike, a second capture card set up like the first, a title given another's font and colors. What makes each one itself stays its own (what an Aurora follows, which device or window a capture shows, a file, a title's words). One undo step.

Keyscope: manage

Parameters

  • fromsourcerequired

    The source to copy from: its id or name. Give its id or name.

    Choices in sources

  • tosourcerequired

    The source to paste onto, of the same kind: its id or name. Give its id or name.

    Choices in sources

Result

  • changedarray of stringalways

    The settings that changed on it.

  • fromstring (uuid)always

    The source copied from.

  • keptarray of stringalways

    The settings each source of its kind keeps its own (never copied).

  • tostring (uuid)always

    The source pasted onto.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.copy_settings",
  "params": {
    "from": "<source id or name>",
    "to": "<source id or name>"
  }
}

In the SDKs

C#
Task<SourceCopySettingsResult> SourceCopySettingsAsync(SourceCopySettingsParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceCopySettings(params: SourceCopySettingsParams): Promise<SourceCopySettingsResult>
Python
async def source_copy_settings(self, *, from_: str, to: str) -> SourceCopySettingsResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "from": {
        "description": "The source to copy from: its id or name. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "to": {
        "description": "The source to paste onto, of the same kind: its id or name. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "from",
      "to"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "changed": {
        "description": "The settings that changed on it.",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "from": {
        "description": "The source copied from.",
        "format": "uuid",
        "type": "string"
      },
      "kept": {
        "description": "The settings each source of its kind keeps its own (never copied).",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "to": {
        "description": "The source pasted onto.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "from",
      "to",
      "changed",
      "kept"
    ],
    "type": "object"
  }
}

source.record_separatelyRecord this source separately

Records a clean source feed beside the next program recording, when the encoder budget allows it. Options left out keep their settings; mode defaults to toggle. Audio defaults to none.

Keyscope: manage

Parameters

  • sourcesourcerequired

    The video source. Give its id or name.

    Choices in sources

  • modechoiceoptional

    Turn separate recording on, off or toggle it.

    One of on off toggle

  • audiochoiceoptional

    No audio, or this source's own audio.

    One of none source

  • cap_canvasbooloptional

    Limit the source's size to the canvas, keeping its shape.

Result

  • audiostringalways

    One of "none" "source"

  • cap_canvasbooleanalways
  • enabledbooleanalways
  • sourcestring (uuid)always

Live state

This action has no live state.

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

In the SDKs

C#
Task<SourceRecordSeparatelyResult> SourceRecordSeparatelyAsync(SourceRecordSeparatelyParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceRecordSeparately(params: SourceRecordSeparatelyParams): Promise<SourceRecordSeparatelyResult>
Python
async def source_record_separately(self, *, source: str, audio: SourceRecordSeparatelyAudio | None = None, cap_canvas: bool | None = None, mode: SourceRecordSeparatelyMode | None = None) -> SourceRecordSeparatelyResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "audio": {
        "description": "No audio, or this source's own audio.",
        "enum": [
          "none",
          "source"
        ],
        "type": "string"
      },
      "cap_canvas": {
        "description": "Limit the source's size to the canvas, keeping its shape.",
        "type": "boolean"
      },
      "mode": {
        "description": "Turn separate recording on, off or toggle it.",
        "enum": [
          "on",
          "off",
          "toggle"
        ],
        "type": "string"
      },
      "source": {
        "description": "The video source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "audio": {
        "enum": [
          "none",
          "source"
        ],
        "type": "string"
      },
      "cap_canvas": {
        "type": "boolean"
      },
      "enabled": {
        "type": "boolean"
      },
      "source": {
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "source",
      "enabled",
      "audio",
      "cap_canvas"
    ],
    "type": "object"
  }
}

source.setSet a source's setting

Sets one setting of a source: one Studio makes itself (an Aurora's follows, colors, palette, points, edges, intensity, softness, reach, drift or ease; a blur box's blur, strength, angle, block size, feather, corner radius, tint, brightness or opacity; catalog.list has them under source_settings) or a plugin's source (the settings its plugin made automatable, such as an avatar's held expression, camera or outfit; catalog.list has the loaded plugins' under plugin_settings). The source_settings topic lists every source's settings with their names, ranges and values now. A number can also move by a step (for dials); an on/off setting takes "toggle". Saved with the collection, like an Inspector edit. Give value or step.

KeyDialscope: manage

Parameters

  • sourcesourcerequired

    The source: its id or name. Give its id or name.

    Choices in sources

  • settingtextrequired

    The setting's key, such as softness, palette or expression_0_active.

    Up to 64 characters

  • valuejsonoptional

    The new value: true or false (or "toggle") for an on/off setting, a number, a choice's word, a color ("#rrggbb"), words, a list of colors ("#rrggbb"), or sources and scenes (a list, by name or id).

  • stepnumberoptional

    Move a number setting by this much (a dial's turn), within its range.

    -10000 to 10000

Result

  • settingstringalways
  • sourcestring (uuid)always

    The source's id.

  • valuenumber or boolean or string or arrayalways

    The value it was set to; sources as a list of ids, a palette as its colors, a color as "#rrggbb".

Live state

sources.items[source].settings[setting] any

The setting's value now. From the sources topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.set",
  "params": {
    "source": "<source id or name>",
    "setting": "<text>"
  }
}

In the SDKs

C#
Task<SourceSetResult> SourceSetAsync(SourceSetParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceSet(params: SourceSetParams): Promise<SourceSetResult>
Python
async def source_set(self, *, setting: str, source: str, step: float | None = None, value: Any | None = None) -> SourceSetResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "setting": {
        "description": "The setting's key, such as softness, palette or expression_0_active.",
        "maxLength": 64,
        "type": "string"
      },
      "source": {
        "description": "The source: its id or name. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "step": {
        "description": "Move a number setting by this much (a dial's turn), within its range.",
        "maximum": 10000.0,
        "minimum": -10000.0,
        "type": "number"
      },
      "value": {
        "description": "The new value: true or false (or \"toggle\") for an on/off setting, a number, a choice's word, a color (\"#rrggbb\"), words, a list of colors (\"#rrggbb\"), or sources and scenes (a list, by name or id).",
        "items": {
          "type": "string"
        },
        "type": [
          "number",
          "boolean",
          "string",
          "array"
        ]
      }
    },
    "required": [
      "source",
      "setting"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "setting": {
        "type": "string"
      },
      "source": {
        "description": "The source's id.",
        "format": "uuid",
        "type": "string"
      },
      "value": {
        "description": "The value it was set to; sources as a list of ids, a palette as its colors, a color as \"#rrggbb\".",
        "items": {
          "type": "string"
        },
        "type": [
          "number",
          "boolean",
          "string",
          "array"
        ]
      }
    },
    "required": [
      "source",
      "setting",
      "value"
    ],
    "type": "object"
  }
}

source.triggerTrigger a source's action

Fires one of a plugin source's actions, as its button in the Inspector does: an avatar's "Toggle expression", for one. The settings whose kind is trigger in the source_settings topic (catalog.list's plugin_settings has their schemas). Nothing is stored: there is nothing to save or undo.

Keyscope: control

Parameters

  • sourcesourcerequired

    The plugin's source: its id or name. Give its id or name.

    Choices in sources

  • settingtextrequired

    The trigger's key, such as expression_0_toggle.

    Up to 64 characters

Result

  • namestringalways

    The trigger's name, as pickers show it.

  • settingstringalways
  • sourcestring (uuid)always

    The source's id.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.trigger",
  "params": {
    "source": "<source id or name>",
    "setting": "<text>"
  }
}

In the SDKs

C#
Task<SourceTriggerResult> SourceTriggerAsync(SourceTriggerParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceTrigger(params: SourceTriggerParams): Promise<SourceTriggerResult>
Python
async def source_trigger(self, *, setting: str, source: str) -> SourceTriggerResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "setting": {
        "description": "The trigger's key, such as expression_0_toggle.",
        "maxLength": 64,
        "type": "string"
      },
      "source": {
        "description": "The plugin's source: its id or name. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source",
      "setting"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "The trigger's name, as pickers show it.",
        "type": "string"
      },
      "setting": {
        "type": "string"
      },
      "source": {
        "description": "The source's id.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "source",
      "setting",
      "name"
    ],
    "type": "object"
  }
}

text.setSet text

Changes what a text source says.

Keyscope: manage

Parameters

  • sourcetext_sourcerequired

    The text source. Give its id or name.

    Choices in sources

  • texttextrequired

    The new text.

    Up to 10000 characters

Result

  • sourcestring (uuid)always

    The text source's id.

  • textstringalways

Live state

sources.items[source].text string

What the text source says now. From the sources topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "text.set",
  "params": {
    "source": "<text source id or name>",
    "text": "<text>"
  }
}

In the SDKs

C#
Task<TextSetResult> TextSetAsync(TextSetParams parameters, CancellationToken cancellationToken = default)
TypeScript
textSet(params: TextSetParams): Promise<TextSetResult>
Python
async def text_set(self, *, source: str, text: str) -> TextSetResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "source": {
        "description": "The text source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "text": {
        "description": "The new text.",
        "maxLength": 10000,
        "type": "string"
      }
    },
    "required": [
      "source",
      "text"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "source": {
        "description": "The text source's id.",
        "format": "uuid",
        "type": "string"
      },
      "text": {
        "type": "string"
      }
    },
    "required": [
      "source",
      "text"
    ],
    "type": "object"
  }
}

source.remove_from_all_scenesRemove a source from all scenes

Removes every layer of a source, on every scene and canvas (nested scenes and vertical layouts included); the source itself stays. Automations that used one of those layers are turned off. Needs "confirm": true; one undo puts it all back.

Keydestructivescope: manage

Parameters

  • sourcesourcerequired

    The source. Give its id or name.

    Choices in sources

  • confirmboolrequired

    Must be true.

    Must be true

Result

  • automations_turned_offintegeralways

    Automations turned off because they used it.

  • deletedbooleanalways

    True when the source itself was deleted too.

  • layers_removedintegeralways

    Layers removed, on every scene and canvas.

  • sourcestring (uuid)always

    The source's id.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.remove_from_all_scenes",
  "params": {
    "source": "<source id or name>",
    "confirm": true
  }
}

In the SDKs

C#
Task<SourceRemoveFromAllScenesResult> SourceRemoveFromAllScenesAsync(SourceRemoveFromAllScenesParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceRemoveFromAllScenes(params: SourceRemoveFromAllScenesParams): Promise<SourceRemoveFromAllScenesResult>
Python
async def source_remove_from_all_scenes(self, *, confirm: bool, source: str) -> SourceRemoveFromAllScenesResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "confirm": {
        "const": true,
        "description": "Must be true.",
        "type": "boolean"
      },
      "source": {
        "description": "The source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source",
      "confirm"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "automations_turned_off": {
        "description": "Automations turned off because they used it.",
        "type": "integer"
      },
      "deleted": {
        "description": "True when the source itself was deleted too.",
        "type": "boolean"
      },
      "layers_removed": {
        "description": "Layers removed, on every scene and canvas.",
        "type": "integer"
      },
      "source": {
        "description": "The source's id.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "source",
      "deleted",
      "layers_removed",
      "automations_turned_off"
    ],
    "type": "object"
  }
}

source.delete_everywhereDelete a source everywhere

Deletes a source and every layer of it. Automations that used it are turned off, detectors stop watching it (one that watched only it is deleted), and Mirrors and settings that pointed at it point at nothing. Needs "confirm": true; one undo puts it all back.

Keydestructivescope: manage

Parameters

  • sourcesourcerequired

    The source. Give its id or name.

    Choices in sources

  • confirmboolrequired

    Must be true.

    Must be true

Result

  • automations_turned_offintegeralways

    Automations turned off because they used it.

  • deletedbooleanalways

    True when the source itself was deleted too.

  • layers_removedintegeralways

    Layers removed, on every scene and canvas.

  • sourcestring (uuid)always

    The source's id.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.delete_everywhere",
  "params": {
    "source": "<source id or name>",
    "confirm": true
  }
}

In the SDKs

C#
Task<SourceDeleteEverywhereResult> SourceDeleteEverywhereAsync(SourceDeleteEverywhereParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceDeleteEverywhere(params: SourceDeleteEverywhereParams): Promise<SourceDeleteEverywhereResult>
Python
async def source_delete_everywhere(self, *, confirm: bool, source: str) -> SourceDeleteEverywhereResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "confirm": {
        "const": true,
        "description": "Must be true.",
        "type": "boolean"
      },
      "source": {
        "description": "The source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source",
      "confirm"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "automations_turned_off": {
        "description": "Automations turned off because they used it.",
        "type": "integer"
      },
      "deleted": {
        "description": "True when the source itself was deleted too.",
        "type": "boolean"
      },
      "layers_removed": {
        "description": "Layers removed, on every scene and canvas.",
        "type": "integer"
      },
      "source": {
        "description": "The source's id.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "source",
      "deleted",
      "layers_removed",
      "automations_turned_off"
    ],
    "type": "object"
  }
}

source.mergeMerge duplicate sources

Merges sources of the same kind into one (the keep source's settings win): every layer, automation, detector and Mirror that used one of them uses the keeper, the others are deleted, and their names keep working as names of the keeper. Needs "confirm": true; one undo puts it all back.

Keydestructivescope: manage

Parameters

  • keepsourcerequired

    The source to keep. Give its id or name.

    Choices in sources

  • mergetext_listrequired

    The sources to merge into it, by id or name.

    Up to 64 items

  • confirmboolrequired

    Must be true.

    Must be true

Result

  • keepstring (uuid)always

    The id of the source kept.

  • layers_repointedintegeralways

    Layers that now show the kept source.

  • mergedarray of string (uuid)always

    The ids of the sources merged into it (now deleted).

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.merge",
  "params": {
    "keep": "<source id or name>",
    "merge": [
      "<text>"
    ],
    "confirm": true
  }
}

In the SDKs

C#
Task<SourceMergeResult> SourceMergeAsync(SourceMergeParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceMerge(params: SourceMergeParams): Promise<SourceMergeResult>
Python
async def source_merge(self, *, confirm: bool, keep: str, merge: list[str]) -> SourceMergeResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "confirm": {
        "const": true,
        "description": "Must be true.",
        "type": "boolean"
      },
      "keep": {
        "description": "The source to keep. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "merge": {
        "description": "The sources to merge into it, by id or name.",
        "items": {
          "type": "string"
        },
        "maxItems": 64,
        "type": "array"
      }
    },
    "required": [
      "keep",
      "merge",
      "confirm"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "keep": {
        "description": "The id of the source kept.",
        "format": "uuid",
        "type": "string"
      },
      "layers_repointed": {
        "description": "Layers that now show the kept source.",
        "type": "integer"
      },
      "merged": {
        "description": "The ids of the sources merged into it (now deleted).",
        "items": {
          "format": "uuid",
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": [
      "keep",
      "merged",
      "layers_repointed"
    ],
    "type": "object"
  }
}

mirror.showPoint a Mirror

Chooses what a Mirror source shows: another source with a picture, or nothing.

Keyscope: control

Parameters

  • mirrorsourcerequired

    The Mirror source. Give its id or name.

    Choices in sources

  • sourcesourceoptional

    What it shows; nothing when left out. Give its id or name.

    Choices in sources

Result

  • mirrorstring (uuid)always

    The Mirror's id.

  • showsstring (uuid)alwayscan be null

    The id of the source it shows now, or null for nothing.

Live state

sources.items[mirror].shows string

The id of the source the Mirror shows (null for nothing). From the sources topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mirror.show",
  "params": {
    "mirror": "<source id or name>"
  }
}

In the SDKs

C#
Task<MirrorShowResult> MirrorShowAsync(MirrorShowParams parameters, CancellationToken cancellationToken = default)
TypeScript
mirrorShow(params: MirrorShowParams): Promise<MirrorShowResult>
Python
async def mirror_show(self, *, mirror: str, source: str | None = None) -> MirrorShowResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "mirror": {
        "description": "The Mirror source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "source": {
        "description": "What it shows; nothing when left out. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "mirror"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "mirror": {
        "description": "The Mirror's id.",
        "format": "uuid",
        "type": "string"
      },
      "shows": {
        "description": "The id of the source it shows now, or null for nothing.",
        "format": "uuid",
        "type": [
          "string",
          "null"
        ]
      }
    },
    "required": [
      "mirror",
      "shows"
    ],
    "type": "object"
  }
}

capture.targetsWhat a capture can show

Lists what a display, window or game capture can be switched to now, as its Capture menu does: every display (name, size and where it sits, such as "DELL U2720Q · 2560×1440 · left"), the open windows, or for game capture "Whichever game is in front" and then the games and other windows. current is the one it shows now. Where the desktop's own dialog chooses (Linux on Wayland), a display or window capture lists only @choose, which opens that dialog again: no app may list what it offers.

Keyscope: control

Parameters

  • sourcesourcerequired

    The display, window or game capture. Give its id or name.

    Choices in sources

Result

CaptureTargets

  • chooserCaptureChooser (string)always

    Who picks: list, from these targets; system, the desktop's own dialog (Linux on Wayland), so a display or window capture has only @choose.

    One of "list" "system"

  • currentstringalwayscan be null

    The id of the target it shows now, or null.

  • kindCaptureKind (string)always

    What it captures.

    One of "display" "window" "game"

  • screens_onlybooleanalways

    The desktop's dialog shares whole screens only.

  • sourcestring (uuid)always

    The capture's id.

  • targetsarray of CaptureTargetalways
    Fields of targets
    • classstringoptional
    • currentbooleanalways

      The one it shows now.

    • displaystringoptional

      A display's own name.

    • exestringoptional

      The program's file name.

    • gamestringoptionalcan be null

      Why a window counts as a game (installed from a game library, captured before), or null.

    • groupCaptureGroup (string)always

      Where the menu lists it.

      One of "displays" "front" "games" "windows" "choose"

    • heightintegeroptional
    • idstringalways

      What capture.set takes: a display's id, a window's saved form, @front or @choose.

    • missingbooleanoptional

      Chosen before but not connected or open now.

    • namestringalways

      As the Capture menu shows it.

    • positionstringoptional

      Where a display sits among the others: left, right, middle, top, bottom, top left... (empty with one).

    • primarybooleanoptional
    • titlestringoptional

      A window's title.

    • widthintegeroptional
    • xintegeroptional
    • yintegeroptional

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "capture.targets",
  "params": {
    "source": "<source id or name>"
  }
}

In the SDKs

C#
Task<CaptureTargets> CaptureTargetsAsync(CaptureTargetsParams parameters, CancellationToken cancellationToken = default)
TypeScript
captureTargets(params: CaptureTargetsParams): Promise<CaptureTargets>
Python
async def capture_targets(self, *, source: str) -> CaptureTargets
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "source": {
        "description": "The display, window or game capture. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "chooser": {
        "description": "Who picks: list, from these targets; system, the desktop's own dialog (Linux on Wayland), so a display or window capture has only @choose.",
        "enum": [
          "list",
          "system"
        ],
        "title": "CaptureChooser",
        "type": "string"
      },
      "current": {
        "description": "The id of the target it shows now, or null.",
        "type": [
          "string",
          "null"
        ]
      },
      "kind": {
        "description": "What it captures.",
        "enum": [
          "display",
          "window",
          "game"
        ],
        "title": "CaptureKind",
        "type": "string"
      },
      "screens_only": {
        "description": "The desktop's dialog shares whole screens only.",
        "type": "boolean"
      },
      "source": {
        "description": "The capture's id.",
        "format": "uuid",
        "type": "string"
      },
      "targets": {
        "items": {
          "additionalProperties": false,
          "properties": {
            "class": {
              "type": "string"
            },
            "current": {
              "description": "The one it shows now.",
              "type": "boolean"
            },
            "display": {
              "description": "A display's own name.",
              "type": "string"
            },
            "exe": {
              "description": "The program's file name.",
              "type": "string"
            },
            "game": {
              "description": "Why a window counts as a game (installed from a game library, captured before), or null.",
              "type": [
                "string",
                "null"
              ]
            },
            "group": {
              "description": "Where the menu lists it.",
              "enum": [
                "displays",
                "front",
                "games",
                "windows",
                "choose"
              ],
              "title": "CaptureGroup",
              "type": "string"
            },
            "height": {
              "type": "integer"
            },
            "id": {
              "description": "What capture.set takes: a display's id, a window's saved form, @front or @choose.",
              "type": "string"
            },
            "missing": {
              "description": "Chosen before but not connected or open now.",
              "type": "boolean"
            },
            "name": {
              "description": "As the Capture menu shows it.",
              "type": "string"
            },
            "position": {
              "description": "Where a display sits among the others: left, right, middle, top, bottom, top left... (empty with one).",
              "type": "string"
            },
            "primary": {
              "type": "boolean"
            },
            "title": {
              "description": "A window's title.",
              "type": "string"
            },
            "width": {
              "type": "integer"
            },
            "x": {
              "type": "integer"
            },
            "y": {
              "type": "integer"
            }
          },
          "required": [
            "id",
            "name",
            "group",
            "current"
          ],
          "title": "CaptureTarget",
          "type": "object"
        },
        "type": "array"
      }
    },
    "required": [
      "source",
      "kind",
      "chooser",
      "screens_only",
      "current",
      "targets"
    ],
    "title": "CaptureTargets",
    "type": "object"
  }
}

capture.setSwitch what a capture shows

Switches a display, window or game capture to another target from capture.targets: a display's id, a window's id (its saved form, title:class:exe, which also finds a window that isn't open yet), @front for game capture's whichever game is in front, or @choose to open the desktop's own dialog again (Wayland). Saved like any edit; the capture keeps its place, crop and filters.

Keyscope: control

Parameters

  • sourcesourcerequired

    The display, window or game capture. Give its id or name.

    Choices in sources

  • targettextrequired

    A target's id from capture.targets.

    Up to 2048 characters

Result

  • namestringalways

    The target, as the Capture menu shows it.

  • sourcestring (uuid)always

    The capture's id.

  • targetstringalways

    The target it was switched to.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "capture.set",
  "params": {
    "source": "<source id or name>",
    "target": "<text>"
  }
}

In the SDKs

C#
Task<CaptureSetResult> CaptureSetAsync(CaptureSetParams parameters, CancellationToken cancellationToken = default)
TypeScript
captureSet(params: CaptureSetParams): Promise<CaptureSetResult>
Python
async def capture_set(self, *, source: str, target: str) -> CaptureSetResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "source": {
        "description": "The display, window or game capture. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "target": {
        "description": "A target's id from capture.targets.",
        "maxLength": 2048,
        "type": "string"
      }
    },
    "required": [
      "source",
      "target"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "The target, as the Capture menu shows it.",
        "type": "string"
      },
      "source": {
        "description": "The capture's id.",
        "format": "uuid",
        "type": "string"
      },
      "target": {
        "description": "The target it was switched to.",
        "type": "string"
      }
    },
    "required": [
      "source",
      "target",
      "name"
    ],
    "type": "object"
  }
}

media.controlMedia control

Plays, pauses, restarts, stops or seeks a media source (a video, a sound or a playlist), or moves a playlist to its next or previous item. With seek_ms and an action, it seeks first ("seek to 30 s and play"); with seek_ms alone, a paused source stays paused.

KeyDialscope: control

Parameters

  • sourcemedia_sourcerequired

    The media source. Give its id or name.

    Choices in media

  • actionchoiceoptional

    What to do; toggle when neither this nor seek_ms is given.

    One of play pause toggle restart stop next previous

  • seek_msintegeroptional

    Jump to this many milliseconds into the item playing.

    0 to 86400000 ms

Result

  • actionMediaAction (string)alwayscan be null

    What was asked; null for a seek alone.

    One of "play" "pause" "toggle" "restart" "stop" "next" "previous" null

  • seek_msintegeralwayscan be null

    Where it was asked to seek to, if it was.

  • sourcestring (uuid)always

    The media source's id.

  • statusMediaStatusalwayscan be null

    Its playback when asked (before the change, which follows in the media topic); null before it's been opened.

    Fields of status
    • at_msintegeralways

      When position_ms was true (Unix ms).

    • duration_msintegeralwayscan be null
    • errorstringalwayscan be null
    • itemintegeralways
    • item_namestringalways
    • itemsintegeralways
    • on_airbooleanalways
    • position_msintegeralways

      Milliseconds into the item at at_ms.

    • speednumberalways

      How fast it plays (1 is as the file is): the position moves on this many ms a ms.

    • stateMediaPlayState (string)always

      One of "idle" "opening" "playing" "paused" "stopped" "ended"

Live state

media.items[source].state string

idle, opening, playing, paused, stopped or ended. From the media topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "media.control",
  "params": {
    "source": "<media source id or name>"
  }
}

In the SDKs

C#
Task<MediaControlResult> MediaControlAsync(MediaControlParams parameters, CancellationToken cancellationToken = default)
TypeScript
mediaControl(params: MediaControlParams): Promise<MediaControlResult>
Python
async def media_control(self, *, source: str, action: MediaAction | None = None, seek_ms: int | None = None) -> MediaControlResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "action": {
        "description": "What to do; toggle when neither this nor seek_ms is given.",
        "enum": [
          "play",
          "pause",
          "toggle",
          "restart",
          "stop",
          "next",
          "previous"
        ],
        "type": "string"
      },
      "seek_ms": {
        "description": "Jump to this many milliseconds into the item playing.",
        "maximum": 86400000,
        "minimum": 0,
        "type": "integer"
      },
      "source": {
        "description": "The media source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "action": {
        "description": "What was asked; null for a seek alone.",
        "enum": [
          "play",
          "pause",
          "toggle",
          "restart",
          "stop",
          "next",
          "previous",
          null
        ],
        "title": "MediaAction",
        "type": [
          "string",
          "null"
        ]
      },
      "seek_ms": {
        "description": "Where it was asked to seek to, if it was.",
        "type": [
          "integer",
          "null"
        ]
      },
      "source": {
        "description": "The media source's id.",
        "format": "uuid",
        "type": "string"
      },
      "status": {
        "additionalProperties": false,
        "description": "Its playback when asked (before the change, which follows in the media topic); null before it's been opened.",
        "properties": {
          "at_ms": {
            "description": "When position_ms was true (Unix ms).",
            "type": "integer"
          },
          "duration_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "item": {
            "type": "integer"
          },
          "item_name": {
            "type": "string"
          },
          "items": {
            "type": "integer"
          },
          "on_air": {
            "type": "boolean"
          },
          "position_ms": {
            "description": "Milliseconds into the item at at_ms.",
            "type": "integer"
          },
          "speed": {
            "description": "How fast it plays (1 is as the file is): the position moves on this many ms a ms.",
            "type": "number"
          },
          "state": {
            "enum": [
              "idle",
              "opening",
              "playing",
              "paused",
              "stopped",
              "ended"
            ],
            "title": "MediaPlayState",
            "type": "string"
          }
        },
        "required": [
          "state",
          "on_air",
          "position_ms",
          "at_ms",
          "duration_ms",
          "item",
          "items",
          "item_name",
          "error",
          "speed"
        ],
        "title": "MediaStatus",
        "type": [
          "object",
          "null"
        ]
      }
    },
    "required": [
      "source",
      "action",
      "seek_ms",
      "status"
    ],
    "type": "object"
  }
}

media.speedMedia speed

Sets how fast a media source plays, 0.25× to 4× (1 is as the file is), or moves it by a step (for dials). Its sound keeps its pitch; the picture, seeking and its end follow the speed. Saved with the source, like its Speed in the Inspector. Give speed or step.

KeyDialscope: control

Parameters

  • sourcemedia_sourcerequired

    The media source. Give its id or name.

    Choices in media

  • speednumberoptional

    The speed: 0.25, 0.5, 0.75, 1, 1.25, 1.5, 2 or 4, or any other in between.

    0.25 to 4 ×

  • stepnumberoptional

    Move the speed by this much (a dial's turn), within 0.25 to 4.

    -4 to 4 ×

Result

  • changedbooleanalways

    Whether the speed changed (false when it already played at it).

  • sourcestring (uuid)always

    The media source's id.

  • speednumberalways

    How fast it plays now (1 is as the file is).

Live state

media.items[source].speed number

How fast it plays (1 is as the file is). From the media topic. How to read it.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "media.speed",
  "params": {
    "source": "<media source id or name>"
  }
}

In the SDKs

C#
Task<MediaSpeedResult> MediaSpeedAsync(MediaSpeedParams parameters, CancellationToken cancellationToken = default)
TypeScript
mediaSpeed(params: MediaSpeedParams): Promise<MediaSpeedResult>
Python
async def media_speed(self, *, source: str, speed: float | None = None, step: float | None = None) -> MediaSpeedResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "source": {
        "description": "The media source. Give its id or name.",
        "minLength": 1,
        "type": "string"
      },
      "speed": {
        "description": "The speed: 0.25, 0.5, 0.75, 1, 1.25, 1.5, 2 or 4, or any other in between.",
        "maximum": 4.0,
        "minimum": 0.25,
        "type": "number"
      },
      "step": {
        "description": "Move the speed by this much (a dial's turn), within 0.25 to 4.",
        "maximum": 4.0,
        "minimum": -4.0,
        "type": "number"
      }
    },
    "required": [
      "source"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "changed": {
        "description": "Whether the speed changed (false when it already played at it).",
        "type": "boolean"
      },
      "source": {
        "description": "The media source's id.",
        "format": "uuid",
        "type": "string"
      },
      "speed": {
        "description": "How fast it plays now (1 is as the file is).",
        "type": "number"
      }
    },
    "required": [
      "source",
      "speed",
      "changed"
    ],
    "type": "object"
  }
}

ndi.sendersNDI® senders

Lists the NDI senders on the network now: {senders: [{name, url, machine, label}]}. An NDI source shows one by its name (source.set with setting ndi_name).

Displayscope: control

Parameters

None. Leave params out.

Result

  • sendersarray of objectalways

    NDI® senders on the network now.

    Fields of senders
    • labelstringalways
    • machinestringalways
    • namestringalways

      Its full name, "MACHINE (Name)": what an NDI source is set to.

    • urlstringalways

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ndi.senders"
}

In the SDKs

C#
Task<NdiSendersResult> NdiSendersAsync(CancellationToken cancellationToken = default)
TypeScript
ndiSenders(): Promise<NdiSendersResult>
Python
async def ndi_senders(self) -> NdiSendersResult
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": {
      "senders": {
        "description": "NDI® senders on the network now.",
        "items": {
          "additionalProperties": false,
          "properties": {
            "label": {
              "type": "string"
            },
            "machine": {
              "type": "string"
            },
            "name": {
              "description": "Its full name, \"MACHINE (Name)\": what an NDI source is set to.",
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "url",
            "machine",
            "label"
          ],
          "type": "object"
        },
        "type": "array"
      }
    },
    "required": [
      "senders"
    ],
    "type": "object"
  }
}

source.ndi_sendSend a source over NDI®

Sends one source on its own as an NDI sender (OBS's NDI filter): its picture and sound, its picture, its sound (after its filters, before its fader), or nothing. Saved with the collection.

Keyscope: manage

Parameters

  • sourcesourcerequired

    The source: its id or name. Give its id or name.

    Choices in sources

  • sendchoicerequired

    off, video_audio, video or audio.

    One of off video_audio video audio

  • nametextoptional

    The sender's name; left out keeps its name, empty goes back to "Velum Studio - <source>".

    Up to 256 characters

Result

  • sendNdiSend (string)always

    One of "off" "video_audio" "video" "audio"

  • sourcestring (uuid)always

    The source's id.

Live state

This action has no live state.

Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "source.ndi_send",
  "params": {
    "source": "<source id or name>",
    "send": "off"
  }
}

In the SDKs

C#
Task<SourceNdiSendResult> SourceNdiSendAsync(SourceNdiSendParams parameters, CancellationToken cancellationToken = default)
TypeScript
sourceNdiSend(params: SourceNdiSendParams): Promise<SourceNdiSendResult>
Python
async def source_ndi_send(self, *, send: NdiSend, source: str, name: str | None = None) -> SourceNdiSendResult
JSON Schema
JSON
{
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "name": {
        "description": "The sender's name; left out keeps its name, empty goes back to \"Velum Studio - <source>\".",
        "maxLength": 256,
        "type": "string"
      },
      "send": {
        "description": "off, video_audio, video or audio.",
        "enum": [
          "off",
          "video_audio",
          "video",
          "audio"
        ],
        "type": "string"
      },
      "source": {
        "description": "The source: its id or name. Give its id or name.",
        "minLength": 1,
        "type": "string"
      }
    },
    "required": [
      "source",
      "send"
    ],
    "type": "object"
  },
  "result_schema": {
    "additionalProperties": false,
    "properties": {
      "send": {
        "enum": [
          "off",
          "video_audio",
          "video",
          "audio"
        ],
        "title": "NdiSend",
        "type": "string"
      },
      "source": {
        "description": "The source's id.",
        "format": "uuid",
        "type": "string"
      }
    },
    "required": [
      "source",
      "send"
    ],
    "type": "object"
  }
}

to open · ↑ ↓ to move · Esc to close