protocol.md

obs-websocket 4.8.0 protocol reference

General Introduction

Messages are exchanged between the client and the server as JSON objects. This protocol is based on the original OBS Remote protocol created by Bill Hamilton, with new commands specific to OBS Studio.

Authentication

obs-websocket uses SHA256 to transmit credentials.

A request for GetAuthRequired returns two elements:

• A challenge: a random string that will be used to generate the auth response.
• A salt: applied to the password when generating the auth response.

To generate the answer to the auth challenge, follow this procedure:

• Concatenate the user declared password with the salt sent by the server (in this order: password + server salt).
• Generate a binary SHA256 hash of the result and encode the resulting SHA256 binary hash to base64, known as a base64 secret.
• Concatenate the base64 secret with the challenge sent by the server (in this order: base64 secret + server challenge).
• Generate a binary SHA256 hash of the result and encode it to base64.
• Voilà, this last base64 string is the auth response. You may now use it to authenticate to the server with the Authenticate request.

Pseudo Code Example:

password = "supersecretpassword"
challenge = "ztTBnnuqrqaKDzRM3xcVdbYm"
salt = "PZVbYpvAnZut2SS6JNJytDm9"

secret_string = password + salt
secret_hash = binary_sha256(secret_string)
secret = base64_encode(secret_hash)

auth_response_string = secret + challenge
auth_response_hash = binary_sha256(auth_response_string)
auth_response = base64_encode(auth_response_hash)

Table of Contents

• Typedefs
  • SceneItem
  • SceneItemTransform
  • OBSStats
  • Output
  • Scene
• Events
  • Scenes
    • SwitchScenes
    • ScenesChanged
    • SceneCollectionChanged
    • SceneCollectionListChanged
  • Transitions
    • SwitchTransition
    • TransitionListChanged
    • TransitionDurationChanged
    • TransitionBegin
    • TransitionEnd
    • TransitionVideoEnd
  • Profiles
    • ProfileChanged
    • ProfileListChanged
  • Streaming
    • StreamStarting
    • StreamStarted
    • StreamStopping
    • StreamStopped
    • StreamStatus
  • Recording
    • RecordingStarting
    • RecordingStarted
    • RecordingStopping
    • RecordingStopped
    • RecordingPaused
    • RecordingResumed
  • Replay Buffer
    • ReplayStarting
    • ReplayStarted
    • ReplayStopping
    • ReplayStopped
  • Other
    • Exiting
  • General
    • Heartbeat
    • BroadcastCustomMessage
  • Sources
    • SourceCreated
    • SourceDestroyed
    • SourceVolumeChanged
    • SourceMuteStateChanged
    • SourceAudioSyncOffsetChanged
    • SourceAudioMixersChanged
    • SourceRenamed
    • SourceFilterAdded
    • SourceFilterRemoved
    • SourceFilterVisibilityChanged
    • SourceFiltersReordered
  • Scene Items
    • SourceOrderChanged
    • SceneItemAdded
    • SceneItemRemoved
    • SceneItemVisibilityChanged
    • SceneItemLockChanged
    • SceneItemTransformChanged
    • SceneItemSelected
    • SceneItemDeselected
  • Studio Mode
    • PreviewSceneChanged
    • StudioModeSwitched
• Requests
  • General
    • GetVersion
    • GetAuthRequired
    • Authenticate
    • SetHeartbeat
    • SetFilenameFormatting
    • GetFilenameFormatting
    • GetStats
    • BroadcastCustomMessage
    • GetVideoInfo
    • OpenProjector
  • Outputs
    • ListOutputs
    • GetOutputInfo
    • StartOutput
    • StopOutput
  • Profiles
    • SetCurrentProfile
    • GetCurrentProfile
    • ListProfiles
  • Recording
    • StartStopRecording
    • StartRecording
    • StopRecording
    • PauseRecording
    • ResumeRecording
    • SetRecordingFolder
    • GetRecordingFolder
  • Replay Buffer
    • StartStopReplayBuffer
    • StartReplayBuffer
    • StopReplayBuffer
    • SaveReplayBuffer
  • Scene Collections
    • SetCurrentSceneCollection
    • GetCurrentSceneCollection
    • ListSceneCollections
  • Scene Items
    • GetSceneItemProperties
    • SetSceneItemProperties
    • ResetSceneItem
    • SetSceneItemRender
    • SetSceneItemPosition
    • SetSceneItemTransform
    • SetSceneItemCrop
    • DeleteSceneItem
    • DuplicateSceneItem
  • Scenes
    • SetCurrentScene
    • GetCurrentScene
    • GetSceneList
    • ReorderSceneItems
    • SetSceneTransitionOverride
    • RemoveSceneTransitionOverride
    • GetSceneTransitionOverride
  • Sources
    • GetSourcesList
    • GetSourceTypesList
    • GetVolume
    • SetVolume
    • GetMute
    • SetMute
    • ToggleMute
    • SetSourceName
    • SetSyncOffset
    • GetSyncOffset
    • GetSourceSettings
    • SetSourceSettings
    • GetTextGDIPlusProperties
    • SetTextGDIPlusProperties
    • GetTextFreetype2Properties
    • SetTextFreetype2Properties
    • GetBrowserSourceProperties
    • SetBrowserSourceProperties
    • GetSpecialSources
    • GetSourceFilters
    • GetSourceFilterInfo
    • AddFilterToSource
    • RemoveFilterFromSource
    • ReorderSourceFilter
    • MoveSourceFilter
    • SetSourceFilterSettings
    • SetSourceFilterVisibility
    • GetAudioMonitorType
    • SetAudioMonitorType
    • TakeSourceScreenshot
  • Streaming
    • GetStreamingStatus
    • StartStopStreaming
    • StartStreaming
    • StopStreaming
    • SetStreamSettings
    • GetStreamSettings
    • SaveStreamSettings
    • SendCaptions
  • Studio Mode
    • GetStudioModeStatus
    • GetPreviewScene
    • SetPreviewScene
    • TransitionToProgram
    • EnableStudioMode
    • DisableStudioMode
    • ToggleStudioMode
  • Transitions
    • GetTransitionList
    • GetCurrentTransition
    • SetCurrentTransition
    • SetTransitionDuration
    • GetTransitionDuration
    • GetTransitionPosition

Typedefs

These are complex types, such as Source and Scene, which are used as arguments or return values in multiple requests and/or events.

SceneItem

Name	Type	Description
cy	Number
cx	Number
alignment	Number	The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis.
name	String	The name of this Scene Item.
id	int	Scene item ID
render	Boolean	Whether or not this Scene Item is set to "visible".
muted	Boolean	Whether or not this Scene Item is muted.
locked	Boolean	Whether or not this Scene Item is locked and can't be moved around
source_cx	Number
source_cy	Number
type	String	Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"
volume	Number
x	Number
y	Number
parentGroupName	String (optional)	Name of the item's parent (if this item belongs to a group)
groupChildren	Array<SceneItem> (optional)	List of children (if this item is a group)

SceneItemTransform

Name	Type	Description
position.x	int	The x position of the scene item from the left.
position.y	int	The y position of the scene item from the top.
position.alignment	int	The point on the scene item that the item is manipulated from.
rotation	double	The clockwise rotation of the scene item in degrees around the point of alignment.
scale.x	double	The x-scale factor of the scene item.
scale.y	double	The y-scale factor of the scene item.
crop.top	int	The number of pixels cropped off the top of the scene item before scaling.
crop.right	int	The number of pixels cropped off the right of the scene item before scaling.
crop.bottom	int	The number of pixels cropped off the bottom of the scene item before scaling.
crop.left	int	The number of pixels cropped off the left of the scene item before scaling.
visible	bool	If the scene item is visible.
locked	bool	If the scene item is locked in position.
bounds.type	String	Type of bounding box. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE".
bounds.alignment	int	Alignment of the bounding box.
bounds.x	double	Width of the bounding box.
bounds.y	double	Height of the bounding box.
sourceWidth	int	Base width (without scaling) of the source
sourceHeight	int	Base source (without scaling) of the source
width	double	Scene item width (base source width multiplied by the horizontal scaling factor)
height	double	Scene item height (base source height multiplied by the vertical scaling factor)
parentGroupName	String (optional)	Name of the item's parent (if this item belongs to a group)
groupChildren	Array<SceneItemTransform> (optional)	List of children (if this item is a group)

OBSStats

Name	Type	Description
fps	double	Current framerate.
render-total-frames	int	Number of frames rendered
render-missed-frames	int	Number of frames missed due to rendering lag
output-total-frames	int	Number of frames outputted
output-skipped-frames	int	Number of frames skipped due to encoding lag
average-frame-time	double	Average frame render time (in milliseconds)
cpu-usage	double	Current CPU usage (percentage)
memory-usage	double	Current RAM usage (in megabytes)
free-disk-space	double	Free recording disk space (in megabytes)

Output

Name	Type	Description
name	String	Output name
type	String	Output type/kind
width	int	Video output width
height	int	Video output height
flags	Object	Output flags
flags.rawValue	int	Raw flags value
flags.audio	boolean	Output uses audio
flags.video	boolean	Output uses video
flags.encoded	boolean	Output is encoded
flags.multiTrack	boolean	Output uses several audio tracks
flags.service	boolean	Output uses a service
settings	Object	Output name
active	boolean	Output status (active or not)
reconnecting	boolean	Output reconnection status (reconnecting or not)
congestion	double	Output congestion
totalFrames	int	Number of frames sent
droppedFrames	int	Number of frames dropped
totalBytes	int	Total bytes sent

Scene

Name	Type	Description
name	String	Name of the currently active scene.
sources	Array<SceneItem>	Ordered list of the current scene's source items.

Events

Events are broadcast by the server to each connected client when a recognized action occurs within OBS.

An event message will contain at least the following base fields:

• update-type String: the type of event.
• stream-timecode String (optional): time elapsed between now and stream start (only present if OBS Studio is streaming).
• rec-timecode String (optional): time elapsed between now and recording start (only present if OBS Studio is recording).

Timecodes are sent using the format: HH:MM:SS.mmm

Additional fields may be present in the event message depending on the event type.

Scenes

SwitchScenes

• Added in v0.3

Indicates a scene change.

Response Items:

Name	Type	Description
scene-name	String	The new scene.
sources	Array<SceneItem>	List of scene items in the new scene. Same specification as GetCurrentScene.

---

ScenesChanged

• Added in v0.3

The scene list has been modified. Scenes have been added, removed, or renamed.

Response Items:

No additional response items.

---

SceneCollectionChanged

• Added in v4.0.0

Triggered when switching to another scene collection or when renaming the current scene collection.

Response Items:

No additional response items.

---

SceneCollectionListChanged

• Added in v4.0.0

Triggered when a scene collection is created, added, renamed, or removed.

Response Items:

No additional response items.

---

Transitions

SwitchTransition

• Added in v4.0.0

The active transition has been changed.

Response Items:

Name	Type	Description
transition-name	String	The name of the new active transition.

---

TransitionListChanged

• Added in v4.0.0

The list of available transitions has been modified. Transitions have been added, removed, or renamed.

Response Items:

No additional response items.

---

TransitionDurationChanged

• Added in v4.0.0

The active transition duration has been changed.

Response Items:

Name	Type	Description
new-duration	int	New transition duration.

---

TransitionBegin

• Added in v4.0.0

A transition (other than "cut") has begun.

Response Items:

Name	Type	Description
name	String	Transition name.
type	String	Transition type.
duration	int	Transition duration (in milliseconds). Will be -1 for any transition with a fixed duration, such as a Stinger, due to limitations of the OBS API.
from-scene	String	Source scene of the transition
to-scene	String	Destination scene of the transition

---

TransitionEnd

• Added in v4.8.0

A transition (other than "cut") has ended. Please note that the from-scene field is not available in TransitionEnd.

Response Items:

Name	Type	Description
name	String	Transition name.
type	String	Transition type.
duration	int	Transition duration (in milliseconds).
to-scene	String	Destination scene of the transition

---

TransitionVideoEnd

• Added in v4.8.0

A stinger transition has finished playing its video.

Response Items:

Name	Type	Description
name	String	Transition name.
type	String	Transition type.
duration	int	Transition duration (in milliseconds).
from-scene	String	Source scene of the transition
to-scene	String	Destination scene of the transition

---

Profiles

ProfileChanged

• Added in v4.0.0

Triggered when switching to another profile or when renaming the current profile.

Response Items:

No additional response items.

---

ProfileListChanged

• Added in v4.0.0

Triggered when a profile is created, added, renamed, or removed.

Response Items:

No additional response items.

---

Streaming

StreamStarting

• Added in v0.3

A request to start streaming has been issued.

Response Items:

Name	Type	Description
preview-only	boolean	Always false (retrocompatibility).

---

StreamStarted

• Added in v0.3

Streaming started successfully.

Response Items:

No additional response items.

---

StreamStopping

• Added in v0.3

A request to stop streaming has been issued.

Response Items:

Name	Type	Description
preview-only	boolean	Always false (retrocompatibility).

---

StreamStopped

• Added in v0.3

Streaming stopped successfully.

Response Items:

No additional response items.

---

StreamStatus

• Added in v0.3

Emit every 2 seconds.

Response Items:

Name	Type	Description
streaming	boolean	Current streaming state.
recording	boolean	Current recording state.
replay-buffer-active	boolean	Replay Buffer status
bytes-per-sec	int	Amount of data per second (in bytes) transmitted by the stream encoder.
kbits-per-sec	int	Amount of data per second (in kilobits) transmitted by the stream encoder.
strain	double	Percentage of dropped frames.
total-stream-time	int	Total time (in seconds) since the stream started.
num-total-frames	int	Total number of frames transmitted since the stream started.
num-dropped-frames	int	Number of frames dropped by the encoder since the stream started.
fps	double	Current framerate.
render-total-frames	int	Number of frames rendered
render-missed-frames	int	Number of frames missed due to rendering lag
output-total-frames	int	Number of frames outputted
output-skipped-frames	int	Number of frames skipped due to encoding lag
average-frame-time	double	Average frame time (in milliseconds)
cpu-usage	double	Current CPU usage (percentage)
memory-usage	double	Current RAM usage (in megabytes)
free-disk-space	double	Free recording disk space (in megabytes)
preview-only	boolean	Always false (retrocompatibility).

---

Recording

RecordingStarting

• Added in v0.3

A request to start recording has been issued.

Response Items:

No additional response items.

---

RecordingStarted

• Added in v0.3

Recording started successfully.

Response Items:

No additional response items.

---

RecordingStopping

• Added in v0.3

A request to stop recording has been issued.

Response Items:

No additional response items.

---

RecordingStopped

• Added in v0.3

Recording stopped successfully.

Response Items:

No additional response items.

---

RecordingPaused

• Added in v4.7.0

Current recording paused

Response Items:

No additional response items.

---

RecordingResumed

• Added in v4.7.0

Current recording resumed

Response Items:

No additional response items.

---

Replay Buffer

ReplayStarting

• Added in v4.2.0

A request to start the replay buffer has been issued.

Response Items:

No additional response items.

---

ReplayStarted

• Added in v4.2.0

Replay Buffer started successfully

Response Items:

No additional response items.

---

ReplayStopping

• Added in v4.2.0

A request to stop the replay buffer has been issued.

Response Items:

No additional response items.

---

ReplayStopped

• Added in v4.2.0

Replay Buffer stopped successfully

Response Items:

No additional response items.

---

Other

Exiting

• Added in v0.3

OBS is exiting.

Response Items:

No additional response items.

---

General

Heartbeat

• Added in v

Emitted every 2 seconds after enabling it by calling SetHeartbeat.

Response Items:

Name	Type	Description
pulse	boolean	Toggles between every JSON message as an "I am alive" indicator.
current-profile	string (optional)	Current active profile.
current-scene	string (optional)	Current active scene.
streaming	boolean (optional)	Current streaming state.
total-stream-time	int (optional)	Total time (in seconds) since the stream started.
total-stream-bytes	int (optional)	Total bytes sent since the stream started.
total-stream-frames	int (optional)	Total frames streamed since the stream started.
recording	boolean (optional)	Current recording state.
total-record-time	int (optional)	Total time (in seconds) since recording started.
total-record-bytes	int (optional)	Total bytes recorded since the recording started.
total-record-frames	int (optional)	Total frames recorded since the recording started.
stats	OBSStats	OBS Stats

---

BroadcastCustomMessage

• Added in v4.7.0

A custom broadcast message was received

Response Items:

Name	Type	Description
realm	String	Identifier provided by the sender
data	Object	User-defined data

---

Sources

SourceCreated

• Added in v4.6.0

A source has been created. A source can be an input, a scene or a transition.

Response Items:

Name	Type	Description
sourceName	String	Source name
sourceType	String	Source type. Can be "input", "scene", "transition" or "filter".
sourceKind	String	Source kind.
sourceSettings	Object	Source settings

---

SourceDestroyed

• Added in v4.6.0

A source has been destroyed/removed. A source can be an input, a scene or a transition.

Response Items:

Name	Type	Description
sourceName	String	Source name
sourceType	String	Source type. Can be "input", "scene", "transition" or "filter".
sourceKind	String	Source kind.

---

SourceVolumeChanged

• Added in v4.6.0

The volume of a source has changed.

Response Items:

Name	Type	Description
sourceName	String	Source name
volume	float	Source volume

---

SourceMuteStateChanged

• Added in v4.6.0

A source has been muted or unmuted.

Response Items:

Name	Type	Description
sourceName	String	Source name
muted	boolean	Mute status of the source

---

SourceAudioSyncOffsetChanged

• Added in v4.6.0

The audio sync offset of a source has changed.

Response Items:

Name	Type	Description
sourceName	String	Source name
syncOffset	int	Audio sync offset of the source (in nanoseconds)

---

SourceAudioMixersChanged

• Added in v4.6.0

Audio mixer routing changed on a source.

Response Items:

Name	Type	Description
sourceName	String	Source name
mixers	Array<Object>	Routing status of the source for each audio mixer (array of 6 values)
mixers.*.id	int	Mixer number
mixers.*.enabled	boolean	Routing status
hexMixersValue	String	Raw mixer flags (little-endian, one bit per mixer) as an hexadecimal value

---

SourceRenamed

• Added in v4.6.0

A source has been renamed.

Response Items:

Name	Type	Description
previousName	String	Previous source name
newName	String	New source name
sourceType	String	Type of source (input, scene, filter, transition)

---

SourceFilterAdded

• Added in v4.6.0

A filter was added to a source.

Response Items:

Name	Type	Description
sourceName	String	Source name
filterName	String	Filter name
filterType	String	Filter type
filterSettings	Object	Filter settings

---

SourceFilterRemoved

• Added in v4.6.0

A filter was removed from a source.

Response Items:

Name	Type	Description
sourceName	String	Source name
filterName	String	Filter name
filterType	String	Filter type

---

SourceFilterVisibilityChanged

• Added in v4.7.0

The visibility/enabled state of a filter changed

Response Items:

Name	Type	Description
sourceName	String	Source name
filterName	String	Filter name
filterEnabled	Boolean	New filter state

---

SourceFiltersReordered

• Added in v4.6.0

Filters in a source have been reordered.

Response Items:

Name	Type	Description
sourceName	String	Source name
filters	Array<Object>	Ordered Filters list
filters.*.name	String	Filter name
filters.*.type	String	Filter type

---

Scene Items

SourceOrderChanged

• Added in v4.0.0

Scene items have been reordered.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene where items have been reordered.
scene-items	Array<Object>	Ordered list of scene items
scene-items.*.source-name	String	Item source name
scene-items.*.item-id	int	Scene item unique ID

---

SceneItemAdded

• Added in v4.0.0

An item has been added to the current scene.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item added to the scene.
item-id	int	Scene item ID

---

SceneItemRemoved

• Added in v4.0.0

An item has been removed from the current scene.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item removed from the scene.
item-id	int	Scene item ID

---

SceneItemVisibilityChanged

• Added in v4.0.0

An item's visibility has been toggled.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item in the scene.
item-id	int	Scene item ID
item-visible	boolean	New visibility state of the item.

---

SceneItemLockChanged

• Added in v4.8.0

An item's locked status has been toggled.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item in the scene.
item-id	int	Scene item ID
item-locked	boolean	New locked state of the item.

---

SceneItemTransformChanged

• Added in v4.6.0

An item's transform has been changed.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item in the scene.
item-id	int	Scene item ID
transform	SceneItemTransform	Scene item transform properties

---

SceneItemSelected

• Added in v4.6.0

A scene item is selected.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item in the scene.
item-id	int	Name of the item in the scene.

---

SceneItemDeselected

• Added in v4.6.0

A scene item is deselected.

Response Items:

Name	Type	Description
scene-name	String	Name of the scene.
item-name	String	Name of the item in the scene.
item-id	int	Name of the item in the scene.

---

Studio Mode

PreviewSceneChanged

• Added in v4.1.0

The selected preview scene has changed (only available in Studio Mode).

Response Items:

Name	Type	Description
scene-name	String	Name of the scene being previewed.
sources	Array<SceneItem>	List of sources composing the scene. Same specification as GetCurrentScene.

---

StudioModeSwitched

• Added in v4.1.0

Studio Mode has been enabled or disabled.

Response Items:

Name	Type	Description
new-state	boolean	The new enabled state of Studio Mode.

---

Requests

Requests are sent by the client and require at least the following two fields:

• request-type String: String name of the request type.
• message-id String: Client defined identifier for the message, will be echoed in the response.

Once a request is sent, the server will return a JSON response with at least the following fields:

• message-id String: The client defined identifier specified in the request.
• status String: Response status, will be one of the following: ok, error
• error String: An error message accompanying an error status.

Additional information may be required/returned depending on the request type. See below for more information.

General

GetVersion

• Added in v0.3

Returns the latest version of the plugin and the API.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
version	double	OBSRemote compatible API version. Fixed to 1.1 for retrocompatibility.
obs-websocket-version	String	obs-websocket plugin version.
obs-studio-version	String	OBS Studio program version.
available-requests	String	List of available request types, formatted as a comma-separated list string (e.g. : "Method1,Method2,Method3").
supported-image-export-formats	String	List of supported formats for features that use image export (like the TakeSourceScreenshot request type) formatted as a comma-separated list string

---

GetAuthRequired

• Added in v0.3

Tells the client if authentication is required. If so, returns authentication parameters challenge and salt (see "Authentication" for more information).

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
authRequired	boolean	Indicates whether authentication is required.
challenge	String (optional)
salt	String (optional)

---

Authenticate

• Added in v0.3

Attempt to authenticate the client to the server.

Request Fields:

Name	Type	Description
auth	String	Response to the auth challenge (see "Authentication" for more information).

Response Items:

No additional response items.

---

SetHeartbeat

• Added in v4.3.0

Enable/disable sending of the Heartbeat event

Request Fields:

Name	Type	Description
enable	boolean	Starts/Stops emitting heartbeat messages

Response Items:

No additional response items.

---

SetFilenameFormatting

• Added in v4.3.0

Set the filename formatting string

Request Fields:

Name	Type	Description
filename-formatting	String	Filename formatting string to set.

Response Items:

No additional response items.

---

GetFilenameFormatting

• Added in v4.3.0

Get the filename formatting string

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
filename-formatting	String	Current filename formatting string.

---

GetStats

• Added in v4.6.0

Get OBS stats (almost the same info as provided in OBS' stats window)

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
stats	OBSStats	OBS stats

---

BroadcastCustomMessage

• Added in v4.7.0

Broadcast custom message to all connected WebSocket clients

Request Fields:

Name	Type	Description
realm	String	Identifier to be choosen by the client
data	Object	User-defined data

Response Items:

No additional response items.

---

GetVideoInfo

• Added in v4.6.0

Get basic OBS video information

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
baseWidth	int	Base (canvas) width
baseHeight	int	Base (canvas) height
outputWidth	int	Output width
outputHeight	int	Output height
scaleType	String	Scaling method used if output size differs from base size
fps	double	Frames rendered per second
videoFormat	String	Video color format
colorSpace	String	Color space for YUV
colorRange	String	Color range (full or partial)

---

OpenProjector

• Added in v4.8.0

Open a projector window or create a projector on a monitor. Requires OBS v24.0.4 or newer.

Request Fields:

Name	Type	Description
type	String (Optional)	Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive).
monitor	int (Optional)	Monitor to open the projector on. If -1 or omitted, opens a window.
geometry	String (Optional)	Size and position of the projector window (only if monitor is -1). Encoded in Base64 using Qt's geometry encoding (https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors.
name	String (Optional)	Name of the source or scene to be displayed (ignored for other projector types).

Response Items:

No additional response items.

---

Outputs

ListOutputs

• Added in v4.7.0

List existing outputs

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
outputs	Array<Output>	Outputs list

---

GetOutputInfo

• Added in v4.7.0

Get information about a single output

Request Fields:

Name	Type	Description
outputName	String	Output name

Response Items:

Name	Type	Description
outputInfo	Output	Output info

---

StartOutput

• Added in v4.7.0

Start an output

Request Fields:

Name	Type	Description
outputName	String	Output name

Response Items:

No additional response items.

---

StopOutput

• Added in v4.7.0

Stop an output

Request Fields:

Name	Type	Description
outputName	String	Output name
force	boolean (optional)	Force stop (default: false)

Response Items:

No additional response items.

---

Profiles

SetCurrentProfile

• Added in v4.0.0

Set the currently active profile.

Request Fields:

Name	Type	Description
profile-name	String	Name of the desired profile.

Response Items:

No additional response items.

---

GetCurrentProfile

• Added in v4.0.0

Get the name of the current profile.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
profile-name	String	Name of the currently active profile.

---

ListProfiles

• Added in v4.0.0

Get a list of available profiles.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
profiles	Array<Object>	List of available profiles.

---

Recording

StartStopRecording

• Added in v0.3

Toggle recording on or off.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

StartRecording

• Added in v4.1.0

Start recording. Will return an error if recording is already active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

StopRecording

• Added in v4.1.0

Stop recording. Will return an error if recording is not active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

PauseRecording

• Added in v4.7.0

Pause the current recording. Returns an error if recording is not active or already paused.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

ResumeRecording

• Added in v4.7.0

Resume/unpause the current recording (if paused). Returns an error if recording is not active or not paused.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

SetRecordingFolder

• Added in v4.1.0

Please note: if SetRecordingFolder is called while a recording is in progress, the change won't be applied immediately and will be effective on the next recording.

Request Fields:

Name	Type	Description
rec-folder	String	Path of the recording folder.

Response Items:

No additional response items.

---

GetRecordingFolder

• Added in v4.1.0

Get the path of the current recording folder.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
rec-folder	String	Path of the recording folder.

---

Replay Buffer

StartStopReplayBuffer

• Added in v4.2.0

Toggle the Replay Buffer on/off.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

StartReplayBuffer

• Added in v4.2.0

Start recording into the Replay Buffer. Will return an error if the Replay Buffer is already active or if the "Save Replay Buffer" hotkey is not set in OBS' settings. Setting this hotkey is mandatory, even when triggering saves only through obs-websocket.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

StopReplayBuffer

• Added in v4.2.0

Stop recording into the Replay Buffer. Will return an error if the Replay Buffer is not active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

SaveReplayBuffer

• Added in v4.2.0

Flush and save the contents of the Replay Buffer to disk. This is basically the same as triggering the "Save Replay Buffer" hotkey. Will return an error if the Replay Buffer is not active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

Scene Collections

SetCurrentSceneCollection

• Added in v4.0.0

Change the active scene collection.

Request Fields:

Name	Type	Description
sc-name	String	Name of the desired scene collection.

Response Items:

No additional response items.

---

GetCurrentSceneCollection

• Added in v4.0.0

Get the name of the current scene collection.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
sc-name	String	Name of the currently active scene collection.

---

ListSceneCollections

• Added in v4.0.0

List available scene collections

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
scene-collections	Array<String>	Scene collections list

---

Scene Items

GetSceneItemProperties

• Added in v4.3.0

Gets the scene specific properties of the specified source item. Coordinates are relative to the item's parent (the scene or group it belongs to).

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the scene item belongs to. Defaults to the current scene.
item	String | Object	Scene Item name (if this field is a string) or specification (if it is an object).
item.name	String (optional)	Scene Item name (if the item field is an object)
item.id	int (optional)	Scene Item ID (if the item field is an object)

Response Items:

Name	Type	Description
name	String	Scene Item name.
itemId	int	Scene Item ID.
position.x	int	The x position of the source from the left.
position.y	int	The y position of the source from the top.
position.alignment	int	The point on the source that the item is manipulated from.
rotation	double	The clockwise rotation of the item in degrees around the point of alignment.
scale.x	double	The x-scale factor of the source.
scale.y	double	The y-scale factor of the source.
crop.top	int	The number of pixels cropped off the top of the source before scaling.
crop.right	int	The number of pixels cropped off the right of the source before scaling.
crop.bottom	int	The number of pixels cropped off the bottom of the source before scaling.
crop.left	int	The number of pixels cropped off the left of the source before scaling.
visible	bool	If the source is visible.
muted	bool	If the source is muted.
locked	bool	If the source's transform is locked.
bounds.type	String	Type of bounding box. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE".
bounds.alignment	int	Alignment of the bounding box.
bounds.x	double	Width of the bounding box.
bounds.y	double	Height of the bounding box.
sourceWidth	int	Base width (without scaling) of the source
sourceHeight	int	Base source (without scaling) of the source
width	double	Scene item width (base source width multiplied by the horizontal scaling factor)
height	double	Scene item height (base source height multiplied by the vertical scaling factor)
alignment	int	The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis.
parentGroupName	String (optional)	Name of the item's parent (if this item belongs to a group)
groupChildren	Array<SceneItemTransform> (optional)	List of children (if this item is a group)

---

SetSceneItemProperties

• Added in v4.3.0

Sets the scene specific properties of a source. Unspecified properties will remain unchanged. Coordinates are relative to the item's parent (the scene or group it belongs to).

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the source item belongs to. Defaults to the current scene.
item	String | Object	Scene Item name (if this field is a string) or specification (if it is an object).
item.name	String (optional)	Scene Item name (if the item field is an object)
item.id	int (optional)	Scene Item ID (if the item field is an object)
position.x	int (optional)	The new x position of the source.
position.y	int (optional)	The new y position of the source.
position.alignment	int (optional)	The new alignment of the source.
rotation	double (optional)	The new clockwise rotation of the item in degrees.
scale.x	double (optional)	The new x scale of the item.
scale.y	double (optional)	The new y scale of the item.
crop.top	int (optional)	The new amount of pixels cropped off the top of the source before scaling.
crop.bottom	int (optional)	The new amount of pixels cropped off the bottom of the source before scaling.
crop.left	int (optional)	The new amount of pixels cropped off the left of the source before scaling.
crop.right	int (optional)	The new amount of pixels cropped off the right of the source before scaling.
visible	bool (optional)	The new visibility of the source. 'true' shows source, 'false' hides source.
locked	bool (optional)	The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement.
bounds.type	String (optional)	The new bounds type of the source. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE".
bounds.alignment	int (optional)	The new alignment of the bounding box. (0-2, 4-6, 8-10)
bounds.x	double (optional)	The new width of the bounding box.
bounds.y	double (optional)	The new height of the bounding box.

Response Items:

No additional response items.

---

ResetSceneItem

• Added in v4.2.0

Reset a scene item.

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the scene item belongs to. Defaults to the current scene.
item	String | Object	Scene Item name (if this field is a string) or specification (if it is an object).
item.name	String (optional)	Scene Item name (if the item field is an object)
item.id	int (optional)	Scene Item ID (if the item field is an object)

Response Items:

No additional response items.

---

SetSceneItemRender

• ⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️

• Added in v0.3

Show or hide a specified source item in a specified scene.

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the scene item belongs to. Defaults to the currently active scene.
source	String	Scene Item name.
render	boolean	true = shown ; false = hidden

Response Items:

No additional response items.

---

SetSceneItemPosition

• ⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️

• Added in v4.0.0

Sets the coordinates of a specified source item.

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the scene item belongs to. Defaults to the current scene.
item	String	Scene Item name.
x	double	X coordinate.
y	double	Y coordinate.

Response Items:

No additional response items.

---

SetSceneItemTransform

• ⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️

• Added in v4.0.0

Set the transform of the specified source item.

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the scene item belongs to. Defaults to the current scene.
item	String	Scene Item name.
x-scale	double	Width scale factor.
y-scale	double	Height scale factor.
rotation	double	Source item rotation (in degrees).

Response Items:

No additional response items.

---

SetSceneItemCrop

• ⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️

• Added in v4.1.0

Sets the crop coordinates of the specified source item.

Request Fields:

Name	Type	Description
scene-name	String (optional)	Name of the scene the scene item belongs to. Defaults to the current scene.
item	String	Scene Item name.
top	int	Pixel position of the top of the source item.
bottom	int	Pixel position of the bottom of the source item.
left	int	Pixel position of the left of the source item.
right	int	Pixel position of the right of the source item.

Response Items:

No additional response items.

---

DeleteSceneItem

• Added in v4.5.0

Deletes a scene item.

Request Fields:

Name	Type	Description
scene	String (optional)	Name of the scene the scene item belongs to. Defaults to the current scene.
item	Object	Scene item to delete (required)
item.name	String	Scene Item name (prefer id, including both is acceptable).
item.id	int	Scene Item ID.

Response Items:

No additional response items.

---

DuplicateSceneItem

• Added in v4.5.0

Duplicates a scene item.

Request Fields:

Name	Type	Description
fromScene	String (optional)	Name of the scene to copy the item from. Defaults to the current scene.
toScene	String (optional)	Name of the scene to create the item in. Defaults to the current scene.
item	Object	Scene Item to duplicate from the source scene (required)
item.name	String	Scene Item name (prefer id, including both is acceptable).
item.id	int	Scene Item ID.

Response Items:

Name	Type	Description
scene	String	Name of the scene where the new item was created
item	Object	New item info
item.id	int	New item ID
item.name	String	New item name

---

Scenes

SetCurrentScene

• Added in v0.3

Switch to the specified scene.

Request Fields:

Name	Type	Description
scene-name	String	Name of the scene to switch to.

Response Items:

No additional response items.

---

GetCurrentScene

• Added in v0.3

Get the current scene's name and source items.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
name	String	Name of the currently active scene.
sources	Array<SceneItem>	Ordered list of the current scene's source items.

---

GetSceneList

• Added in v0.3

Get a list of scenes in the currently active profile.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
current-scene	String	Name of the currently active scene.
scenes	Array<Scene>	Ordered list of the current profile's scenes (See GetCurrentScene for more information).

---

ReorderSceneItems

• Added in v4.5.0

Changes the order of scene items in the requested scene.

Request Fields:

Name	Type	Description
scene	String (optional)	Name of the scene to reorder (defaults to current).
items	Array<Scene>	Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene
items[].id	int (optional)	Id of a specific scene item. Unique on a scene by scene basis.
items[].name	String (optional)	Name of a scene item. Sufficiently unique if no scene items share sources within the scene.

Response Items:

No additional response items.

---

SetSceneTransitionOverride

• Added in v4.9.0

Set a scene to use a specific transition override.

Request Fields:

Name	Type	Description
sceneName	String	Name of the scene to switch to.
transitionName	String	Name of the transition to use.
transitionDuration	int (Optional)	Duration in milliseconds of the transition if transition is not fixed. Defaults to the current duration specified in the UI if there is no current override and this value is not given.

Response Items:

No additional response items.

---

RemoveSceneTransitionOverride

• Added in v4.9.0

Remove any transition override on a scene.

Request Fields:

Name	Type	Description
sceneName	String	Name of the scene to switch to.

Response Items:

No additional response items.

---

GetSceneTransitionOverride

• Added in v4.9.0

Get the current scene transition override.

Request Fields:

Name	Type	Description
sceneName	String	Name of the scene to switch to.

Response Items:

Name	Type	Description
transitionName	String	Name of the current overriding transition. Empty string if no override is set.
transitionDuration	int	Transition duration. -1 if no override is set.

---

Sources

GetSourcesList

• Added in v4.3.0

List all sources available in the running OBS instance

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
sources	Array<Object>	Array of sources
sources.*.name	String	Unique source name
sources.*.typeId	String	Non-unique source internal type (a.k.a type id)
sources.*.type	String	Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"

---

GetSourceTypesList

• Added in v4.3.0

Get a list of all available sources types

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
types	Array<Object>	Array of source types
types.*.typeId	String	Non-unique internal source type ID
types.*.displayName	String	Display name of the source type
types.*.type	String	Type. Value is one of the following: "input", "filter", "transition" or "other"
types.*.defaultSettings	Object	Default settings of this source type
types.*.caps	Object	Source type capabilities
types.*.caps.isAsync	Boolean	True if source of this type provide frames asynchronously
types.*.caps.hasVideo	Boolean	True if sources of this type provide video
types.*.caps.hasAudio	Boolean	True if sources of this type provide audio
types.*.caps.canInteract	Boolean	True if interaction with this sources of this type is possible
types.*.caps.isComposite	Boolean	True if sources of this type composite one or more sub-sources
types.*.caps.doNotDuplicate	Boolean	True if sources of this type should not be fully duplicated
types.*.caps.doNotSelfMonitor	Boolean	True if sources of this type may cause a feedback loop if it's audio is monitored and shouldn't be

---

GetVolume

• Added in v4.0.0

Get the volume of the specified source. Default response uses mul format, NOT SLIDER PERCENTAGE.

Request Fields:

Name	Type	Description
source	String	Source name.
useDecibel	boolean (optional)	Output volume in decibels of attenuation instead of amplitude/mul.

Response Items:

Name	Type	Description
name	String	Source name.
volume	double	Volume of the source. Between 0.0 and 1.0 if using mul, under 0.0 if using dB (since it is attenuating).
muted	boolean	Indicates whether the source is muted.

---

SetVolume

• Added in v4.0.0

Set the volume of the specified source. Default request format uses mul, NOT SLIDER PERCENTAGE.

Request Fields:

Name	Type	Description
source	String	Source name.
volume	double	Desired volume. Must be between 0.0 and 1.0 for mul, and under 0.0 for dB. Note: OBS will interpret dB values under -100.0 as Inf.
useDecibel	boolean (optional)	Interperet volume data as decibels instead of amplitude/mul.

Response Items:

No additional response items.

---

GetMute

• Added in v4.0.0

Get the mute status of a specified source.

Request Fields:

Name	Type	Description
source	String	Source name.

Response Items:

Name	Type	Description
name	String	Source name.
muted	boolean	Mute status of the source.

---

SetMute

• Added in v4.0.0

Sets the mute status of a specified source.

Request Fields:

Name	Type	Description
source	String	Source name.
mute	boolean	Desired mute status.

Response Items:

No additional response items.

---

ToggleMute

• Added in v4.0.0

Inverts the mute status of a specified source.

Request Fields:

Name	Type	Description
source	String	Source name.

Response Items:

No additional response items.

---

SetSourceName

• Added in v4.8.0

Note: If the new name already exists as a source, OBS will automatically modify the name to not interfere.

Request Fields:

Name	Type	Description
sourceName	String	Source name.
newName	String	New source name.

Response Items:

No additional response items.

---

SetSyncOffset

• Added in v4.2.0

Set the audio sync offset of a specified source.

Request Fields:

Name	Type	Description
source	String	Source name.
offset	int	The desired audio sync offset (in nanoseconds).

Response Items:

No additional response items.

---

GetSyncOffset

• Added in v4.2.0

Get the audio sync offset of a specified source.

Request Fields:

Name	Type	Description
source	String	Source name.

Response Items:

Name	Type	Description
name	String	Source name.
offset	int	The audio sync offset (in nanoseconds).

---

GetSourceSettings

• Added in v4.3.0

Get settings of the specified source

Request Fields:

Name	Type	Description
sourceName	String	Source name.
sourceType	String (optional)	Type of the specified source. Useful for type-checking if you expect a specific settings schema.

Response Items:

Name	Type	Description
sourceName	String	Source name
sourceType	String	Type of the specified source
sourceSettings	Object	Source settings (varies between source types, may require some probing around).

---

SetSourceSettings

• Added in v4.3.0

Set settings of the specified source.

Request Fields:

Name	Type	Description
sourceName	String	Source name.
sourceType	String (optional)	Type of the specified source. Useful for type-checking to avoid settings a set of settings incompatible with the actual source's type.
sourceSettings	Object	Source settings (varies between source types, may require some probing around).

Response Items:

Name	Type	Description
sourceName	String	Source name
sourceType	String	Type of the specified source
sourceSettings	Object	Updated source settings

---

GetTextGDIPlusProperties

• Added in v4.1.0

Get the current properties of a Text GDI Plus source.

Request Fields:

Name	Type	Description
source	String	Source name.

Response Items:

Name	Type	Description
source	String	Source name.
align	String	Text Alignment ("left", "center", "right").
bk-color	int	Background color.
bk-opacity	int	Background opacity (0-100).
chatlog	boolean	Chat log.
chatlog_lines	int	Chat log lines.
color	int	Text color.
extents	boolean	Extents wrap.
extents_cx	int	Extents cx.
extents_cy	int	Extents cy.
file	String	File path name.
read_from_file	boolean	Read text from the specified file.
font	Object	Holds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.face	String	Font face.
font.flags	int	Font text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.size	int	Font text size.
font.style	String	Font Style (unknown function).
gradient	boolean	Gradient enabled.
gradient_color	int	Gradient color.
gradient_dir	float	Gradient direction.
gradient_opacity	int	Gradient opacity (0-100).
outline	boolean	Outline.
outline_color	int	Outline color.
outline_size	int	Outline size.
outline_opacity	int	Outline opacity (0-100).
text	String	Text content to be displayed.
valign	String	Text vertical alignment ("top", "center", "bottom").
vertical	boolean	Vertical text enabled.

---

SetTextGDIPlusProperties

• Added in v4.1.0

Set the current properties of a Text GDI Plus source.

Request Fields:

Name	Type	Description
source	String	Name of the source.
align	String (optional)	Text Alignment ("left", "center", "right").
bk-color	int (optional)	Background color.
bk-opacity	int (optional)	Background opacity (0-100).
chatlog	boolean (optional)	Chat log.
chatlog_lines	int (optional)	Chat log lines.
color	int (optional)	Text color.
extents	boolean (optional)	Extents wrap.
extents_cx	int (optional)	Extents cx.
extents_cy	int (optional)	Extents cy.
file	String (optional)	File path name.
read_from_file	boolean (optional)	Read text from the specified file.
font	Object (optional)	Holds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.face	String (optional)	Font face.
font.flags	int (optional)	Font text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.size	int (optional)	Font text size.
font.style	String (optional)	Font Style (unknown function).
gradient	boolean (optional)	Gradient enabled.
gradient_color	int (optional)	Gradient color.
gradient_dir	float (optional)	Gradient direction.
gradient_opacity	int (optional)	Gradient opacity (0-100).
outline	boolean (optional)	Outline.
outline_color	int (optional)	Outline color.
outline_size	int (optional)	Outline size.
outline_opacity	int (optional)	Outline opacity (0-100).
text	String (optional)	Text content to be displayed.
valign	String (optional)	Text vertical alignment ("top", "center", "bottom").
vertical	boolean (optional)	Vertical text enabled.
render	boolean (optional)	Visibility of the scene item.

Response Items:

No additional response items.

---

GetTextFreetype2Properties

• Added in v4.5.0

Get the current properties of a Text Freetype 2 source.

Request Fields:

Name	Type	Description
source	String	Source name.

Response Items:

Name	Type	Description
source	String	Source name
color1	int	Gradient top color.
color2	int	Gradient bottom color.
custom_width	int	Custom width (0 to disable).
drop_shadow	boolean	Drop shadow.
font	Object	Holds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.face	String	Font face.
font.flags	int	Font text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.size	int	Font text size.
font.style	String	Font Style (unknown function).
from_file	boolean	Read text from the specified file.
log_mode	boolean	Chat log.
outline	boolean	Outline.
text	String	Text content to be displayed.
text_file	String	File path.
word_wrap	boolean	Word wrap.

---

SetTextFreetype2Properties

• Added in v4.5.0

Set the current properties of a Text Freetype 2 source.

Request Fields:

Name	Type	Description
source	String	Source name.
color1	int (optional)	Gradient top color.
color2	int (optional)	Gradient bottom color.
custom_width	int (optional)	Custom width (0 to disable).
drop_shadow	boolean (optional)	Drop shadow.
font	Object (optional)	Holds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.face	String (optional)	Font face.
font.flags	int (optional)	Font text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.size	int (optional)	Font text size.
font.style	String (optional)	Font Style (unknown function).
from_file	boolean (optional)	Read text from the specified file.
log_mode	boolean (optional)	Chat log.
outline	boolean (optional)	Outline.
text	String (optional)	Text content to be displayed.
text_file	String (optional)	File path.
word_wrap	boolean (optional)	Word wrap.

Response Items:

No additional response items.

---

GetBrowserSourceProperties

• ⚠️ Deprecated. Since 4.8.0. Prefer the use of GetSourceSettings. ⚠️

• Added in v4.1.0

Get current properties for a Browser Source.

Request Fields:

Name	Type	Description
source	String	Source name.

Response Items:

Name	Type	Description
source	String	Source name.
is_local_file	boolean	Indicates that a local file is in use.
local_file	String	file path.
url	String	Url.
css	String	CSS to inject.
width	int	Width.
height	int	Height.
fps	int	Framerate.
shutdown	boolean	Indicates whether the source should be shutdown when not visible.

---

SetBrowserSourceProperties

• ⚠️ Deprecated. Since 4.8.0. Prefer the use of SetSourceSettings. ⚠️

• Added in v4.1.0

Set current properties for a Browser Source.

Request Fields:

Name	Type	Description
source	String	Name of the source.
is_local_file	boolean (optional)	Indicates that a local file is in use.
local_file	String (optional)	file path.
url	String (optional)	Url.
css	String (optional)	CSS to inject.
width	int (optional)	Width.
height	int (optional)	Height.
fps	int (optional)	Framerate.
shutdown	boolean (optional)	Indicates whether the source should be shutdown when not visible.
render	boolean (optional)	Visibility of the scene item.

Response Items:

No additional response items.

---

GetSpecialSources

• Added in v4.1.0

Get configured special sources like Desktop Audio and Mic/Aux sources.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
desktop-1	String (optional)	Name of the first Desktop Audio capture source.
desktop-2	String (optional)	Name of the second Desktop Audio capture source.
mic-1	String (optional)	Name of the first Mic/Aux input source.
mic-2	String (optional)	Name of the second Mic/Aux input source.
mic-3	String (optional)	NAme of the third Mic/Aux input source.

---

GetSourceFilters

• Added in v4.5.0

List filters applied to a source

Request Fields:

Name	Type	Description
sourceName	String	Source name

Response Items:

Name	Type	Description
filters	Array<Object>	List of filters for the specified source
filters.*.enabled	Boolean	Filter status (enabled or not)
filters.*.type	String	Filter type
filters.*.name	String	Filter name
filters.*.settings	Object	Filter settings

---

GetSourceFilterInfo

• Added in v4.7.0

List filters applied to a source

Request Fields:

Name	Type	Description
sourceName	String	Source name
filterName	String	Source filter name

Response Items:

Name	Type	Description
enabled	Boolean	Filter status (enabled or not)
type	String	Filter type
name	String	Filter name
settings	Object	Filter settings

---

AddFilterToSource

• Added in v4.5.0

Add a new filter to a source. Available source types along with their settings properties are available from GetSourceTypesList.

Request Fields:

Name	Type	Description
sourceName	String	Name of the source on which the filter is added
filterName	String	Name of the new filter
filterType	String	Filter type
filterSettings	Object	Filter settings

Response Items:

No additional response items.

---

RemoveFilterFromSource

• Added in v4.5.0

Remove a filter from a source

Request Fields:

Name	Type	Description
sourceName	String	Name of the source from which the specified filter is removed
filterName	String	Name of the filter to remove

Response Items:

No additional response items.

---

ReorderSourceFilter

• Added in v4.5.0

Move a filter in the chain (absolute index positioning)

Request Fields:

Name	Type	Description
sourceName	String	Name of the source to which the filter belongs
filterName	String	Name of the filter to reorder
newIndex	Integer	Desired position of the filter in the chain

Response Items:

No additional response items.

---

MoveSourceFilter

• Added in v4.5.0

Move a filter in the chain (relative positioning)

Request Fields:

Name	Type	Description
sourceName	String	Name of the source to which the filter belongs
filterName	String	Name of the filter to reorder
movementType	String	How to move the filter around in the source's filter chain. Either "up", "down", "top" or "bottom".

Response Items:

No additional response items.

---

SetSourceFilterSettings

• Added in v4.5.0

Update settings of a filter

Request Fields:

Name	Type	Description
sourceName	String	Name of the source to which the filter belongs
filterName	String	Name of the filter to reconfigure
filterSettings	Object	New settings. These will be merged to the current filter settings.

Response Items:

No additional response items.

---

SetSourceFilterVisibility

• Added in v4.7.0

Change the visibility/enabled state of a filter

Request Fields:

Name	Type	Description
sourceName	String	Source name
filterName	String	Source filter name
filterEnabled	Boolean	New filter state

Response Items:

No additional response items.

---

GetAudioMonitorType

• Added in v4.8.0

Get the audio monitoring type of the specified source.

Request Fields:

Name	Type	Description
sourceName	String	Source name.

Response Items:

Name	Type	Description
monitorType	String	The monitor type in use. Options: none, monitorOnly, monitorAndOutput.

---

SetAudioMonitorType

• Added in v4.8.0

Set the audio monitoring type of the specified source.

Request Fields:

Name	Type	Description
sourceName	String	Source name.
monitorType	String	The monitor type to use. Options: none, monitorOnly, monitorAndOutput.

Response Items:

No additional response items.

---

TakeSourceScreenshot

• Added in v4.6.0

At least embedPictureFormat or saveToFilePath must be specified.

Clients can specify width and height parameters to receive scaled pictures. Aspect ratio is preserved if only one of these two parameters is specified.

Request Fields:

Name	Type	Description
sourceName	String	Source name. Note that, since scenes are also sources, you can also provide a scene name.
embedPictureFormat	String (optional)	Format of the Data URI encoded picture. Can be "png", "jpg", "jpeg" or "bmp" (or any other value supported by Qt's Image module)
saveToFilePath	String (optional)	Full file path (file extension included) where the captured image is to be saved. Can be in a format different from pictureFormat. Can be a relative path.
fileFormat	String (optional)	Format to save the image file as (one of the values provided in the supported-image-export-formats response field of GetVersion). If not specified, tries to guess based on file extension.
compressionQuality	int (optional)	Compression ratio between -1 and 100 to write the image with. -1 is automatic, 1 is smallest file/most compression, 100 is largest file/least compression. Varies with image type.
width	int (optional)	Screenshot width. Defaults to the source's base width.
height	int (optional)	Screenshot height. Defaults to the source's base height.

Response Items:

Name	Type	Description
sourceName	String	Source name
img	String	Image Data URI (if embedPictureFormat was specified in the request)
imageFile	String	Absolute path to the saved image file (if saveToFilePath was specified in the request)

---

Streaming

GetStreamingStatus

• Added in v0.3

Get current streaming and recording status.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
streaming	boolean	Current streaming status.
recording	boolean	Current recording status.
stream-timecode	String (optional)	Time elapsed since streaming started (only present if currently streaming).
rec-timecode	String (optional)	Time elapsed since recording started (only present if currently recording).
preview-only	boolean	Always false. Retrocompatibility with OBSRemote.

---

StartStopStreaming

• Added in v0.3

Toggle streaming on or off.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

StartStreaming

• Added in v4.1.0

Start streaming. Will return an error if streaming is already active.

Request Fields:

Name	Type	Description
stream	Object (optional)	Special stream configuration. Please note: these won't be saved to OBS' configuration.
stream.type	String (optional)	If specified ensures the type of stream matches the given type (usually 'rtmp_custom' or 'rtmp_common'). If the currently configured stream type does not match the given stream type, all settings must be specified in the settings object or an error will occur when starting the stream.
stream.metadata	Object (optional)	Adds the given object parameters as encoded query string parameters to the 'key' of the RTMP stream. Used to pass data to the RTMP service about the streaming. May be any String, Numeric, or Boolean field.
stream.settings	Object (optional)	Settings for the stream.
stream.settings.server	String (optional)	The publish URL.
stream.settings.key	String (optional)	The publish key of the stream.
stream.settings.use_auth	boolean (optional)	Indicates whether authentication should be used when connecting to the streaming server.
stream.settings.username	String (optional)	If authentication is enabled, the username for the streaming server. Ignored if use_auth is not set to true.
stream.settings.password	String (optional)	If authentication is enabled, the password for the streaming server. Ignored if use_auth is not set to true.

Response Items:

No additional response items.

---

StopStreaming

• Added in v4.1.0

Stop streaming. Will return an error if streaming is not active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

SetStreamSettings

• Added in v4.1.0

Sets one or more attributes of the current streaming server settings. Any options not passed will remain unchanged. Returns the updated settings in response. If 'type' is different than the current streaming service type, all settings are required. Returns the full settings of the stream (the same as GetStreamSettings).

Request Fields:

Name	Type	Description
type	String	The type of streaming service configuration, usually rtmp_custom or rtmp_common.
settings	Object	The actual settings of the stream.
settings.server	String (optional)	The publish URL.
settings.key	String (optional)	The publish key.
settings.use_auth	boolean (optional)	Indicates whether authentication should be used when connecting to the streaming server.
settings.username	String (optional)	The username for the streaming service.
settings.password	String (optional)	The password for the streaming service.
save	boolean	Persist the settings to disk.

Response Items:

No additional response items.

---

GetStreamSettings

• Added in v4.1.0

Get the current streaming server settings.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
type	String	The type of streaming service configuration. Possible values: 'rtmp_custom' or 'rtmp_common'.
settings	Object	Stream settings object.
settings.server	String	The publish URL.
settings.key	String	The publish key of the stream.
settings.use_auth	boolean	Indicates whether authentication should be used when connecting to the streaming server.
settings.username	String	The username to use when accessing the streaming server. Only present if use_auth is true.
settings.password	String	The password to use when accessing the streaming server. Only present if use_auth is true.

---

SaveStreamSettings

• Added in v4.1.0

Save the current streaming server settings to disk.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

SendCaptions

• Added in v4.6.0

Send the provided text as embedded CEA-608 caption data. As of OBS Studio 23.1, captions are not yet available on Linux.

Request Fields:

Name	Type	Description
text	String	Captions text

Response Items:

No additional response items.

---

Studio Mode

GetStudioModeStatus

• Added in v4.1.0

Indicates if Studio Mode is currently enabled.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
studio-mode	boolean	Indicates if Studio Mode is enabled.

---

GetPreviewScene

• Added in v4.1.0

Get the name of the currently previewed scene and its list of sources. Will return an error if Studio Mode is not enabled.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
name	String	The name of the active preview scene.
sources	Array<SceneItem>

---

SetPreviewScene

• Added in v4.1.0

Set the active preview scene. Will return an error if Studio Mode is not enabled.

Request Fields:

Name	Type	Description
scene-name	String	The name of the scene to preview.

Response Items:

No additional response items.

---

TransitionToProgram

• Added in v4.1.0

Transitions the currently previewed scene to the main output. Will return an error if Studio Mode is not enabled.

Request Fields:

Name	Type	Description
with-transition	Object (optional)	Change the active transition before switching scenes. Defaults to the active transition.
with-transition.name	String	Name of the transition.
with-transition.duration	int (optional)	Transition duration (in milliseconds).

Response Items:

No additional response items.

---

EnableStudioMode

• Added in v4.1.0

Enables Studio Mode.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

DisableStudioMode

• Added in v4.1.0

Disables Studio Mode.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

ToggleStudioMode

• Added in v4.1.0

Toggles Studio Mode.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

---

Transitions

GetTransitionList

• Added in v4.1.0

List of all transitions available in the frontend's dropdown menu.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
current-transition	String	Name of the currently active transition.
transitions	Array<Object>	List of transitions.
transitions.*.name	String	Name of the transition.

---

GetCurrentTransition

• Added in v0.3

Get the name of the currently selected transition in the frontend's dropdown menu.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
name	String	Name of the selected transition.
duration	int (optional)	Transition duration (in milliseconds) if supported by the transition.

---

SetCurrentTransition

• Added in v0.3

Set the active transition.

Request Fields:

Name	Type	Description
transition-name	String	The name of the transition.

Response Items:

No additional response items.

---

SetTransitionDuration

• Added in v4.0.0

Set the duration of the currently selected transition if supported.

Request Fields:

Name	Type	Description
duration	int	Desired duration of the transition (in milliseconds).

Response Items:

No additional response items.

---

GetTransitionDuration

• Added in v4.1.0

Get the duration of the currently selected transition if supported.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
transition-duration	int	Duration of the current transition (in milliseconds).

---

GetTransitionPosition

• Added in v4.8.0

Get the position of the current transition.

Request Fields:

No specified parameters.

Response Items:

Name	Type	Description
position	double	current transition position. This value will be between 0.0 and 1.0. Note: Transition returns 1.0 when not active.

---