---
updatedAt: 2025-05-29T22:37:54.000Z
agentTools:
  projectIndex: https://slobs-platform.readme.io/llms.txt
---

# Sources Module

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

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        id
      </td>

      <td>
        string
      </td>

      <td>
        A persistent, immutable, and unique identifier for this source
      </td>
    </tr>

    <tr>
      <td>
        name
      </td>

      <td>
        string
      </td>

      <td>
        The display name of this source
      </td>
    </tr>

    <tr>
      <td>
        type
      </td>

      <td>
        string
      </td>

      <td>
        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`
      </td>
    </tr>

    <tr>
      <td>
        flags
      </td>

      <td>
        [SourceFlags](https://slobs-platform.readme.io/docs/sources-module#section-sourceflags-object-)
      </td>

      <td>
        An object describing the flags on the source
      </td>
    </tr>

    <tr>
      <td>
        size
      </td>

      <td>
        [SourceSize](https://slobs-platform.readme.io/docs/sources-module#section-sourcesize-object-)
      </td>

      <td>
        An object describing the size of the source in pixels
      </td>
    </tr>

    <tr>
      <td>
        appId
      </td>

      <td>
        string
      </td>

      <td>
        If this source belongs to an application running on the Streamlabs Desktop platform, this field will contain the id of the application.
      </td>
    </tr>

    <tr>
      <td>
        appSourceId
      </td>

      <td>
        string
      </td>

      <td>
        The id (type) of the source as listed in the application manifest.
      </td>
    </tr>
  </tbody>
</Table>

# SourceFlags `object`

These flags describe some common properties of a source.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        audio
      </td>

      <td>
        boolean
      </td>

      <td>
        Whether this source has an audio component
      </td>
    </tr>

    <tr>
      <td>
        video
      </td>

      <td>
        boolean
      </td>

      <td>
        Whether this source has a video component
      </td>
    </tr>
  </tbody>
</Table>

# SourceSize `object`

This object describes the size of a source in pixels.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        width
      </td>

      <td>
        number
      </td>

      <td>
        The width of the source in pixels
      </td>
    </tr>

    <tr>
      <td>
        height
      </td>

      <td>
        number
      </td>

      <td>
        The height of the source in pixels
      </td>
    </tr>
  </tbody>
</Table>

# sourceAdded `event`

This event is emitted whenever a new source is added.  Your callback will be called with a [Source](sources-module#section-source-object-) object.

### Example

```javascript
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](sources-module#section-source-object-) object.

### Example

```javascript
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

```javascript
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

```javascript
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](sources-module#section-source-object-) objects.

### Example

```javascript
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

1. `sourceId`: The ID of the source to be retrieved.

### Returns

Returns the [serialized Source](sources-module#section-source-object-) or `null` if the source cannot be found.

### Example

```javascript
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](sources-module#section-source-object-) objects.

### Example

```javascript
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

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

### Returns

None

### Example

```javascript
// 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

1. `sourceId`: The id of the source to fetch from.

### Returns

The settings string for the source.

### Example

```javascript
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

1. `name`: The name of the source
2. `type`: The type of the source.  Must be one of the options in the return value of [getAvailableSourceTypes](sources-module#section-getavailablesourcetypes-method-)
3. `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](sources-module#section-source-object-) object.

### Example

```javascript
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

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

### Returns

A [Source](sources-module#section-source-object-) object.

### Example

```javascript
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

1. `sourcePatch`:  A partial [Source](sources-module#section-source-object-) object.  `id` is required.

### Returns

None

### Example

```javascript
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

1. `sourceId`: The id of the source to remove

### Returns

None

### Example

```javascript
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

1. `sourceId`: The `id` of the source to fetch settings for

### Returns

An object mapping settings to their current value

### Example

```javascript
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

1. `sourceId`: The `id` of the source to set settings for
2. `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

```javascript
// 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
  }
);
```