From 10fdb8a4f069381bf49634b475b87e8af88c3ca8 Mon Sep 17 00:00:00 2001 From: Github Actions <> Date: Tue, 27 Apr 2021 01:39:26 +0000 Subject: [PATCH] docs(ci): Update generated docs - 6160c29 [skip ci] --- docs/generated/protocol.md | 346 ++++++++++++++++++++++++++++++++++++- 1 file changed, 337 insertions(+), 9 deletions(-) diff --git a/docs/generated/protocol.md b/docs/generated/protocol.md index 33e3f60b..049a7198 100644 --- a/docs/generated/protocol.md +++ b/docs/generated/protocol.md @@ -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, + "availableRequests": array, + "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(optional), + "eventBlacklist": array(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(optional), + "eventBlacklist": array(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