Skip to content

Instantly share code, notes, and snippets.

@tt2468
Last active December 25, 2022 06:10
Show Gist options
  • Save tt2468/59390b99e7841b28f56dffb3dd622ec9 to your computer and use it in GitHub Desktop.
Save tt2468/59390b99e7841b28f56dffb3dd622ec9 to your computer and use it in GitHub Desktop.
obs-websocket v5.0.0 API

obs-websocket API v5.0.0

Redesign Objectives:

  • Abstraction of identification, events, requests, and batch requests into new messageType.
  • camelCase for all key names.
  • Conformity of request naming using similar terms like Get, Set, Get[x]List, Start[x], Toggle[x].
  • Conformity of OBS data key names like sourceName, sourceKind, sourceType, sceneName, sceneItemName.
  • Error code response system - integer corrosponds to type of error, with optional comment
  • Possible support for multiple message encoding options: JSON and MessagePack
  • PubSub system | Allow clients to specify which events they do or don't want to receive from OBS

Making the initial connection:

Following is a step by step instruction on how a connection would be made and authenticated.

  • Initial HTTP request made to obs-websocket server.
    • HTTP request headers used to set communication format. Format is default JSON. Example headers:
      • Content-Type: application/json
      • Content-Type: application/msgpack Not currently planned for v5.0.0.
  • Connection upgraded to websocket.
  • Websocket server sends Hello message to client specifying authentication requirement.
    • If authentication is not required, the client must send an Identify with any requested connection parameters.
    • If authentication is required, client emits Identify request with authentication string along with any requested connection parameters.
      • If authentication succeeds, the server will emit an Identified message, which signifies that the sent Identify message was valid.
      • If authentication fails, the connection will be closed by the server with code 4005.
      • If the Identify message's parameters were invalid, the connection will be closed by the server with code 4006.
  • Subscribed events will begin to be sent from the server, and the client may proceed to make requests.

Base Object Fields:

{
  "messageType": string
}

Message Type: Hello

  • Sent from: obs-websocket
  • Sent to: Freshly connected client
  • Description: First message sent from the server immediately on client connection. Contains authentication information if auth is required.

Additional Base Object Fields:

{
  "obsWebsocketVersion": string,
  "rpcVersion": number,
  "availableEvents": array<string>,
  "availableRequests": array<string>,
  "authentication": object(optional)
}
  • rpcVersion is a version number which gets incremented on each breaking change to the obs-websocket protocol. Its usage in this context is to provide the current rpc version that the server would like to use.

authentication object:

{
  "challenge": string,
  "salt": string
}

Example Messages:

Authentication is required

{
  "messageType": "Hello",
  "websocketVersion": "5.0.0",
  "rpcVersion": 3,
  "availableRequests": [],
  "availableEvents": [],
  "authentication": {
    "challenge": "+IxH4CnCiqpX1rM9scsNynZzbOe4KhDeYcTNS3PDaeY=",
    "salt": "lM1GncleQOaCu9lT1yeUZhFYnqhsLLP1G5lAGo3ixaI="
  }
}

Authentication is not required

{
  "messageType": "Hello",
  "websocketVersion": "5.0.0",
  "rpcVersion": 3,
  "availableRequests": [],
  "availableEvents": []
}

Message Type: Identify

  • Sent from: Freshly connected client
  • Sent to: obs-websocket
  • Description: Response to Hello message, should contain authentication data if authentication is required, along with PubSub subscriptions.

Additional Base Object Fields:

{
  "rpcVersion": number(optional),
  "authentication": string(optional),
  "ignoreInvalidMessages": bool(optional) = false,
  "ignoreNonFatalChecks": bool(optional) = false,
  "eventWhitelist": array<string>(optional),
  "eventBlacklist": array<string>(optional)
}
  • rpcVersion is the version number that the client would like the obs-websocket server to use. If the client's version is older than the server's, it sends its highest supported version. If the client's version is no longer supported by the server, the connection is closed with WebsocketCloseCode::UnsupportedProtocolVersion. The client may also support multiple versions, in which it can decide which version it wants to use on its own (Eg. the client is newer than the obs-websocket server.)
  • When ignoreInvalidMessages is true, the socket will not be closed for codes 4001, 4002, or 4007. Instead, the message will be logged and dropped.
  • When ignoreNonFatalRequestChecks is true, requests will ignore checks which are not critical to the function of the request. Eg calling DeleteScene when the target scene does not exist would still return RequestStatus::Success if this flag is enabled.
  • When eventWhitelist is specified, only the specified events will be sent to the client.
  • When eventBlacklist is specified, all events will be sent to the client except for the specified events.
  • Only eventWhitelist or eventBlacklist may be provided. If both are provided, the connection will be closed with code 4006.

Example Message:

{
  "messageType": "Identify",
  "authentication": "Dj6cLS+jrNA0HpCArRg0Z/Fc+YHdt2FQfAvgD1mip6Y=",
  "eventWhitelist": ["StreamStarted"]
}

Message Type: Identified

  • Sent from: obs-websocket
  • Sent to: Identified client
  • Description: The identify request was received and validated, and the connection is now ready.

Example Message:

{
  "messageType": "Identified",
  "negotiatedRpcVersion": number
}
  • If rpc version negotiation succeeds, the server determines the RPC version to be used and gives it to the client as negotiatedRpcVersion

Message Type: Event

  • Sent from: obs-websocket
  • Sent to: All identified clients that are subscribed
  • Description: An event coming from OBS has occured. Eg scene switched, source muted.

Additional Base Object Fields:

{
  "eventType": string,
  "eventData": object(optional)
}

Example Message:

{
  "messageType": "Event",
  "eventType": "SceneChanged",
  "eventData": {
    "fromScene": "Scene 1",
    "toScene": "Scene 2"
  }
}

Message Type: Request

  • Sent from: Identified client
  • Sent to: obs-websocket
  • Description: Client is making a request to obs-websocket. Eg get current scene, create source.

Additional Base Object Fields

{
  "requestType": string,
  "requestId": string,
  "requestData": object(optional),
  
}

Example Message:

{
  "messageType": "Request",
  "requestType": "SetSourceVolume",
  "requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
  "requestData": {
    "useDb": true,
    "volume": -101
  }
}

Message Type: RequestResponse

  • Sent from: obs-websocket
  • Sent to: Identified client which made the request
  • Description: obs-websocket is responding to a request coming from a client.

Additional Base Object Fields:

{
  "requestType": string,
  "requestId": string,
  "requestStatus": object,
  "responseData": object(optional)
}

requestStatus object:

{
  "result": bool,
  "code": number,
  "comment": string(optional)
}

Example Messages:

Successful Response

{
  "messageType": "RequestResponse",
  "requestType": "SetSourceVolume",
  "requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
  "requestStatus": {
    "result": true,
    "code": 100
  }
}

Failure Response

{
  "messageType": "RequestResponse",
  "requestType": "SetSourceVolume",
  "requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
  "requestStatus": {
    "result": false,
    "code": 402,
    "comment": "Parameter: volume"
  }
}

Message Type: RequestBatch

  • Sent from: Identified client
  • Sent to: obs-websocket
  • Description: Client is making a batch of requests for obs-websocket. Requests are processed serially by the server.

Additional Base Object Fields

{
  "requestId": string,
  "haltOnFailure": bool(optional)
  "requests": array<object>
}
  • Specifying haltOnFailure as true stops the processing of requests if one returns a failure. Returns only the processed requests in RequestBatchResponse.

Message Type: RequestBatchResponse

  • Sent from: obs-websocket
  • Sent to: Identified client which made the request
  • Description: obs-websocket is responding to a request batch coming from the client.

Additional Base Object Fields:

{
  "requestId": string,
  "results": array<object>
}

Request Response Status Codes

  • Sent in RequestResponse messages
enum RequestStatus: std::uint16_t {
	Unknown = 0,

	// For internal use to signify a successful parameter check
	NoError = 10,

	Success = 100,

	// The request is denied because the client is not authenticated
	AuthenticationMissing = 200,
	// Connection has already been authenticated (for modules utilizing a request to provide authentication)
	AlreadyAuthenticated = 201,
	// Authentication request was denied (for modules utilizing a request to provide authentication)
	AuthenticationDenied = 202,
	// The `requestType` field is missing from the request data
	RequestTypeMissing = 203,
	// The request type is invalid (does not exist)
	InvalidRequestType = 204,
	// Generic error code (comment is expected to be provided)
	GenericError = 205,

	// A required request parameter is missing
	MissingRequestParameter = 300,

	// Generic invalid request parameter message
	InvalidRequestParameter = 400,
	// A request parameter has the wrong data type
	InvalidRequestParameterDataType = 401,
	// A request parameter (float or int) is out of valid range
	RequestParameterOutOfRange = 402,
	// A request parameter (string or array) is empty and cannot be
	RequestParameterEmpty = 403,

	// An output is running and cannot be in order to perform the request (generic)
	OutputRunning = 500,
	// An output is not running and should be
	OutputNotRunning = 501,
	// Stream is running and cannot be
	StreamRunning = 502,
	// Stream is not running and should be
	StreamNotRunning = 503,
	// Record is running and cannot be
	RecordRunning = 504,
	// Record is not running and should be
	RecordNotRunning = 505,
	// Record is paused and cannot be
	RecordPaused = 506,
	// Replay buffer is running and cannot be
	ReplayBufferRunning = 507,
	// Replay buffer is not running and should be
	ReplayBufferNotRunning = 508,
	// Replay buffer is disabled and cannot be
	ReplayBufferDisabled = 509,
	// Studio mode is active and cannot be
	StudioModeActive = 510,
	// Studio mode is not active and should be
	StudioModeNotActive = 511,

	// The specified source (obs_source_t) was of the invalid type (Eg. input instead of scene)
	InvalidSourceType = 600,
	// The specified source (obs_source_t) was not found (generic for input, filter, transition, scene)
	SourceNotFound = 601,
	// The specified source (obs_source_t) already exists. Applicable to inputs, filters, transitions, scenes
	SourceAlreadyExists = 602,
	// The specified input (obs_source_t-OBS_SOURCE_TYPE_FILTER) was not found
	InputNotFound = 603,
	// The specified input (obs_source_t-OBS_SOURCE_TYPE_INPUT) had the wrong kind
	InvalidInputKind = 604,
	// The specified filter (obs_source_t-OBS_SOURCE_TYPE_FILTER) was not found
	FilterNotFound = 605,
	// The specified transition (obs_source_t-OBS_SOURCE_TYPE_TRANSITION) was not found
	TransitionNotFound = 606,
	// The specified transition (obs_source_t-OBS_SOURCE_TYPE_TRANSITION) does not support setting its position (transition is of fixed type)
	TransitionDurationFixed = 607,
	// The specified scene (obs_source_t-OBS_SOURCE_TYPE_SCENE), (obs_scene_t) was not found
	SceneNotFound = 608,
	// The specified scene item (obs_sceneitem_t) was not found
	SceneItemNotFound = 609,
	// The specified scene collection was not found
	SceneCollectionNotFound = 610,
	// The specified profile was not found
	ProfileNotFound = 611,
	// The specified output (obs_output_t) was not found
	OutputNotFound = 612,
	// The specified encoder (obs_encoder_t) was not found
	EncoderNotFound = 613,
	// The specified service (obs_service_t) was not found
	ServiceNotFound = 614,
	// The specified hotkey was not found
	HotkeyNotFound = 615,
	// The specified directory was not found
	DirectoryNotFound = 616,
	// The specified config item (obs_config_t) was not found. Could be section or parameter name.
	ConfigParameterNotFound = 617,
	// The specified property (obs_properties_t) was not found
	PropertyNotFound = 618

	// Processing the request failed unexpectedly
	RequestProcessingFailed = 700,
	// Starting the Output failed
	OutputStartFailed = 701,
	// Duplicating the scene item failed
	SceneItemDuplicationFailed = 702,
	// Rendering the screenshot failed
	ScreenshotRenderFailed = 703,
	// Encoding the screenshot failed
	ScreenshotEncodeFailed = 704,
	// Saving the screenshot failed
	ScreenshotSaveFailed = 705,
	// Creating the directory failed
	DirectoryCreationFailed = 706,
};

Websocket Close Codes

  • Sent on connection close by the obs-websocket server.
enum WebsocketCloseCode: std::uint16_t {
	UnknownReason = 4000,

	// The server was unable to decode the incoming websocket message
	MessageDecodeError = 4001,
	// The specified `messageType` was invalid
	UnknownMessageType = 4002,
	// The client sent a websocket message without first sending `Identify` message
	NotIdentified = 4003,
	// The client sent an `Identify` message while already identified
	AlreadyIdentified = 4004,
	// The authentication attempt (via `Identify`) failed
	AuthenticationFailed = 4005,
	// There was an invalid parameter the client's `Identify` message
	InvalidIdentifyParameter = 4006,
	// A `Request` or `RequestBatch` was missing its `requestId`
	RequestMissingRequestId = 4007,
	// The websocket session has been invalidated by the obs-websocket server.
	SessionInvalidated = 4008,
	// The server detected the usage of an old version of the obs-websocket protocol.
	UnsupportedProtocolVersion = 4009,
};
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment