Required Permissions: slobs.scenes-sources

The sources module can be used to list and modify Desktop sources and their properties. It can also be used to subscribe to events about sources.

Source `object`

The source 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 source
name	string	The display name of this source
type	string	The type of source. This cannot be changed after creation. Available source types: - `image_source` - `color_source` - `browser_source` - `slideshow` - `ffmpeg_source` - `text_gdiplus` - `text_ft2_source` - `monitor_capture` - `window_capture` - `game_capture` - `dshow_input` - `wasapi_input_capture` - `wasapi_output_capture` - `decklink-input` - `scene` - `ndi_source`
flags	SourceFlags	An object describing the flags on the source
size	SourceSize	An object describing the size of the source in pixels
appId	string	If this source belongs to an application running on the Streamlabs Desktop platform, this field will contain the id of the application.
appSourceId	string	The id (type) of the source as listed in the application manifest.

SourceFlags `object`

These flags describe some common properties of a source.

Property	Type	Description
audio	boolean	Whether this source has an audio component
video	boolean	Whether this source has a video component

SourceSize `object`

This object describes the size of a source in pixels.

Property	Type	Description
width	number	The width of the source in pixels
height	number	The height of the source in pixels

sourceAdded `event`

This event is emitted whenever a new source is added. Your callback will be called with a Source object.

Example

streamlabsOBS.v1.Sources.sourceAdded(source => {
  console.log('Source Added', source);
});

sourceUpdated `event`

This event is emitted whenever a source is changed. Your callback will be called with a Source object.

Example

streamlabsOBS.v1.Sources.sourceUpdated(source => {
  console.log('Source Updated', source);
});

sourceRemoved `event`

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

Example

streamlabsOBS.v1.Sources.sourceRemoved(id => {
  console.log('Source Removed', id);
});

getAvailableSourceTypes `method`

getAvailableSourceTypes(): string[]

This function can be used to fetch a list of available source types loaded by OBS. The contents of this list can vary depending on the system and which OBS plugins and runtimes are loaded.

Arguments

None

Returns

An array of strings representing the currently loaded source types.

Example

streamlabsOBS.v1.Sources.getAvailableSourceTypes().then(types => {
  console.log(types);
});

getSources `method`

getSources(): Source[]

Arguments

This method does not take any arguments

Returns

This method returns an array of Source objects.

Example

streamlabsOBS.v1.Sources.getSources().then(sources => {
  console.log('Got sources!', sources);
});

getSource `method`

getSource(sourceId: string): Source | null

Get a specific source via ID.

Arguments

sourceId: The ID of the source to be retrieved.

Returns

Returns the serialized Source or null if the source cannot be found.

Example

streamlabsOBS.v1.Sources.getSource('sourceid').then(source => {
  console.log('source was:', source);
});

getAppSources `method`

getAppSources(): Source[]

This method is similar to getSources except it only returns sources that belong to this app.

Arguments

This method does not take any arguments

Returns

This method returns an array of Source objects.

Example

streamlabsOBS.v1.Sources.getAppSources().then(sources => {
  console.log('Got sources!', sources);
});

setAppSourceSettings `method`

setAppSourceSettings(sourceId: string, settings: string): void

This method will set source-specific settings on a particular source that your app owns. These settings will be available in that source via the settings query parameter. The settings are passed as a string, which means you are responsible for serializing and deserializing the settings using something like JSON. The string will be URI-encoded before it is passed into the URL of your source, so you should use decodeURIComponent to decode it before using it. The source will be refreshed whenever the settings are changed.

Arguments

sourceId: The id of the source you want to set settings on
settings: A string representing your encoded settings

Returns

None

Example

// settings.html
streamlabsOBS.v1.Sources.setAppSourceSettings(
  'browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  JSON.stringify({ color: '#ffffff' })
);

// widget.html
let query = location.search.substr(1);
let settings;
query.split('&').forEach(part => {
  var item = part.split('=');
  if (item[0] === 'settings') {
    settings = JSON.parse(decodeURIComponent(item[1]));
  }
});

console.log('Got color!', settings.color);

getAppSourceSettings `method`

getAppSourceSettings(sourceId: string): string

The method fetches the current settings on a source.

Arguments

sourceId: The id of the source to fetch from.

Returns

The settings string for the source.

Example

streamlabsOBS.v1.Sources.getAppSourceSettings(
  'browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7'
).then(settings => {
  console.log('Got settings:', settings);
});

createSource `method`

createSource(name: string, type: string, settings?: Dictionary<any>): Source

🚧
Warning
This function is designed for creating sources that your app does not expose. You are unable to create app sources using this function. If you want to programmatically create a source that your app exposes, use createAppSource instead.

Creates a raw OBS source.

Arguments

name: The name of the source
type: The type of the source. Must be one of the options in the return value of getAvailableSourceTypes
settings: A list of OBS settings to apply to the source. This varies by source type, and listing all of the available options is beyond the scope of this documentation.

Returns

A Source object.

Example

streamlabsOBS.v1.Sources.createSource('My Color Source', 'color_source');

createAppSource `method`

createAppSource(name: string, appSourceId: string): Source

Create a source that your app exposed. Generally we recommend that you let users add your source manually in the scenes they want choose. However, sometimes it can be desirable for you to automatically set up one or more of your sources.

Arguments

name: The name of the source
appSourceId: The id of the source type that you specified in your application's manifest.json file.

Returns

A Source object.

Example

streamlabsOBS.v1.Sources.createAppSource('My Cool Widget', 'widget_type_1');

updateSource `method`

updateSource(sourcePatch: Partial<Source>): void

This function can be used to update a source. Currently the only mutable properties on a source are: name, volume, and muted.

Arguments

sourcePatch: A partial Source object. id is required.

Returns

None

Example

streamlabsOBS.v1.Sources.updateSource({
  id: 'browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  name: 'New Name'
});

removeSource `method`

removeSource(sourceId: string): void

Removes a source.

📘
This function is rarely needed. Sources are automatically removed when the last scene item referencing it is removed. The only time you need this function is if you created a source, but never added it as a scene item.

Arguments

sourceId: The id of the source to remove

Returns

None

Example

streamlabsOBS.v1.Sources.removeSource('browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7');

getObsSettings `method`

getObsSettings(sourceId: string): Dictionary<any>

This function returns the underlying OBS settings for a source. These map to the settings shown in the source properties window in Streamlabs Desktop, and are different for every source type. Exhaustively documenting them here is beyond the scope of this documentation, but if you need help modifying the underlying settings of a source, please feel free to reach out to the Streamlabs development team.

Arguments

sourceId: The id of the source to fetch settings for

Returns

An object mapping settings to their current value

Example

streamlabsOBS.v1.Sources.getObsSettings('browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7')
  .then(settings => {
    console.log('Got settings', settings);
  });

setObsSettings `method`

setObsSettings(sourceId: string, settings: Dictionary<any>): void

This function can be used to change the underlying OBS settings for a source.

Arguments

sourceId: The id of the source to set settings for
settings:: An object with keys of settings to change. The key should be the setting, and the value should be the value you want to set.

Returns

None

Example

// Modify the browser source to shutdown when not visible,
// and also modify its viewport width to 400 pixels.
streamlabsOBS.v1.Sources.setObsSettings(
  'browser_source_2d9fd894-d1a2-4aed-8fcd-25884ebc13a7',
  {
    shutdown: true,
    width: 400
  }
);

Source object

SourceFlags object

SourceSize object

sourceAdded event

Example

sourceUpdated event

Example

sourceRemoved event

Example

getAvailableSourceTypes method

Arguments

Returns

Example

getSources method

Arguments

Returns

Example

getSource method

Arguments

Returns

Example

getAppSources method

Arguments

Returns

Example

setAppSourceSettings method

Arguments

Returns

Example

getAppSourceSettings method

Arguments

Returns

Example

createSource method

🚧Warning

Arguments

Returns

Example

createAppSource method

Arguments

Returns

Example

updateSource method

Arguments

Returns

Example

removeSource method

📘

Arguments

Returns

Example

getObsSettings method

Arguments

Returns

Example

setObsSettings method

Arguments

Returns

Example

Source `object`

SourceFlags `object`

SourceSize `object`

sourceAdded `event`

sourceUpdated `event`

sourceRemoved `event`

getAvailableSourceTypes `method`

getSources `method`

getSource `method`

getAppSources `method`

setAppSourceSettings `method`

getAppSourceSettings `method`

createSource `method`

🚧
Warning

createAppSource `method`

updateSource `method`

removeSource `method`

getObsSettings `method`

setObsSettings `method`