其他分享
首页 > 其他分享> > 2021-06-29

2021-06-29

作者:互联网

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:

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

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

NameTypeDescription
cyNumber
cxNumber
alignmentNumberThe 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.
nameStringThe name of this Scene Item.
idintScene item ID
renderBooleanWhether or not this Scene Item is set to “visible”.
mutedBooleanWhether or not this Scene Item is muted.
lockedBooleanWhether or not this Scene Item is locked and can’t be moved around
source_cxNumber
source_cyNumber
typeStringSource type. Value is one of the following: “input”, “filter”, “transition”, “scene” or “unknown”
volumeNumber
xNumber
yNumber
parentGroupNameString (optional)Name of the item’s parent (if this item belongs to a group)
groupChildrenArray<SceneItem> (optional)List of children (if this item is a group)

SceneItemTransform

NameTypeDescription
position.xdoubleThe x position of the scene item from the left.
position.ydoubleThe y position of the scene item from the top.
position.alignmentintThe point on the scene item that the item is manipulated from.
rotationdoubleThe clockwise rotation of the scene item in degrees around the point of alignment.
scale.xdoubleThe x-scale factor of the scene item.
scale.ydoubleThe y-scale factor of the scene item.
scale.filterStringThe 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.topintThe number of pixels cropped off the top of the scene item before scaling.
crop.rightintThe number of pixels cropped off the right of the scene item before scaling.
crop.bottomintThe number of pixels cropped off the bottom of the scene item before scaling.
crop.leftintThe number of pixels cropped off the left of the scene item before scaling.
visibleboolIf the scene item is visible.
lockedboolIf the scene item is locked in position.
bounds.typeStringType 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.alignmentintAlignment of the bounding box.
bounds.xdoubleWidth of the bounding box.
bounds.ydoubleHeight of the bounding box.
sourceWidthintBase width (without scaling) of the source
sourceHeightintBase source (without scaling) of the source
widthdoubleScene item width (base source width multiplied by the horizontal scaling factor)
heightdoubleScene item height (base source height multiplied by the vertical scaling factor)
parentGroupNameString (optional)Name of the item’s parent (if this item belongs to a group)
groupChildrenArray<SceneItemTransform> (optional)List of children (if this item is a group)

OBSStats

NameTypeDescription
fpsdoubleCurrent framerate.
render-total-framesintNumber of frames rendered
render-missed-framesintNumber of frames missed due to rendering lag
output-total-framesintNumber of frames outputted
output-skipped-framesintNumber of frames skipped due to encoding lag
average-frame-timedoubleAverage frame render time (in milliseconds)
cpu-usagedoubleCurrent CPU usage (percentage)
memory-usagedoubleCurrent RAM usage (in megabytes)
free-disk-spacedoubleFree recording disk space (in megabytes)

Output

NameTypeDescription
nameStringOutput name
typeStringOutput type/kind
widthintVideo output width
heightintVideo output height
flagsObjectOutput flags
flags.rawValueintRaw flags value
flags.audiobooleanOutput uses audio
flags.videobooleanOutput uses video
flags.encodedbooleanOutput is encoded
flags.multiTrackbooleanOutput uses several audio tracks
flags.servicebooleanOutput uses a service
settingsObjectOutput settings
activebooleanOutput status (active or not)
reconnectingbooleanOutput reconnection status (reconnecting or not)
congestiondoubleOutput congestion
totalFramesintNumber of frames sent
droppedFramesintNumber of frames dropped
totalBytesintTotal bytes sent

ScenesCollection

NameTypeDescription
sc-nameStringName of the scene collection

Scene

NameTypeDescription
nameStringName of the currently active scene.
sourcesArray<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:

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

Indicates a scene change.

Response Items:

NameTypeDescription
scene-nameStringThe new scene.
sourcesArray<SceneItem>List of scene items in the new scene. Same specification as GetCurrentScene.

ScenesChanged

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

Response Items:

NameTypeDescription
scenesArray<Scene>Scenes list.

SceneCollectionChanged

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

Response Items:

NameTypeDescription
sceneCollectionStringName of the new current scene collection.

SceneCollectionListChanged

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

Response Items:

NameTypeDescription
sceneCollectionsArray<Object>Scene collections list.
sceneCollections.*.nameStringScene collection name.

Transitions

SwitchTransition

The active transition has been changed.

Response Items:

NameTypeDescription
transition-nameStringThe name of the new active transition.

TransitionListChanged

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

Response Items:

NameTypeDescription
transitionsArray<Object>Transitions list.
transitions.*.nameStringTransition name.

TransitionDurationChanged

The active transition duration has been changed.

Response Items:

NameTypeDescription
new-durationintNew transition duration.

TransitionBegin

A transition (other than “cut”) has begun.

Response Items:

NameTypeDescription
nameStringTransition name.
typeStringTransition type.
durationintTransition 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-sceneString (optional)Source scene of the transition
to-sceneStringDestination scene of the transition

TransitionEnd

A transition (other than “cut”) has ended.
Note: The from-scene field is not available in TransitionEnd.

Response Items:

NameTypeDescription
nameStringTransition name.
typeStringTransition type.
durationintTransition duration (in milliseconds).
to-sceneStringDestination scene of the transition

TransitionVideoEnd

A stinger transition has finished playing its video.

Response Items:

NameTypeDescription
nameStringTransition name.
typeStringTransition type.
durationintTransition duration (in milliseconds).
from-sceneString (optional)Source scene of the transition
to-sceneStringDestination scene of the transition

Profiles

ProfileChanged

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

Response Items:

NameTypeDescription
profileStringName of the new current profile.

ProfileListChanged

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

Response Items:

NameTypeDescription
profilesArray<Object>Profiles list.
profiles.*.nameStringProfile name.

Streaming

StreamStarting

A request to start streaming has been issued.

Response Items:

NameTypeDescription
preview-onlybooleanAlways false (retrocompatibility).

StreamStarted

Streaming started successfully.

Response Items:

No additional response items.


StreamStopping

A request to stop streaming has been issued.

Response Items:

NameTypeDescription
preview-onlybooleanAlways false (retrocompatibility).

StreamStopped

Streaming stopped successfully.

Response Items:

No additional response items.


StreamStatus

Emitted every 2 seconds when stream is active.

Response Items:

NameTypeDescription
streamingbooleanCurrent streaming state.
recordingbooleanCurrent recording state.
replay-buffer-activebooleanReplay Buffer status
bytes-per-secintAmount of data per second (in bytes) transmitted by the stream encoder.
kbits-per-secintAmount of data per second (in kilobits) transmitted by the stream encoder.
straindoublePercentage of dropped frames.
total-stream-timeintTotal time (in seconds) since the stream started.
num-total-framesintTotal number of frames transmitted since the stream started.
num-dropped-framesintNumber of frames dropped by the encoder since the stream started.
fpsdoubleCurrent framerate.
render-total-framesintNumber of frames rendered
render-missed-framesintNumber of frames missed due to rendering lag
output-total-framesintNumber of frames outputted
output-skipped-framesintNumber of frames skipped due to encoding lag
average-frame-timedoubleAverage frame time (in milliseconds)
cpu-usagedoubleCurrent CPU usage (percentage)
memory-usagedoubleCurrent RAM usage (in megabytes)
free-disk-spacedoubleFree recording disk space (in megabytes)
preview-onlybooleanAlways false (retrocompatibility).

Recording

RecordingStarting

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

Recording started successfully.

Response Items:

NameTypeDescription
recordingFilenameStringAbsolute path to the file of the current recording.

RecordingStopping

A request to stop recording has been issued.

Response Items:

NameTypeDescription
recordingFilenameStringAbsolute path to the file of the current recording.

RecordingStopped

Recording stopped successfully.

Response Items:

NameTypeDescription
recordingFilenameStringAbsolute path to the file of the current recording.

RecordingPaused

Current recording paused

Response Items:

No additional response items.


RecordingResumed

Current recording resumed

Response Items:

No additional response items.


Virtual Cam

VirtualCamStarted

Virtual cam started successfully.

Response Items:

No additional response items.


VirtualCamStopped

Virtual cam stopped successfully.

Response Items:

No additional response items.


Replay Buffer

ReplayStarting

A request to start the replay buffer has been issued.

Response Items:

No additional response items.


ReplayStarted

Replay Buffer started successfully

Response Items:

No additional response items.


ReplayStopping

A request to stop the replay buffer has been issued.

Response Items:

No additional response items.


ReplayStopped

Replay Buffer stopped successfully

Response Items:

No additional response items.


Other

Exiting

OBS is exiting.

Response Items:

No additional response items.


General

Heartbeat

Emitted every 2 seconds after enabling it by calling SetHeartbeat.

Response Items:

NameTypeDescription
pulsebooleanToggles between every JSON message as an “I am alive” indicator.
current-profilestring (optional)Current active profile.
current-scenestring (optional)Current active scene.
streamingboolean (optional)Current streaming state.
total-stream-timeint (optional)Total time (in seconds) since the stream started.
total-stream-bytesint (optional)Total bytes sent since the stream started.
total-stream-framesint (optional)Total frames streamed since the stream started.
recordingboolean (optional)Current recording state.
total-record-timeint (optional)Total time (in seconds) since recording started.
total-record-bytesint (optional)Total bytes recorded since the recording started.
total-record-framesint (optional)Total frames recorded since the recording started.
statsOBSStatsOBS Stats

BroadcastCustomMessage

A custom broadcast message, sent by the server, requested by one of the websocket clients.

Response Items:

NameTypeDescription
realmStringIdentifier provided by the sender
dataObjectUser-defined data

Sources

SourceCreated

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

Response Items:

NameTypeDescription
sourceNameStringSource name
sourceTypeStringSource type. Can be “input”, “scene”, “transition” or “filter”.
sourceKindStringSource kind.
sourceSettingsObjectSource settings

SourceDestroyed

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

Response Items:

NameTypeDescription
sourceNameStringSource name
sourceTypeStringSource type. Can be “input”, “scene”, “transition” or “filter”.
sourceKindStringSource kind.

SourceVolumeChanged

The volume of a source has changed.

Response Items:

NameTypeDescription
sourceNameStringSource name
volumefloatSource volume
volumeDbfloatSource volume in Decibel

SourceMuteStateChanged

A source has been muted or unmuted.

Response Items:

NameTypeDescription
sourceNameStringSource name
mutedbooleanMute status of the source

SourceAudioDeactivated

A source has removed audio.

Response Items:

NameTypeDescription
sourceNameStringSource name

SourceAudioActivated

A source has added audio.

Response Items:

NameTypeDescription
sourceNameStringSource name

SourceAudioSyncOffsetChanged

The audio sync offset of a source has changed.

Response Items:

NameTypeDescription
sourceNameStringSource name
syncOffsetintAudio sync offset of the source (in nanoseconds)

SourceAudioMixersChanged

Audio mixer routing changed on a source.

Response Items:

NameTypeDescription
sourceNameStringSource name
mixersArray<Object>Routing status of the source for each audio mixer (array of 6 values)
mixers.*.idintMixer number
mixers.*.enabledbooleanRouting status
hexMixersValueStringRaw mixer flags (little-endian, one bit per mixer) as an hexadecimal value

SourceRenamed

A source has been renamed.

Response Items:

NameTypeDescription
previousNameStringPrevious source name
newNameStringNew source name
sourceTypeStringType of source (input, scene, filter, transition)

SourceFilterAdded

A filter was added to a source.

Response Items:

NameTypeDescription
sourceNameStringSource name
filterNameStringFilter name
filterTypeStringFilter type
filterSettingsObjectFilter settings

SourceFilterRemoved

A filter was removed from a source.

Response Items:

NameTypeDescription
sourceNameStringSource name
filterNameStringFilter name
filterTypeStringFilter type

SourceFilterVisibilityChanged

The visibility/enabled state of a filter changed

Response Items:

NameTypeDescription
sourceNameStringSource name
filterNameStringFilter name
filterEnabledBooleanNew filter state

SourceFiltersReordered

Filters in a source have been reordered.

Response Items:

NameTypeDescription
sourceNameStringSource name
filtersArray<Object>Ordered Filters list
filters.*.nameStringFilter name
filters.*.typeStringFilter type
filters.*.enabledbooleanFilter visibility status

Media

MediaPlaying

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaPaused

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaRestarted

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaStopped

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaNext

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaPrevious

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaStarted

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

MediaEnded

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:

NameTypeDescription
sourceNameStringSource name
sourceKindStringThe ID type of the source (Eg. vlc_source or ffmpeg_source)

Scene Items

SourceOrderChanged

Scene items within a scene have been reordered.

Response Items:

NameTypeDescription
scene-nameStringName of the scene where items have been reordered.
scene-itemsArray<Object>Ordered list of scene items
scene-items.*.source-nameStringItem source name
scene-items.*.item-idintScene item unique ID

SceneItemAdded

A scene item has been added to a scene.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item added to the scene.
item-idintScene item ID

SceneItemRemoved

A scene item has been removed from a scene.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item removed from the scene.
item-idintScene item ID

SceneItemVisibilityChanged

A scene item’s visibility has been toggled.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item in the scene.
item-idintScene item ID
item-visiblebooleanNew visibility state of the item.

SceneItemLockChanged

A scene item’s locked status has been toggled.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item in the scene.
item-idintScene item ID
item-lockedbooleanNew locked state of the item.

SceneItemTransformChanged

A scene item’s transform has been changed.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item in the scene.
item-idintScene item ID
transformSceneItemTransformScene item transform properties

SceneItemSelected

A scene item is selected.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item in the scene.
item-idintName of the item in the scene.

SceneItemDeselected

A scene item is deselected.

Response Items:

NameTypeDescription
scene-nameStringName of the scene.
item-nameStringName of the item in the scene.
item-idintName of the item in the scene.

Studio Mode

PreviewSceneChanged

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

Response Items:

NameTypeDescription
scene-nameStringName of the scene being previewed.
sourcesArray<SceneItem>List of sources composing the scene. Same specification as GetCurrentScene.

StudioModeSwitched

Studio Mode has been enabled or disabled.

Response Items:

NameTypeDescription
new-statebooleanThe new enabled state of Studio Mode.

Requests

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

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

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

General

GetVersion

Returns the latest version of the plugin and the API.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
versiondoubleOBSRemote compatible API version. Fixed to 1.1 for retrocompatibility.
obs-websocket-versionStringobs-websocket plugin version.
obs-studio-versionStringOBS Studio program version.
available-requestsStringList of available request types, formatted as a comma-separated list string (e.g. : “Method1,Method2,Method3”).
supported-image-export-formatsStringList of supported formats for features that use image export (like the TakeSourceScreenshot request type) formatted as a comma-separated list string

GetAuthRequired

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:

NameTypeDescription
authRequiredbooleanIndicates whether authentication is required.
challengeString (optional)
saltString (optional)

Authenticate

Attempt to authenticate the client to the server.

Request Fields:

NameTypeDescription
authStringResponse to the auth challenge (see “Authentication” for more information).

Response Items:

No additional response items.


SetHeartbeat

Enable/disable sending of the Heartbeat event

Request Fields:

NameTypeDescription
enablebooleanStarts/Stops emitting heartbeat messages

Response Items:

No additional response items.


SetFilenameFormatting

Set the filename formatting string

Request Fields:

NameTypeDescription
filename-formattingStringFilename formatting string to set.

Response Items:

No additional response items.


GetFilenameFormatting

Get the filename formatting string

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
filename-formattingStringCurrent filename formatting string.

GetStats

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

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
statsOBSStatsOBS stats

BroadcastCustomMessage

Broadcast custom message to all connected WebSocket clients

Request Fields:

NameTypeDescription
realmStringIdentifier to be choosen by the client
dataObjectUser-defined data

Response Items:

No additional response items.


GetVideoInfo

Get basic OBS video information

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
baseWidthintBase (canvas) width
baseHeightintBase (canvas) height
outputWidthintOutput width
outputHeightintOutput height
scaleTypeStringScaling method used if output size differs from base size
fpsdoubleFrames rendered per second
videoFormatStringVideo color format
colorSpaceStringColor space for YUV
colorRangeStringColor range (full or partial)

OpenProjector

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

Request Fields:

NameTypeDescription
typeString (Optional)Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive).
monitorint (Optional)Monitor to open the projector on. If -1 or omitted, opens a window.
geometryString (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.
nameString (Optional)Name of the source or scene to be displayed (ignored for other projector types).

Response Items:

No additional response items.


TriggerHotkeyByName

Executes hotkey routine, identified by hotkey unique name

Request Fields:

NameTypeDescription
hotkeyNameStringUnique name of the hotkey, as defined when registering the hotkey (e.g. “ReplayBuffer.Save”)

Response Items:

No additional response items.


TriggerHotkeyBySequence

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

Request Fields:

NameTypeDescription
keyIdStringMain key identifier (e.g. OBS_KEY_A for key “A”). Available identifiers here
keyModifiersObject (Optional)Optional key modifiers object. False entries can be ommitted
keyModifiers.shiftbooleanTrigger Shift Key
keyModifiers.altbooleanTrigger Alt Key
keyModifiers.controlbooleanTrigger Control (Ctrl) Key
keyModifiers.commandbooleanTrigger Command Key (Mac)

Response Items:

No additional response items.


ExecuteBatch

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

Request Fields:

NameTypeDescription
requestsArray<Object>Array of requests to perform. Executed in order.
requests.*.request-typeStringRequest type. Eg. GetVersion.
requests.*.message-idString (Optional)ID of the individual request. Can be any string and not required to be unique. Defaults to empty string if not specified.
abortOnFailboolean (Optional)Stop processing batch requests if one returns a failure.

Response Items:

NameTypeDescription
resultsArray<Object>Batch requests results, ordered sequentially.
results.*.message-idStringID of the individual request which was originally provided by the client.
results.*.statusStringStatus response as string. Either ok or error.
results.*.errorString (Optional)Error message accompanying an error status.

Sleep

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

Request Fields:

NameTypeDescription
sleepMillisintDelay in milliseconds to wait before continuing.

Response Items:

No additional response items.


Media Control

PlayPauseMedia

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:

NameTypeDescription
sourceNameStringSource name.
playPauseboolean(optional) Whether to pause or play the source. false for play, true for pause.

Response Items:

No additional response items.


RestartMedia

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

No additional response items.


StopMedia

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

No additional response items.


NextMedia

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

No additional response items.


PreviousMedia

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

No additional response items.


GetMediaDuration

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:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
mediaDurationintThe total length of media in milliseconds…

GetMediaTime

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
timestampintThe time in milliseconds since the start of the media.

SetMediaTime

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.
timestampintMilliseconds to set the timestamp to.

Response Items:

No additional response items.


ScrubMedia

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:

NameTypeDescription
sourceNameStringSource name.
timeOffsetintMillisecond offset (positive or negative) to offset the current media position.

Response Items:

No additional response items.


GetMediaState

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
mediaStateStringThe media state of the provided source. States: none, playing, opening, buffering, paused, stopped, ended, error, unknown

Sources

GetMediaSourcesList

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

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
mediaSourcesArray<Object>Array of sources
mediaSources.*.sourceNameStringUnique source name
mediaSources.*.sourceKindStringUnique source internal type (a.k.a ffmpeg_source or vlc_source)
mediaSources.*.mediaStateStringThe current state of media for that source. States: none, playing, opening, buffering, paused, stopped, ended, error, unknown

CreateSource

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.
sourceKindStringSource kind, Eg. vlc_source.
sceneNameStringScene to add the new source to.
sourceSettingsObject (optional)Source settings data.
setVisibleboolean (optional)Set the created SceneItem as visible or not. Defaults to true

Response Items:

NameTypeDescription
itemIdintID of the SceneItem in the scene.

GetSourcesList

List all sources available in the running OBS instance

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
sourcesArray<Object>Array of sources
sources.*.nameStringUnique source name
sources.*.typeIdStringNon-unique source internal type (a.k.a kind)
sources.*.typeStringSource type. Value is one of the following: “input”, “filter”, “transition”, “scene” or “unknown”

GetSourceTypesList

Get a list of all available sources types

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
typesArray<Object>Array of source types
types.*.typeIdStringNon-unique internal source type ID
types.*.displayNameStringDisplay name of the source type
types.*.typeStringType. Value is one of the following: “input”, “filter”, “transition” or “other”
types.*.defaultSettingsObjectDefault settings of this source type
types.*.capsObjectSource type capabilities
types.*.caps.isAsyncBooleanTrue if source of this type provide frames asynchronously
types.*.caps.hasVideoBooleanTrue if sources of this type provide video
types.*.caps.hasAudioBooleanTrue if sources of this type provide audio
types.*.caps.canInteractBooleanTrue if interaction with this sources of this type is possible
types.*.caps.isCompositeBooleanTrue if sources of this type composite one or more sub-sources
types.*.caps.doNotDuplicateBooleanTrue if sources of this type should not be fully duplicated
types.*.caps.doNotSelfMonitorBooleanTrue if sources of this type may cause a feedback loop if it’s audio is monitored and shouldn’t be

GetVolume

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

Request Fields:

NameTypeDescription
sourceStringSource name.
useDecibelboolean (optional)Output volume in decibels of attenuation instead of amplitude/mul.

Response Items:

NameTypeDescription
nameStringSource name.
volumedoubleVolume of the source. Between 0.0 and 20.0 if using mul, under 26.0 if using dB.
mutedbooleanIndicates whether the source is muted.

SetVolume

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

Request Fields:

NameTypeDescription
sourceStringSource name.
volumedoubleDesired 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.
useDecibelboolean (optional)Interperet volume data as decibels instead of amplitude/mul.

Response Items:

No additional response items.


SetTracks

Changes whether an audio track is active for a source.

Request Fields:

NameTypeDescription
sourceNameStringSource name.
trackintAudio tracks 1-6.
activebooleanWhether audio track is active or not.

Response Items:

No additional response items.


GetTracks

Gets whether an audio track is active for a source.

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
track1boolean
track2boolean
track3boolean
track4boolean
track5boolean
track6boolean

GetMute

Get the mute status of a specified source.

Request Fields:

NameTypeDescription
sourceStringSource name.

Response Items:

NameTypeDescription
nameStringSource name.
mutedbooleanMute status of the source.

SetMute

Sets the mute status of a specified source.

Request Fields:

NameTypeDescription
sourceStringSource name.
mutebooleanDesired mute status.

Response Items:

No additional response items.


ToggleMute

Inverts the mute status of a specified source.

Request Fields:

NameTypeDescription
sourceStringSource name.

Response Items:

No additional response items.


GetSourceActive

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
sourceActivebooleanSource active status of the source.

GetAudioActive

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
audioActivebooleanAudio active status of the source.

SetSourceName

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

Request Fields:

NameTypeDescription
sourceNameStringSource name.
newNameStringNew source name.

Response Items:

No additional response items.


SetSyncOffset

Set the audio sync offset of a specified source.

Request Fields:

NameTypeDescription
sourceStringSource name.
offsetintThe desired audio sync offset (in nanoseconds).

Response Items:

No additional response items.


GetSyncOffset

Get the audio sync offset of a specified source.

Request Fields:

NameTypeDescription
sourceStringSource name.

Response Items:

NameTypeDescription
nameStringSource name.
offsetintThe audio sync offset (in nanoseconds).

GetSourceSettings

Get settings of the specified source

Request Fields:

NameTypeDescription
sourceNameStringSource name.
sourceTypeString (optional)Type of the specified source. Useful for type-checking if you expect a specific settings schema.

Response Items:

NameTypeDescription
sourceNameStringSource name
sourceTypeStringType of the specified source
sourceSettingsObjectSource settings (varies between source types, may require some probing around).

SetSourceSettings

Set settings of the specified source.

Request Fields:

NameTypeDescription
sourceNameStringSource name.
sourceTypeString (optional)Type of the specified source. Useful for type-checking to avoid settings a set of settings incompatible with the actual source’s type.
sourceSettingsObjectSource settings (varies between source types, may require some probing around).

Response Items:

NameTypeDescription
sourceNameStringSource name
sourceTypeStringType of the specified source
sourceSettingsObjectUpdated source settings

GetTextGDIPlusProperties

Get the current properties of a Text GDI Plus source.

Request Fields:

NameTypeDescription
sourceStringSource name.

Response Items:

NameTypeDescription
sourceStringSource name.
alignStringText Alignment (“left”, “center”, “right”).
bk_colorintBackground color.
bk_opacityintBackground opacity (0-100).
chatlogbooleanChat log.
chatlog_linesintChat log lines.
colorintText color.
extentsbooleanExtents wrap.
extents_cxintExtents cx.
extents_cyintExtents cy.
fileStringFile path name.
read_from_filebooleanRead text from the specified file.
fontObjectHolds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.faceStringFont face.
font.flagsintFont text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.sizeintFont text size.
font.styleStringFont Style (unknown function).
gradientbooleanGradient enabled.
gradient_colorintGradient color.
gradient_dirfloatGradient direction.
gradient_opacityintGradient opacity (0-100).
outlinebooleanOutline.
outline_colorintOutline color.
outline_sizeintOutline size.
outline_opacityintOutline opacity (0-100).
textStringText content to be displayed.
valignStringText vertical alignment (“top”, “center”, “bottom”).
verticalbooleanVertical text enabled.

SetTextGDIPlusProperties

Set the current properties of a Text GDI Plus source.

Request Fields:

NameTypeDescription
sourceStringName of the source.
alignString (optional)Text Alignment (“left”, “center”, “right”).
bk_colorint (optional)Background color.
bk_opacityint (optional)Background opacity (0-100).
chatlogboolean (optional)Chat log.
chatlog_linesint (optional)Chat log lines.
colorint (optional)Text color.
extentsboolean (optional)Extents wrap.
extents_cxint (optional)Extents cx.
extents_cyint (optional)Extents cy.
fileString (optional)File path name.
read_from_fileboolean (optional)Read text from the specified file.
fontObject (optional)Holds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.faceString (optional)Font face.
font.flagsint (optional)Font text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.sizeint (optional)Font text size.
font.styleString (optional)Font Style (unknown function).
gradientboolean (optional)Gradient enabled.
gradient_colorint (optional)Gradient color.
gradient_dirfloat (optional)Gradient direction.
gradient_opacityint (optional)Gradient opacity (0-100).
outlineboolean (optional)Outline.
outline_colorint (optional)Outline color.
outline_sizeint (optional)Outline size.
outline_opacityint (optional)Outline opacity (0-100).
textString (optional)Text content to be displayed.
valignString (optional)Text vertical alignment (“top”, “center”, “bottom”).
verticalboolean (optional)Vertical text enabled.
renderboolean (optional)Visibility of the scene item.

Response Items:

No additional response items.


GetTextFreetype2Properties

Get the current properties of a Text Freetype 2 source.

Request Fields:

NameTypeDescription
sourceStringSource name.

Response Items:

NameTypeDescription
sourceStringSource name
color1intGradient top color.
color2intGradient bottom color.
custom_widthintCustom width (0 to disable).
drop_shadowbooleanDrop shadow.
fontObjectHolds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.faceStringFont face.
font.flagsintFont text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.sizeintFont text size.
font.styleStringFont Style (unknown function).
from_filebooleanRead text from the specified file.
log_modebooleanChat log.
outlinebooleanOutline.
textStringText content to be displayed.
text_fileStringFile path.
word_wrapbooleanWord wrap.

SetTextFreetype2Properties

Set the current properties of a Text Freetype 2 source.

Request Fields:

NameTypeDescription
sourceStringSource name.
color1int (optional)Gradient top color.
color2int (optional)Gradient bottom color.
custom_widthint (optional)Custom width (0 to disable).
drop_shadowboolean (optional)Drop shadow.
fontObject (optional)Holds data for the font. Ex: "font": { "face": "Arial", "flags": 0, "size": 150, "style": "" }
font.faceString (optional)Font face.
font.flagsint (optional)Font text styling flag. Bold=1, Italic=2, Bold Italic=3, Underline=5, Strikeout=8
font.sizeint (optional)Font text size.
font.styleString (optional)Font Style (unknown function).
from_fileboolean (optional)Read text from the specified file.
log_modeboolean (optional)Chat log.
outlineboolean (optional)Outline.
textString (optional)Text content to be displayed.
text_fileString (optional)File path.
word_wrapboolean (optional)Word wrap.

Response Items:

No additional response items.


GetBrowserSourceProperties

Get current properties for a Browser Source.

Request Fields:

NameTypeDescription
sourceStringSource name.

Response Items:

NameTypeDescription
sourceStringSource name.
is_local_filebooleanIndicates that a local file is in use.
local_fileStringfile path.
urlStringUrl.
cssStringCSS to inject.
widthintWidth.
heightintHeight.
fpsintFramerate.
shutdownbooleanIndicates whether the source should be shutdown when not visible.

SetBrowserSourceProperties

Set current properties for a Browser Source.

Request Fields:

NameTypeDescription
sourceStringName of the source.
is_local_fileboolean (optional)Indicates that a local file is in use.
local_fileString (optional)file path.
urlString (optional)Url.
cssString (optional)CSS to inject.
widthint (optional)Width.
heightint (optional)Height.
fpsint (optional)Framerate.
shutdownboolean (optional)Indicates whether the source should be shutdown when not visible.
renderboolean (optional)Visibility of the scene item.

Response Items:

No additional response items.


GetSpecialSources

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

Request Fields:

No specified parameters.

Response Items:

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

GetSourceFilters

List filters applied to a source

Request Fields:

NameTypeDescription
sourceNameStringSource name

Response Items:

NameTypeDescription
filtersArray<Object>List of filters for the specified source
filters.*.enabledBooleanFilter status (enabled or not)
filters.*.typeStringFilter type
filters.*.nameStringFilter name
filters.*.settingsObjectFilter settings

GetSourceFilterInfo

List filters applied to a source

Request Fields:

NameTypeDescription
sourceNameStringSource name
filterNameStringSource filter name

Response Items:

NameTypeDescription
enabledBooleanFilter status (enabled or not)
typeStringFilter type
nameStringFilter name
settingsObjectFilter settings

AddFilterToSource

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

Request Fields:

NameTypeDescription
sourceNameStringName of the source on which the filter is added
filterNameStringName of the new filter
filterTypeStringFilter type
filterSettingsObjectFilter settings

Response Items:

No additional response items.


RemoveFilterFromSource

Remove a filter from a source

Request Fields:

NameTypeDescription
sourceNameStringName of the source from which the specified filter is removed
filterNameStringName of the filter to remove

Response Items:

No additional response items.


ReorderSourceFilter

Move a filter in the chain (absolute index positioning)

Request Fields:

NameTypeDescription
sourceNameStringName of the source to which the filter belongs
filterNameStringName of the filter to reorder
newIndexIntegerDesired position of the filter in the chain

Response Items:

No additional response items.


MoveSourceFilter

Move a filter in the chain (relative positioning)

Request Fields:

NameTypeDescription
sourceNameStringName of the source to which the filter belongs
filterNameStringName of the filter to reorder
movementTypeStringHow to move the filter around in the source’s filter chain. Either “up”, “down”, “top” or “bottom”.

Response Items:

No additional response items.


SetSourceFilterSettings

Update settings of a filter

Request Fields:

NameTypeDescription
sourceNameStringName of the source to which the filter belongs
filterNameStringName of the filter to reconfigure
filterSettingsObjectNew settings. These will be merged to the current filter settings.

Response Items:

No additional response items.


SetSourceFilterVisibility

Change the visibility/enabled state of a filter

Request Fields:

NameTypeDescription
sourceNameStringSource name
filterNameStringSource filter name
filterEnabledBooleanNew filter state

Response Items:

No additional response items.


GetAudioMonitorType

Get the audio monitoring type of the specified source.

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

NameTypeDescription
monitorTypeStringThe monitor type in use. Options: none, monitorOnly, monitorAndOutput.

SetAudioMonitorType

Set the audio monitoring type of the specified source.

Request Fields:

NameTypeDescription
sourceNameStringSource name.
monitorTypeStringThe monitor type to use. Options: none, monitorOnly, monitorAndOutput.

Response Items:

No additional response items.


GetSourceDefaultSettings

Get the default settings for a given source type.

Request Fields:

NameTypeDescription
sourceKindStringSource kind. Also called “source id” in libobs terminology.

Response Items:

NameTypeDescription
sourceKindStringSource kind. Same value as the sourceKind parameter.
defaultSettingsObjectSettings object for source.

TakeSourceScreenshot

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:

NameTypeDescription
sourceNameString (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.
embedPictureFormatString (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)
saveToFilePathString (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.
fileFormatString (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.
compressionQualityint (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.
widthint (optional)Screenshot width. Defaults to the source’s base width.
heightint (optional)Screenshot height. Defaults to the source’s base height.

Response Items:

NameTypeDescription
sourceNameStringSource name
imgStringImage Data URI (if embedPictureFormat was specified in the request)
imageFileStringAbsolute path to the saved image file (if saveToFilePath was specified in the request)

RefreshBrowserSource

Refreshes the specified browser source.

Request Fields:

NameTypeDescription
sourceNameStringSource name.

Response Items:

No additional response items.


Outputs

ListOutputs

List existing outputs

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
outputsArray<Output>Outputs list

GetOutputInfo

Get information about a single output

Request Fields:

NameTypeDescription
outputNameStringOutput name

Response Items:

NameTypeDescription
outputInfoOutputOutput info

StartOutput

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:

NameTypeDescription
outputNameStringOutput name

Response Items:

No additional response items.


StopOutput

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:

NameTypeDescription
outputNameStringOutput name
forceboolean (optional)Force stop (default: false)

Response Items:

No additional response items.


Profiles

SetCurrentProfile

Set the currently active profile.

Request Fields:

NameTypeDescription
profile-nameStringName of the desired profile.

Response Items:

No additional response items.


GetCurrentProfile

Get the name of the current profile.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
profile-nameStringName of the currently active profile.

ListProfiles

Get a list of available profiles.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
profilesArray<Object>List of available profiles.
profiles.*.profile-nameStringFilter name

Recording

GetRecordingStatus

Get current recording status.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
isRecordingbooleanCurrent recording status.
isRecordingPausedbooleanWhether the recording is paused or not.
recordTimecodeString (optional)Time elapsed since recording started (only present if currently recording).
recordingFilenameString (optional)Absolute path to the recording file (only present if currently recording).

StartStopRecording

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

Request Fields:

No specified parameters.

Response Items:

No additional response items.


StartRecording

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

Request Fields:

No specified parameters.

Response Items:

No additional response items.


StopRecording

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

Request Fields:

No specified parameters.

Response Items:

No additional response items.


PauseRecording

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

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

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:

NameTypeDescription
rec-folderStringPath of the recording folder.

Response Items:

No additional response items.


GetRecordingFolder

Get the path of the current recording folder.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
rec-folderStringPath of the recording folder.

Replay Buffer

GetReplayBufferStatus

Get the status of the OBS replay buffer.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
isReplayBufferActivebooleanCurrent recording status.

StartStopReplayBuffer

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

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

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

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

Change the active scene collection.

Request Fields:

NameTypeDescription
sc-nameStringName of the desired scene collection.

Response Items:

No additional response items.


GetCurrentSceneCollection

Get the name of the current scene collection.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
sc-nameStringName of the currently active scene collection.

ListSceneCollections

List available scene collections

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
scene-collectionsArray<ScenesCollection>Scene collections list

Scene Items

GetSceneItemList

Get a list of all scene items in a scene.

Request Fields:

NameTypeDescription
sceneNameString (optional)Name of the scene to get the list of scene items from. Defaults to the current scene if not specified.

Response Items:

NameTypeDescription
sceneNameStringName of the requested (or current) scene
sceneItemsArray<Object>Array of scene items
sceneItems.*.itemIdintUnique item id of the source item
sceneItems.*.sourceKindStringID if the scene item’s source. For example vlc_source or image_source
sceneItems.*.sourceNameStringName of the scene item’s source
sceneItems.*.sourceTypeStringType of the scene item’s source. Either input, group, or scene

GetSceneItemProperties

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:

NameTypeDescription
scene-nameString (optional)Name of the scene the scene item belongs to. Defaults to the current scene.
itemString | ObjectScene Item name (if this field is a string) or specification (if it is an object).
item.nameString (optional)Scene Item name (if the item field is an object)
item.idint (optional)Scene Item ID (if the item field is an object)

Response Items:

NameTypeDescription
nameStringScene Item name.
itemIdintScene Item ID.
position.xdoubleThe x position of the source from the left.
position.ydoubleThe y position of the source from the top.
position.alignmentintThe 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.
rotationdoubleThe clockwise rotation of the item in degrees around the point of alignment.
scale.xdoubleThe x-scale factor of the source.
scale.ydoubleThe y-scale factor of the source.
scale.filterStringThe 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.topintThe number of pixels cropped off the top of the source before scaling.
crop.rightintThe number of pixels cropped off the right of the source before scaling.
crop.bottomintThe number of pixels cropped off the bottom of the source before scaling.
crop.leftintThe number of pixels cropped off the left of the source before scaling.
visibleboolIf the source is visible.
mutedboolIf the source is muted.
lockedboolIf the source’s transform is locked.
bounds.typeStringType 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.alignmentintAlignment of the bounding box.
bounds.xdoubleWidth of the bounding box.
bounds.ydoubleHeight of the bounding box.
sourceWidthintBase width (without scaling) of the source
sourceHeightintBase source (without scaling) of the source
widthdoubleScene item width (base source width multiplied by the horizontal scaling factor)
heightdoubleScene item height (base source height multiplied by the vertical scaling factor)
parentGroupNameString (optional)Name of the item’s parent (if this item belongs to a group)
groupChildrenArray<SceneItemTransform> (optional)List of children (if this item is a group)

SetSceneItemProperties

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:

NameTypeDescription
scene-nameString (optional)Name of the scene the source item belongs to. Defaults to the current scene.
itemString | ObjectScene Item name (if this field is a string) or specification (if it is an object).
item.nameString (optional)Scene Item name (if the item field is an object)
item.idint (optional)Scene Item ID (if the item field is an object)
position.xdouble (optional)The new x position of the source.
position.ydouble (optional)The new y position of the source.
position.alignmentint (optional)The new alignment of the source.
rotationdouble (optional)The new clockwise rotation of the item in degrees.
scale.xdouble (optional)The new x scale of the item.
scale.ydouble (optional)The new y scale of the item.
scale.filterString (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.topint (optional)The new amount of pixels cropped off the top of the source before scaling.
crop.bottomint (optional)The new amount of pixels cropped off the bottom of the source before scaling.
crop.leftint (optional)The new amount of pixels cropped off the left of the source before scaling.
crop.rightint (optional)The new amount of pixels cropped off the right of the source before scaling.
visiblebool (optional)The new visibility of the source. ‘true’ shows source, ‘false’ hides source.
lockedbool (optional)The new locked status of the source. ‘true’ keeps it in its current position, ‘false’ allows movement.
bounds.typeString (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.alignmentint (optional)The new alignment of the bounding box. (0-2, 4-6, 8-10)
bounds.xdouble (optional)The new width of the bounding box.
bounds.ydouble (optional)The new height of the bounding box.

Response Items:

No additional response items.


ResetSceneItem

Reset a scene item.

Request Fields:

NameTypeDescription
scene-nameString (optional)Name of the scene the scene item belongs to. Defaults to the current scene.
itemString | ObjectScene Item name (if this field is a string) or specification (if it is an object).
item.nameString (optional)Scene Item name (if the item field is an object)
item.idint (optional)Scene Item ID (if the item field is an object)

Response Items:

No additional response items.


SetSceneItemRender

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

Request Fields:

NameTypeDescription
scene-nameString (optional)Name of the scene the scene item belongs to. Defaults to the currently active scene.
sourceString (optional)Scene Item name.
itemint (optional)Scene Item id
renderbooleantrue = shown ; false = hidden

Response Items:

No additional response items.


SetSceneItemPosition

Sets the coordinates of a specified source item.

Request Fields:

NameTypeDescription
scene-nameString (optional)Name of the scene the scene item belongs to. Defaults to the current scene.
itemStringScene Item name.
xdoubleX coordinate.
ydoubleY coordinate.

Response Items:

No additional response items.


SetSceneItemTransform

Set the transform of the specified source item.

Request Fields:

NameTypeDescription
scene-nameString (optional)Name of the scene the scene item belongs to. Defaults to the current scene.
itemStringScene Item name.
x-scaledoubleWidth scale factor.
y-scaledoubleHeight scale factor.
rotationdoubleSource item rotation (in degrees).

Response Items:

No additional response items.


SetSceneItemCrop

Sets the crop coordinates of the specified source item.

Request Fields:

NameTypeDescription
scene-nameString (optional)Name of the scene the scene item belongs to. Defaults to the current scene.
itemStringScene Item name.
topintPixel position of the top of the source item.
bottomintPixel position of the bottom of the source item.
leftintPixel position of the left of the source item.
rightintPixel position of the right of the source item.

Response Items:

No additional response items.


DeleteSceneItem

Deletes a scene item.

Request Fields:

NameTypeDescription
sceneString (optional)Name of the scene the scene item belongs to. Defaults to the current scene.
itemObjectScene item to delete (required)
item.nameStringScene Item name (prefer id, including both is acceptable).
item.idintScene Item ID.

Response Items:

No additional response items.


AddSceneItem

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

Request Fields:

NameTypeDescription
sceneNameStringName of the scene to create the scene item in
sourceNameStringName of the source to be added
setVisibleboolean (optional)Whether to make the sceneitem visible on creation or not. Default true

Response Items:

NameTypeDescription
itemIdintNumerical ID of the created scene item

DuplicateSceneItem

Duplicates a scene item.

Request Fields:

NameTypeDescription
fromSceneString (optional)Name of the scene to copy the item from. Defaults to the current scene.
toSceneString (optional)Name of the scene to create the item in. Defaults to the current scene.
itemObjectScene Item to duplicate from the source scene (required)
item.nameStringScene Item name (prefer id, including both is acceptable).
item.idintScene Item ID.

Response Items:

NameTypeDescription
sceneStringName of the scene where the new item was created
itemObjectNew item info
item.idintNew item ID
item.nameStringNew item name

Scenes

SetCurrentScene

Switch to the specified scene.

Request Fields:

NameTypeDescription
scene-nameStringName of the scene to switch to.

Response Items:

No additional response items.


GetCurrentScene

Get the current scene’s name and source items.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
nameStringName of the currently active scene.
sourcesArray<SceneItem>Ordered list of the current scene’s source items.

GetSceneList

Get a list of scenes in the currently active profile.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
current-sceneStringName of the currently active scene.
scenesArray<Scene>Ordered list of the current profile’s scenes (See GetCurrentScene for more information).

CreateScene

Create a new scene scene.

Request Fields:

NameTypeDescription
sceneNameStringName of the scene to create.

Response Items:

No additional response items.


ReorderSceneItems

Changes the order of scene items in the requested scene.

Request Fields:

NameTypeDescription
sceneString (optional)Name of the scene to reorder (defaults to current).
itemsArray<Object>Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene
items.*.idint (optional)Id of a specific scene item. Unique on a scene by scene basis.
items.*.nameString (optional)Name of a scene item. Sufficiently unique if no scene items share sources within the scene.

Response Items:

No additional response items.


SetSceneTransitionOverride

Set a scene to use a specific transition override.

Request Fields:

NameTypeDescription
sceneNameStringName of the scene to switch to.
transitionNameStringName of the transition to use.
transitionDurationint (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

Remove any transition override on a scene.

Request Fields:

NameTypeDescription
sceneNameStringName of the scene to switch to.

Response Items:

No additional response items.


GetSceneTransitionOverride

Get the current scene transition override.

Request Fields:

NameTypeDescription
sceneNameStringName of the scene to switch to.

Response Items:

NameTypeDescription
transitionNameStringName of the current overriding transition. Empty string if no override is set.
transitionDurationintTransition duration. -1 if no override is set.

Streaming

GetStreamingStatus

Get current streaming and recording status.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
streamingbooleanCurrent streaming status.
recordingbooleanCurrent recording status.
recording-pausedbooleanIf recording is paused.
virtualcambooleanCurrent virtual cam status.
preview-onlybooleanAlways false. Retrocompatibility with OBSRemote.
stream-timecodeString (optional)Time elapsed since streaming started (only present if currently streaming).
rec-timecodeString (optional)Time elapsed since recording started (only present if currently recording).
virtualcam-timecodeString (optional)Time elapsed since virtual cam started (only present if virtual cam currently active).

StartStopStreaming

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

Request Fields:

No specified parameters.

Response Items:

No additional response items.


StartStreaming

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

Request Fields:

NameTypeDescription
streamObject (optional)Special stream configuration. Note: these won’t be saved to OBS’ configuration.
stream.typeString (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.metadataObject (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.settingsObject (optional)Settings for the stream.
stream.settings.serverString (optional)The publish URL.
stream.settings.keyString (optional)The publish key of the stream.
stream.settings.use_authboolean (optional)Indicates whether authentication should be used when connecting to the streaming server.
stream.settings.usernameString (optional)If authentication is enabled, the username for the streaming server. Ignored if use_auth is not set to true.
stream.settings.passwordString (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

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

Request Fields:

No specified parameters.

Response Items:

No additional response items.


SetStreamSettings

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:

NameTypeDescription
typeStringThe type of streaming service configuration, usually rtmp_custom or rtmp_common.
settingsObjectThe actual settings of the stream.
settings.serverString (optional)The publish URL.
settings.keyString (optional)The publish key.
settings.use_authboolean (optional)Indicates whether authentication should be used when connecting to the streaming server.
settings.usernameString (optional)The username for the streaming service.
settings.passwordString (optional)The password for the streaming service.
savebooleanPersist the settings to disk.

Response Items:

No additional response items.


GetStreamSettings

Get the current streaming server settings.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
typeStringThe type of streaming service configuration. Possible values: ‘rtmp_custom’ or ‘rtmp_common’.
settingsObjectStream settings object.
settings.serverStringThe publish URL.
settings.keyStringThe publish key of the stream.
settings.use_authbooleanIndicates whether authentication should be used when connecting to the streaming server.
settings.usernameStringThe username to use when accessing the streaming server. Only present if use_auth is true.
settings.passwordStringThe password to use when accessing the streaming server. Only present if use_auth is true.

SaveStreamSettings

Save the current streaming server settings to disk.

Request Fields:

No specified parameters.

Response Items:

No additional response items.


SendCaptions

Send the provided text as embedded CEA-608 caption data.

Request Fields:

NameTypeDescription
textStringCaptions text

Response Items:

No additional response items.


Studio Mode

GetStudioModeStatus

Indicates if Studio Mode is currently enabled.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
studio-modebooleanIndicates if Studio Mode is enabled.

GetPreviewScene

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:

NameTypeDescription
nameStringThe name of the active preview scene.
sourcesArray<SceneItem>

SetPreviewScene

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

Request Fields:

NameTypeDescription
scene-nameStringThe name of the scene to preview.

Response Items:

No additional response items.


TransitionToProgram

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

Request Fields:

NameTypeDescription
with-transitionObject (optional)Change the active transition before switching scenes. Defaults to the active transition.
with-transition.nameStringName of the transition.
with-transition.durationint (optional)Transition duration (in milliseconds).

Response Items:

No additional response items.


EnableStudioMode

Enables Studio Mode.

Request Fields:

No specified parameters.

Response Items:

No additional response items.


DisableStudioMode

Disables Studio Mode.

Request Fields:

No specified parameters.

Response Items:

No additional response items.


ToggleStudioMode

Toggles Studio Mode (depending on the current state of studio mode).

Request Fields:

No specified parameters.

Response Items:

No additional response items.


Transitions

GetTransitionList

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

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
current-transitionStringName of the currently active transition.
transitionsArray<Object>List of transitions.
transitions.*.nameStringName of the transition.

GetCurrentTransition

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

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
nameStringName of the selected transition.
durationint (optional)Transition duration (in milliseconds) if supported by the transition.

SetCurrentTransition

Set the active transition.

Request Fields:

NameTypeDescription
transition-nameStringThe name of the transition.

Response Items:

No additional response items.


SetTransitionDuration

Set the duration of the currently selected transition if supported.

Request Fields:

NameTypeDescription
durationintDesired duration of the transition (in milliseconds).

Response Items:

No additional response items.


GetTransitionDuration

Get the duration of the currently selected transition if supported.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
transition-durationintDuration of the current transition (in milliseconds).

GetTransitionPosition

Get the position of the current transition.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
positiondoublecurrent transition position. This value will be between 0.0 and 1.0. Note: Transition returns 1.0 when not active.

GetTransitionSettings

Get the current settings of a transition

Request Fields:

NameTypeDescription
transitionNameStringTransition name

Response Items:

NameTypeDescription
transitionSettingsObjectCurrent transition settings

SetTransitionSettings

Change the current settings of a transition

Request Fields:

NameTypeDescription
transitionNameStringTransition name
transitionSettingsObjectTransition settings (they can be partial)

Response Items:

NameTypeDescription
transitionSettingsObjectUpdated transition settings

ReleaseTBar

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

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:

NameTypeDescription
positiondoubleT-Bar position. This value must be between 0.0 and 1.0.
releaseboolean (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

Get current virtual cam status.

Request Fields:

No specified parameters.

Response Items:

NameTypeDescription
isVirtualCambooleanCurrent virtual camera status.
virtualCamTimecodeString (optional)Time elapsed since virtual cam started (only present if virtual cam currently active).

StartStopVirtualCam

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

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

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

Request Fields:

No specified parameters.

Response Items:

No additional response items.


标签:Added,06,Items,29,scene,source,2021,optional,Response
来源: https://blog.csdn.net/n1234567896/article/details/118326166