mirror of
https://github.com/Palakis/obs-websocket.git
synced 2024-08-30 18:12:16 +00:00
docs(ci): Update generated docs - 6160c29 [skip ci]
This commit is contained in:
Github Actions
parent
6160c292ef
commit
10fdb8a4f0
@ -20,6 +20,7 @@ obs-websocket provides a feature-rich RPC communication protocol, giving access
|
||||
- [Connecting to obs-websocket](#connecting-to-obs-websocket)
|
||||
- [Connection steps](#connection-steps)
|
||||
- [Creating an authentication string](#creating-an-authentication-string)
|
||||
- [Status and close codes](#status-and-close-codes)
|
||||
- [Base message types](#message-types)
|
||||
- [Hello](#hello)
|
||||
- [Identify](#identify)
|
||||
@ -78,8 +79,8 @@ For this guide, we'll be using `supersecretpassword` as the password.
|
||||
The `authentication` object in `Hello` looks like this (example):
|
||||
```json
|
||||
{
|
||||
"challenge": "ztTBnnuqrqaKDzRM3xcVdbYm",
|
||||
"salt": "PZVbYpvAnZut2SS6JNJytDm9"
|
||||
"challenge": "+IxH4CnCiqpX1rM9scsNynZzbOe4KhDeYcTNS3PDaeY=",
|
||||
"salt": "lM1GncleQOaCu9lT1yeUZhFYnqhsLLP1G5lAGo3ixaI="
|
||||
}
|
||||
```
|
||||
|
||||
@ -91,44 +92,371 @@ To generate the authentication string, follow these steps:
|
||||
|
||||
For more info on how to create the `authentication` string, refer to the obs-websocket client libraries listed on the [README](README.md).
|
||||
|
||||
### Status and Close Codes
|
||||
These are the enumeration definitions for various codes used by obs-websocket.
|
||||
|
||||
#### RequestStatus Enum
|
||||
```cpp
|
||||
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,
|
||||
};
|
||||
```
|
||||
|
||||
#### WebsocketCloseCode Enum
|
||||
```cpp
|
||||
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,
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
## Message Types
|
||||
The following message types are the base message types which may be sent to and from obs-websocket.
|
||||
|
||||
**Every** message sent from the obs-websocket server or client must contain these fields, known as the base object:
|
||||
```
|
||||
{
|
||||
"messageType": string
|
||||
}
|
||||
```
|
||||
|
||||
### Hello
|
||||
- Sent from: obs-websocket
|
||||
- Sent to: Freshly connected websocket client
|
||||
- Description:
|
||||
- Description: First message sent from the server immediately on client connection. Contains authentication information if auth is required. Also contains RPC version for version negotiation.
|
||||
|
||||
**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.
|
||||
|
||||
**Example Messages:**
|
||||
Authentication is required
|
||||
```json
|
||||
{
|
||||
"messageType": "Hello",
|
||||
"websocketVersion": "5.0.0",
|
||||
"rpcVersion": 3,
|
||||
"availableRequests": ["GetVersion"],
|
||||
"availableEvents": ["Exiting"],
|
||||
"authentication": {
|
||||
"challenge": "+IxH4CnCiqpX1rM9scsNynZzbOe4KhDeYcTNS3PDaeY=",
|
||||
"salt": "lM1GncleQOaCu9lT1yeUZhFYnqhsLLP1G5lAGo3ixaI="
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Authentication is not required
|
||||
```json
|
||||
{
|
||||
"messageType": "Hello",
|
||||
"websocketVersion": "5.0.0",
|
||||
"rpcVersion": 3,
|
||||
"availableRequests": ["GetVersion"],
|
||||
"availableEvents": ["Exiting"]
|
||||
}
|
||||
```
|
||||
|
||||
### Identify
|
||||
- Sent from: Freshly connected websocket client
|
||||
- Sent to: obs-websocket
|
||||
- Description:
|
||||
- Description: Response to `Hello` message, should contain authentication string if authentication is required, along with PubSub subscriptions and other session parameters.
|
||||
|
||||
**Additional Base Object Fields:**
|
||||
```
|
||||
{
|
||||
"rpcVersion": number,
|
||||
"authentication": string(optional),
|
||||
"ignoreInvalidMessages": bool(optional) = false,
|
||||
"ignoreNonFatalRequestChecks": 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.
|
||||
- When `ignoreInvalidMessages` is true, the socket will not be closed for `WebsocketCloseCode` `MessageDecodeError`, `UnknownMessageType`, or `RequestMissingRequestId`. 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 except those specified will be sent to the client.
|
||||
- Only `eventWhitelist` or `eventBlacklist` may be provided. If both are provided, the connection will be closed with `WebsocketCloseCode::InvalidIdentifyParameter`.
|
||||
|
||||
**Example Message:**
|
||||
```json
|
||||
{
|
||||
"messageType": "Identify",
|
||||
"rpcVersion": 3,
|
||||
"authentication": "Dj6cLS+jrNA0HpCArRg0Z/Fc+YHdt2FQfAvgD1mip6Y=",
|
||||
"eventWhitelist": ["Exiting"]
|
||||
}
|
||||
```
|
||||
|
||||
### Identified
|
||||
- Sent from: obs-websocket
|
||||
- Sent to: Freshly identified client
|
||||
- Description:
|
||||
- Description: The identify request was received and validated, and the connection is now ready for normal operation.
|
||||
|
||||
**Additional Base Object Fields:**
|
||||
```
|
||||
{
|
||||
"negotiatedRpcVersion": number
|
||||
}
|
||||
```
|
||||
- If rpc version negotiation succeeds, the server determines the RPC version to be used and gives it to the client as `negotiatedRpcVersion`
|
||||
|
||||
**Example Message:**
|
||||
```json
|
||||
{
|
||||
"messageType": "Identified",
|
||||
"negotiatedRpcVersion": 3
|
||||
}
|
||||
```
|
||||
|
||||
### Reidentify
|
||||
- Sent from: Identified client
|
||||
- Sent to: obs-websocket
|
||||
- Description:
|
||||
- Description: Sent at any time after initial identification to update the provided session parameters.
|
||||
|
||||
**Additional Base Object Fields:**
|
||||
```
|
||||
{
|
||||
"ignoreInvalidMessages": bool(optional),
|
||||
"ignoreNonFatalRequestChecks": bool(optional),
|
||||
"eventWhitelist": array<string>(optional),
|
||||
"eventBlacklist": array<string>(optional)
|
||||
}
|
||||
```
|
||||
- Only the listed parameters may be changed by `Reidentify` after initial identification. To change a parameter not listed, you must reconnect to the obs-websocket server.
|
||||
|
||||
### Event
|
||||
- Sent from: obs-websocket
|
||||
- Sent to: All subscribed and identified clients
|
||||
- Description:
|
||||
- Description: An event coming from OBS has occured. Eg scene switched, source muted.
|
||||
|
||||
**Additional Base Object Fields:**
|
||||
```
|
||||
{
|
||||
"eventType": string,
|
||||
"eventData": object(optional)
|
||||
}
|
||||
```
|
||||
|
||||
### Request
|
||||
- Sent from: Identified client
|
||||
- Sent to: obs-websocket
|
||||
- Description:
|
||||
- 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:**
|
||||
```json
|
||||
{
|
||||
"messageType": "Request",
|
||||
"requestType": "SetCurrentScene",
|
||||
"requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
|
||||
"requestData": {
|
||||
"sceneName": "Scene 12"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### RequestResponse
|
||||
- Sent from: obs-websocket
|
||||
- Sent to: Identified client which made the request
|
||||
- Description:
|
||||
- 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)
|
||||
}
|
||||
```
|
||||
- The `requestType` and `requestId` are simply mirrors of what was sent by the client.
|
||||
|
||||
`requestStatus` object:
|
||||
```
|
||||
{
|
||||
"result": bool,
|
||||
"code": number,
|
||||
"comment": string(optional)
|
||||
}
|
||||
```
|
||||
- `result` is true if the request resulted in `RequestStatus::Success`. False if otherwise.
|
||||
- `code` is a [`RequestStatus`](#requeststatus-enum) code.
|
||||
- `comment` may be provided by the server on errors to offer further details on why a request failed.
|
||||
|
||||
**Example Messages:**
|
||||
Successful Response
|
||||
```json
|
||||
{
|
||||
"messageType": "RequestResponse",
|
||||
"requestType": "SetCurrentScene",
|
||||
"requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
|
||||
"requestStatus": {
|
||||
"result": true,
|
||||
"code": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Failure Response
|
||||
```json
|
||||
{
|
||||
"messageType": "RequestResponse",
|
||||
"requestType": "SetCurrentScene",
|
||||
"requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
|
||||
"requestStatus": {
|
||||
"result": false,
|
||||
"code": 608,
|
||||
"comment": "Parameter: sceneName"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### RequestBatch
|
||||
- Sent from: Identified client
|
||||
|
||||
Loading…
Reference in New Issue
Block a user