Scenes Module

Required Permissions: slobs.scenes-sources

The scenes module can be used to fetch and modify scenes as well as the items and folders contained inside them. This API is a work in progress, and if there is something specific you are missing, please contact the Streamlabs development team and let us know what APIs you would like to see here.

Scene object

The scene object is the primary data structure that this API module uses, and will be referenced throughout the documentation for this module.

Property	Type	Description
id	string	A persistent, immutable, and unique identifier for this scene
name	string	The display name of this scene
nodes	(SceneItem | SceneItemFolder)[]	An array of nodes contained in this scene. A node is either a scene item, or a folder, which can contain scene items or other folders.

SceneItem object

A scene item is an instance of a source inside a scene. For example, a Color Source might be a 100 pixel wide and 200 pixel high white block. However, this source can be added to many different scenes and be positioned, stretched, or scaled differently in every scene.

Property	Type	Description
id	string	A persistent, immutable, and unique identifier for this scene item
type	'scene_item'	This field can be used to identify this object as a scene item when iterating across an array of nodes.
sourceId	string	The id of the underlying source this scene item is displaying.
visible	boolean	Whether this scene item is currently visible or hidden.
locked	boolean	Whether this scene item is currently locked in the UI. A locked scene item cannot have its transform changed in the editor. However, this setting has no effect when modifying the transform via the API.
transform	Transform	An object representing the current transform of this scene item.

Transform object

This object represents the geometric transform of a particular scene item.

Property	Type	Description
position	Vec2	A 2-dimensional vector representing the position of this scene item relative to the video canvas.
scale	Vec2	A 2-dimensional vector representing the scale of this object, relative to the width and height of the underlying source.
crop	Crop	An object representing the crop applied to the underlying source.
rotation	number	The rotation of this scene item in degrees. Please note that we currently only support rotations in 90-degree increments, so the only valid values are 0, 90, 180 and 270. Any other values will be rounded and normalized into one of these 4 values.

Vec2 object

A Vec2 is a 2-dimensional vector containing an x and y component. The range of values for the x and y components depend on the use-case. For example, when representing a position, x and y would be pixel values on the canvas. When representing a scale, x and y would be fractional values representing a percentage. For example, 0.5 would be 50%, 1 would be 100%, 1.5 would be 150% etc.

Property	Type	Description
x	number	The horizontal component of the vector.
y	number	The vertical component of the vector.

Crop object

This object describes the crop applied to a scene item. The values are in pixels and represent how much crop has been applied to each edge.

Property	Type	Description
top	number	Crop in pixels applied to the top edge.
bottom	number	Crop in pixels applied to the bottom edge.
left	number	Crop in pixels applied to the left edge.
right	number	Crop in pixels applied to the right edge.

SceneItemFolder object

The scene folder object represents a folder in the Streamlabs Desktop UI. It contains children that are either scene items or other folders.

Property	Type	Description
id	string	A persistent, immutable, and unique identifier for this folder.
type	'folder'	This field can be used to identify this object as a folder when iterating across an array of nodes.
childrenIds	string[]	This is an array of ids corresponding to the children nodes inside this folder. The ids may point to folders or scene items.

sceneAdded event

This event will be emitted when a new scene is added. Your callback will be called with a Scene object.

Example

JavaScript

streamlabsOBS.v1.Scenes.sceneAdded(scene => {
  console.log('A new scene was added', scene);
});

sceneRemoved event

This event will be emitted when a scene is removed. Your callback will be called with the id of the scene that was removed.

JavaScript

streamlabsOBS.v1.Scenes.sceneRemoved(id => {
  console.log('A scene was removed', id);
});

sceneSwitched event

This event will be emitted when the active scene is switched. Your callback will be called with a Scene object representing the scene that was switched to.

JavaScript

streamlabsOBS.v1.Scenes.sceneSwitched(scene => {
  console.log('The active scene was switched', scene);
});

getScenes method

getScenes(): Scene[]

Arguments

This function does not take any arguments

Returns

This function returns an array of Scene objects.

Example

JavaScript

streamlabsOBS.v1.Scenes.getScenes()
  .then(scenes => {
    console.log('Current scenes:', scenes);
  });

getScene method

getScene(id: string): Scene | null

Get a given scene by ID.

Arguments

1. id: ID of the Scene to get.

Returns

Returns Scene or null if Scene with specified ID can't be found.

Examples

JavaScript

streamlabsOBS.v1.Scenes.getScene('sceneid').then(scene => {
  // ...
});

getSceneItem method

getSceneItem(id: string): SceneItem | SceneItemFolder | null

Get a Scene Item by ID

Arguments

1. id: ID of the SceneItem or SceneFolder to get.

Returns

Scene Item or Scene Folder.

JavaScript

streamlabsOBS.v1.Scenes.getSceneItem('sceneItemId').then(sceneItem => {
  if (sceneItem) {
    // Check the type
    if (sceneItem.type === 'folder') {
      // ...
    } else if (sceneItem.type === 'scene_item') {
      // ...
    }
  }
});

getActiveScene method

getActiveScene(): Scene

Fetches the currently active scene.

Arguments

None

Returns

A Scene object.

Example

JavaScript

streamlabsOBS.v1.Scenes.getActiveScene().then(scene => {
  console.log(scene);
});

updateScene method

updateScene(scenePatch: Partial<Scene>): void

Currently name is the only mutable attribute on a scene.

Arguments

1. scenePatch: A partial scene. id is required

Returns

None

Example

JavaScript

// Rename a scene
streamlabsOBS.v1.Scenes.updateScene({
  id: 'scene_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  name: 'New Scene Name'
});

makeSceneActive method

makeSceneActive(id: string): void

Switches to a scene so it is rendered in the video output.

Arguments

1. id: The id of the scene to switch to

Returns

None

Example

JavaScript

streamlabsOBS.v1.Scenes.makeSceneActive(
  'scene_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7'
);

createSceneItem method

createSceneItem(sceneId: string, sourceId: string): SceneItem

Adds a source to a particular scene

Arguments

1. sceneId: The id of the scene to add the source to
2. sourceId: The id of the source to add.

Returns

A SceneItem object.

Example

JavaScript

streamlabsOBS.v1.Scenes.createSceneItem(
  'scene_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  'browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7'
);

updateSceneItem method

updateSceneItem(patch: Partial<SceneItem>): void

The following attributes of a scene item can be changed:

• locked
• visible
• transform

Arguments

1. patch: A partial scene item patch. id is required.

Returns

None

Example

JavaScript

streamlabsOBS.v1.Scenes.updateSceneItem({
  id: '2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  transform: {
    position: { x: 50, y: 100 }
  }
});

removeSceneItem method

removeSceneItem(sceneId: string, sceneItemId: string): void

Removes a scene item from the given scene.

Arguments

1. sceneId: The id of the scene that the scene item lives in
2. sceneItemId: The id of the scene item to remove.

Returns

None

Example

JavaScript

streamlabsOBS.v1.Scenes.removeSceneItem(
  'scene_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  '2f9fd894-d3a2-4aed-8fcd-25884ebc13a7'
);