|
|
|
|
@ -1,38 +1,82 @@
|
|
|
|
|
# obs-websocket 4.9.0 protocol reference
|
|
|
|
|
# obs-websocket 5.0.0 protocol reference
|
|
|
|
|
|
|
|
|
|
# General Introduction
|
|
|
|
|
Messages are exchanged between the client and the server as JSON objects.
|
|
|
|
|
This protocol is based on the original OBS Remote protocol created by Bill Hamilton, with new commands specific to OBS Studio. 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.**
|
|
|
|
|
## General Introduction
|
|
|
|
|
obs-websocket provides a feature-rich RPC communication protocol, giving access to much of OBS's feature set. This document contains everything you should know in order to make a connection and use obs-websocket's functionality to the fullest.
|
|
|
|
|
|
|
|
|
|
`obs-websocket` uses SHA256 to transmit credentials.
|
|
|
|
|
|
|
|
|
|
A request for [`GetAuthRequired`](#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.
|
|
|
|
|
## Table of Contents
|
|
|
|
|
- [Connecting to obs-websocket](#connecting_to_obs-websocket)
|
|
|
|
|
- [Connection steps](#connecting_steps)
|
|
|
|
|
- [Creating an authentication string](#connecting_authentication_string)
|
|
|
|
|
- [Base message types](#message_types)
|
|
|
|
|
- [Hello](#basemessage_hello)
|
|
|
|
|
- [Identify](#basemessage_identify)
|
|
|
|
|
- [Identified](#basemessage_identified)
|
|
|
|
|
- [Reidentify](#basemessage_reidentify)
|
|
|
|
|
- [Event](#basemessage_event)
|
|
|
|
|
- [Request](#basemessage_request)
|
|
|
|
|
- [RequestResponse](#basemessage_requestresponse)
|
|
|
|
|
- [RequestBatch](#basemessage_requestbatch)
|
|
|
|
|
- [RequestBatchResponse](#basemessage_requestbatchresponse)
|
|
|
|
|
- [Requests](#requests)
|
|
|
|
|
- [Events](#events)
|
|
|
|
|
|
|
|
|
|
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`](#authenticate) request.
|
|
|
|
|
|
|
|
|
|
Pseudo Code Example:
|
|
|
|
|
```
|
|
|
|
|
password = "supersecretpassword"
|
|
|
|
|
challenge = "ztTBnnuqrqaKDzRM3xcVdbYm"
|
|
|
|
|
salt = "PZVbYpvAnZut2SS6JNJytDm9"
|
|
|
|
|
## Connecting to obs-websocket {connecting_to_obs-websocket}
|
|
|
|
|
Here's info on how to connect to obs-websocket
|
|
|
|
|
|
|
|
|
|
secret_string = password + salt
|
|
|
|
|
secret_hash = binary_sha256(secret_string)
|
|
|
|
|
secret = base64_encode(secret_hash)
|
|
|
|
|
### Connection steps {connecting_steps}
|
|
|
|
|
- Step 1
|
|
|
|
|
|
|
|
|
|
auth_response_string = secret + challenge
|
|
|
|
|
auth_response_hash = binary_sha256(auth_response_string)
|
|
|
|
|
auth_response = base64_encode(auth_response_hash)
|
|
|
|
|
```
|
|
|
|
|
### Creating an authentication string {connecting_authentication_string}
|
|
|
|
|
- Start by
|
|
|
|
|
|
|
|
|
|
You can also refer to any of the client libraries listed on the [README](README.md) for examples of how to authenticate.
|
|
|
|
|
|
|
|
|
|
## Message Types {message_types}
|
|
|
|
|
The following message types (`messageType`) are the base message types which may be sent to and from obs-websocket. Sending a message with a `messageType` that is not recognized to the obs-websocket server will result in your connection being closed with `WebsocketCloseCode::UnknownMessageType`.
|
|
|
|
|
|
|
|
|
|
### Hello {basemessage_hello}
|
|
|
|
|
- Sent from: obs-websocket
|
|
|
|
|
- Sent to: Freshly connected websocket client
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### Identify {basemessage_identify}
|
|
|
|
|
- Sent from: Freshly connected websocket client
|
|
|
|
|
- Sent to: obs-websocket
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### Identified {basemessage_event}
|
|
|
|
|
- Sent from: obs-websocket
|
|
|
|
|
- Sent to: Freshly identified client
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### Reidentify {basemessage_reidentify}
|
|
|
|
|
- Sent from: Identified client
|
|
|
|
|
- Sent to: obs-websocket
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### Event {basemessage_event}
|
|
|
|
|
- Sent from: obs-websocket
|
|
|
|
|
- Sent to: All subscribed and identified clients
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### Request {basemessage_request}
|
|
|
|
|
- Sent from: Identified client
|
|
|
|
|
- Sent to: obs-websocket
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### RequestResponse {basemessage_requestresponse}
|
|
|
|
|
- Sent from: obs-websocket
|
|
|
|
|
- Sent to: Identified client which made the request
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### RequestBatch {basemessage_requestbatch}
|
|
|
|
|
- Sent from: Identified client
|
|
|
|
|
- Sent to: obs-websocket
|
|
|
|
|
- Description:
|
|
|
|
|
|
|
|
|
|
### RequestBatchResponse {basemessage_requestbatchresponse}
|
|
|
|
|
- Sent from: obs-websocket
|
|
|
|
|
- Sent to: Identified client which made the request
|
|
|
|
|
- Description:
|
Azure CI