2021-06-29

2024-01-27 19:47:46

obs-websocket 4.9.1 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. As of v5.0.0, backwards compatability with the protocol will not be kept.

Authentication

Starting with obs-websocket 4.9, authentication is enabled by default and users are encouraged to configure a password on first run.

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)

You can also refer to any of the client libraries listed on the README for examples of how to authenticate.

Table of Contents

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 double The x position of the scene item from the left.
position.y double 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.
scale.filter String The scale filter of the source. Can be “OBS_SCALE_DISABLE”, “OBS_SCALE_POINT”, “OBS_SCALE_BICUBIC”, “OBS_SCALE_BILINEAR”, “OBS_SCALE_LANCZOS” or “OBS_SCALE_AREA”.
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 settings
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

ScenesCollection

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

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

Note: This event is not fired when the scenes are reordered.

Response Items:

Name Type Description
scenes Array<Scene> Scenes list.

SceneCollectionChanged

  • Added in v4.0.0

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

Response Items:

Name Type Description
sceneCollection String Name of the new current scene collection.

SceneCollectionListChanged

  • Added in v4.0.0

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

Response Items:

Name Type Description
sceneCollections Array<Object> Scene collections list.
sceneCollections.*.name String Scene collection name.

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:

Name Type Description
transitions Array<Object> Transitions list.
transitions.*.name String Transition name.

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 (optional) 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.
Note: 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 (optional) 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:

Name Type Description
profile String Name of the new current profile.

ProfileListChanged

  • Added in v4.0.0

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

Response Items:

Name Type Description
profiles Array<Object> Profiles list.
profiles.*.name String Profile name.

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

Emitted every 2 seconds when stream is active.

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

Note: recordingFilename is not provided in this event because this information
is not available at the time this event is emitted.

Response Items:

No additional response items.

RecordingStarted

  • Added in v0.3

Recording started successfully.

Response Items:

Name Type Description
recordingFilename String Absolute path to the file of the current recording.

RecordingStopping

  • Added in v0.3

A request to stop recording has been issued.

Response Items:

Name Type Description
recordingFilename String Absolute path to the file of the current recording.

RecordingStopped

  • Added in v0.3

Recording stopped successfully.

Response Items:

Name Type Description
recordingFilename String Absolute path to the file of the current recording.

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.

Virtual Cam

VirtualCamStarted

  • Added in v4.9.1

Virtual cam started successfully.

Response Items:

No additional response items.

VirtualCamStopped

  • Added in v4.9.1

Virtual cam stopped successfully.

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 vv0.3

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, sent by the server, requested by one of the websocket clients.

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
volumeDb float Source volume in Decibel

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

SourceAudioDeactivated

  • Added in v4.9.0

A source has removed audio.

Response Items:

Name Type Description
sourceName String Source name

SourceAudioActivated

  • Added in v4.9.0

A source has added audio.

Response Items:

Name Type Description
sourceName String Source name

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
filters.*.enabled boolean Filter visibility status

Media

MediaPlaying

  • Added in v4.9.0

Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaPaused

  • Added in v4.9.0

Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaRestarted

  • Added in v4.9.0

Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaStopped

  • Added in v4.9.0

Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaNext

  • Added in v4.9.0

Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaPrevious

  • Added in v4.9.0

Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaStarted

  • Added in v4.9.0

Note: These events are emitted by the OBS sources themselves. For example when the media file starts playing. The behavior depends on the type of media source being used.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaEnded

  • Added in v4.9.0

Note: These events are emitted by the OBS sources themselves. For example when the media file ends. The behavior depends on the type of media source being used.

Response Items:

Name Type Description
sourceName String Source name
sourceKind String The ID type of the source (Eg. vlc_source or ffmpeg_source)

Scene Items

SourceOrderChanged

  • Added in v4.0.0

Scene items within a scene 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

A scene item has been added to a 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

A scene item has been removed from a 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

A scene 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

A scene 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

A scene 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 (Optional): 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

  • ⚠️ Deprecated. Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0. ⚠️

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

TriggerHotkeyByName

  • Added in v4.9.0

Executes hotkey routine, identified by hotkey unique name

Request Fields:

Name Type Description
hotkeyName String Unique name of the hotkey, as defined when registering the hotkey (e.g. “ReplayBuffer.Save”)

Response Items:

No additional response items.

TriggerHotkeyBySequence

  • Added in v4.9.0

Executes hotkey routine, identified by bound combination of keys. A single key combination might trigger multiple hotkey routines depending on user settings

Request Fields:

Name Type Description
keyId String Main key identifier (e.g. OBS_KEY_A for key “A”). Available identifiers here
keyModifiers Object (Optional) Optional key modifiers object. False entries can be ommitted
keyModifiers.shift boolean Trigger Shift Key
keyModifiers.alt boolean Trigger Alt Key
keyModifiers.control boolean Trigger Control (Ctrl) Key
keyModifiers.command boolean Trigger Command Key (Mac)

Response Items:

No additional response items.

ExecuteBatch

  • Added in v4.9.0

Executes a list of requests sequentially (one-by-one on the same thread).

Request Fields:

Name Type Description
requests Array<Object> Array of requests to perform. Executed in order.
requests.*.request-type String Request type. Eg. GetVersion.
requests.*.message-id String (Optional) ID of the individual request. Can be any string and not required to be unique. Defaults to empty string if not specified.
abortOnFail boolean (Optional) Stop processing batch requests if one returns a failure.

Response Items:

Name Type Description
results Array<Object> Batch requests results, ordered sequentially.
results.*.message-id String ID of the individual request which was originally provided by the client.
results.*.status String Status response as string. Either ok or error.
results.*.error String (Optional) Error message accompanying an error status.

Sleep

  • Added in v4.9.1

Waits for the specified duration. Designed to be used in ExecuteBatch operations.

Request Fields:

Name Type Description
sleepMillis int Delay in milliseconds to wait before continuing.

Response Items:

No additional response items.

Media Control

PlayPauseMedia

  • Added in v4.9.0

Pause or play a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
Note :Leaving out playPause toggles the current pause state

Request Fields:

Name Type Description
sourceName String Source name.
playPause boolean (optional) Whether to pause or play the source. false for play, true for pause.

Response Items:

No additional response items.

RestartMedia

  • Added in v4.9.0

Restart a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

No additional response items.

StopMedia

  • Added in v4.9.0

Stop a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

No additional response items.

NextMedia

  • Added in v4.9.0

Skip to the next media item in the playlist. Supports only vlc media source (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

No additional response items.

PreviousMedia

  • Added in v4.9.0

Go to the previous media item in the playlist. Supports only vlc media source (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

No additional response items.

GetMediaDuration

  • Added in v4.9.0

Get the length of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
Note: For some reason, for the first 5 or so seconds that the media is playing, the total duration can be off by upwards of 50ms.

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

Name Type Description
mediaDuration int The total length of media in milliseconds…

GetMediaTime

  • Added in v4.9.0

Get the current timestamp of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

Name Type Description
timestamp int The time in milliseconds since the start of the media.

SetMediaTime

  • Added in v4.9.0

Set the timestamp of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.
timestamp int Milliseconds to set the timestamp to.

Response Items:

No additional response items.

ScrubMedia

  • Added in v4.9.0

Scrub media using a supplied offset. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
Note: Due to processing/network delays, this request is not perfect. The processing rate of this request has also not been tested.

Request Fields:

Name Type Description
sourceName String Source name.
timeOffset int Millisecond offset (positive or negative) to offset the current media position.

Response Items:

No additional response items.

GetMediaState

  • Added in v4.9.0

Get the current playing state of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

Name Type Description
mediaState String The media state of the provided source. States: none, playing, opening, buffering, paused, stopped, ended, error, unknown

Sources

GetMediaSourcesList

  • Added in v4.9.0

List the media state of all media sources (vlc and media source)

Request Fields:

No specified parameters.

Response Items:

Name Type Description
mediaSources Array<Object> Array of sources
mediaSources.*.sourceName String Unique source name
mediaSources.*.sourceKind String Unique source internal type (a.k.a ffmpeg_source or vlc_source)
mediaSources.*.mediaState String The current state of media for that source. States: none, playing, opening, buffering, paused, stopped, ended, error, unknown

CreateSource

  • Added in v4.9.0

Create a source and add it as a sceneitem to a scene.

Request Fields:

Name Type Description
sourceName String Source name.
sourceKind String Source kind, Eg. vlc_source.
sceneName String Scene to add the new source to.
sourceSettings Object (optional) Source settings data.
setVisible boolean (optional) Set the created SceneItem as visible or not. Defaults to true

Response Items:

Name Type Description
itemId int ID of the SceneItem in the scene.

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 kind)
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 20.0 if using mul, under 26.0 if using dB.
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 20.0 for mul, and under 26.0 for dB. OBS will interpret dB values under -100.0 as Inf. Note: The OBS volume sliders only reach a maximum of 1.0mul/0.0dB, however OBS actually supports larger values.
useDecibel boolean (optional) Interperet volume data as decibels instead of amplitude/mul.

Response Items:

No additional response items.

SetTracks

  • Added in v4.9.1

Changes whether an audio track is active for a source.

Request Fields:

Name Type Description
sourceName String Source name.
track int Audio tracks 1-6.
active boolean Whether audio track is active or not.

Response Items:

No additional response items.

GetTracks

  • Added in v4.9.1

Gets whether an audio track is active for a source.

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

Name Type Description
track1 boolean
track2 boolean
track3 boolean
track4 boolean
track5 boolean
track6 boolean

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.

GetSourceActive

  • Added in v4.9.1

Get the source’s active status of a specified source (if it is showing in the final mix).

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

Name Type Description
sourceActive boolean Source active status of the source.

GetAudioActive

  • Added in v4.9.0

Get the audio’s active status of a specified source.

Request Fields:

Name Type Description
sourceName String Source name.

Response Items:

Name Type Description
audioActive boolean Audio active status of the source.

SetSourceName

  • Added in v4.8.0

Note: If the new name already exists as a source, obs-websocket will return an error.

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. Will be removed in v5.0.0 ⚠️

  • 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. Will be removed in v5.0.0 ⚠️

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

GetSourceDefaultSettings

  • Added in v4.9.0

Get the default settings for a given source type.

Request Fields:

Name Type Description
sourceKind String Source kind. Also called “source id” in libobs terminology.

Response Items:

Name Type Description
sourceKind String Source kind. Same value as the sourceKind parameter.
defaultSettings Object Settings object for source.

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 (optional) Source name. Note: Since scenes are also sources, you can also provide a scene name. If not provided, the currently active scene is used.
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)

RefreshBrowserSource

  • Added in v4.9.0

Refreshes the specified browser source.

Request Fields:

Name Type Description
sourceName String Source name.

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

Note: Controlling outputs is an experimental feature of obs-websocket. Some plugins which add outputs to OBS may not function properly when they are controlled in this way.

Request Fields:

Name Type Description
outputName String Output name

Response Items:

No additional response items.

StopOutput

  • Added in v4.7.0

Note: Controlling outputs is an experimental feature of obs-websocket. Some plugins which add outputs to OBS may not function properly when they are controlled in this way.

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.
profiles.*.profile-name String Filter name

Recording

GetRecordingStatus

  • Added in v4.9.0

Get current recording status.

Request Fields:

No specified parameters.

Response Items:

Name Type Description
isRecording boolean Current recording status.
isRecordingPaused boolean Whether the recording is paused or not.
recordTimecode String (optional) Time elapsed since recording started (only present if currently recording).
recordingFilename String (optional) Absolute path to the recording file (only present if currently recording).

StartStopRecording

  • Added in v0.3

Toggle recording on or off (depending on the current recording state).

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

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

GetReplayBufferStatus

  • Added in v4.9.0

Get the status of the OBS replay buffer.

Request Fields:

No specified parameters.

Response Items:

Name Type Description
isReplayBufferActive boolean Current recording status.

StartStopReplayBuffer

  • Added in v4.2.0

Toggle the Replay Buffer on/off (depending on the current state of the replay buffer).

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<ScenesCollection> Scene collections list

Scene Items

GetSceneItemList

  • Added in v4.9.0

Get a list of all scene items in a scene.

Request Fields:

Name Type Description
sceneName String (optional) Name of the scene to get the list of scene items from. Defaults to the current scene if not specified.

Response Items:

Name Type Description
sceneName String Name of the requested (or current) scene
sceneItems Array<Object> Array of scene items
sceneItems.*.itemId int Unique item id of the source item
sceneItems.*.sourceKind String ID if the scene item’s source. For example vlc_source or image_source
sceneItems.*.sourceName String Name of the scene item’s source
sceneItems.*.sourceType String Type of the scene item’s source. Either input, group, or scene

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 double The x position of the source from the left.
position.y double The y position of the source from the top.
position.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.
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.
scale.filter String The scale filter of the source. Can be “OBS_SCALE_DISABLE”, “OBS_SCALE_POINT”, “OBS_SCALE_BICUBIC”, “OBS_SCALE_BILINEAR”, “OBS_SCALE_LANCZOS” or “OBS_SCALE_AREA”.
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)
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 double (optional) The new x position of the source.
position.y double (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.
scale.filter String (optional) The new scale filter of the source. Can be “OBS_SCALE_DISABLE”, “OBS_SCALE_POINT”, “OBS_SCALE_BICUBIC”, “OBS_SCALE_BILINEAR”, “OBS_SCALE_LANCZOS” or “OBS_SCALE_AREA”.
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

  • 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 (optional) Scene Item name.
item int (optional) Scene Item id
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.

AddSceneItem

  • Added in v4.9.0

Creates a scene item in a scene. In other words, this is how you add a source into a scene.

Request Fields:

Name Type Description
sceneName String Name of the scene to create the scene item in
sourceName String Name of the source to be added
setVisible boolean (optional) Whether to make the sceneitem visible on creation or not. Default true

Response Items:

Name Type Description
itemId int Numerical ID of the created scene item

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

CreateScene

  • Added in v4.9.0

Create a new scene scene.

Request Fields:

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

Response Items:

No additional response items.

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<Object> 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.8.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.8.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.8.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.

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.
recording-paused boolean If recording is paused.
virtualcam boolean Current virtual cam status.
preview-only boolean Always false. Retrocompatibility with OBSRemote.
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).
virtualcam-timecode String (optional) Time elapsed since virtual cam started (only present if virtual cam currently active).

StartStopStreaming

  • Added in v0.3

Toggle streaming on or off (depending on the current stream state).

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

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 (depending on the current state of 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.9.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.

GetTransitionSettings

  • Added in v4.9.0

Get the current settings of a transition

Request Fields:

Name Type Description
transitionName String Transition name

Response Items:

Name Type Description
transitionSettings Object Current transition settings

SetTransitionSettings

  • Added in v4.9.0

Change the current settings of a transition

Request Fields:

Name Type Description
transitionName String Transition name
transitionSettings Object Transition settings (they can be partial)

Response Items:

Name Type Description
transitionSettings Object Updated transition settings

ReleaseTBar

  • Added in v4.9.0

Release the T-Bar (like a user releasing their mouse button after moving it).
YOU MUST CALL THIS if you called SetTBarPosition with the release parameter set to false.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

SetTBarPosition

  • Added in v4.9.0

If your code needs to perform multiple successive T-Bar moves (e.g. : in an animation, or in response to a user moving a T-Bar control in your User Interface), set release to false and call ReleaseTBar later once the animation/interaction is over.

Request Fields:

Name Type Description
position double T-Bar position. This value must be between 0.0 and 1.0.
release boolean (optional) Whether or not the T-Bar gets released automatically after setting its new position (like a user releasing their mouse button after moving the T-Bar). Call ReleaseTBar manually if you set release to false. Defaults to true.

Response Items:

No additional response items.

Virtual Cam

GetVirtualCamStatus

  • Added in v4.9.1

Get current virtual cam status.

Request Fields:

No specified parameters.

Response Items:

Name Type Description
isVirtualCam boolean Current virtual camera status.
virtualCamTimecode String (optional) Time elapsed since virtual cam started (only present if virtual cam currently active).

StartStopVirtualCam

  • Added in v4.9.1

Toggle virtual cam on or off (depending on the current virtual cam state).

Request Fields:

No specified parameters.

Response Items:

No additional response items.

StartVirtualCam

  • Added in v4.9.1

Start virtual cam.
Will return an error if virtual cam is already active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

StopVirtualCam

  • Added in v4.9.1

Stop virtual cam.
Will return an error if virtual cam is not active.

Request Fields:

No specified parameters.

Response Items:

No additional response items.

上一篇：CUDA C编程（十四）合并的全局内存访问


下一篇：Ubuntu系统的安装（NVIDIA显卡驱动+cuda10+cudnn7.5）