Mirrored_Repos/obs-websocket
1
0
Fork 0
mirror of https://github.com/Palakis/obs-websocket.git synced 2024-08-30 18:12:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #555 from Palakis/fix/docs-updates

Browse Source 
Docs: Various docs improvements
This commit is contained in:
Stéphane Lepin 2020-07-15 14:59:52 +02:00 committed by GitHub
commit 5da6588ee6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 102 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
CONTRIBUTING.md
View File

@ -12,22 +12,22 @@ Localization happens on [Crowdin](https://crowdin.com/project/obs-websocket)
### Code Formatting Guidelines ### Code Formatting Guidelines
- Function and variable names: snake_case for C names, camelCase for C++ method names * Function and variable names: snake_case for C names, camelCase for C++ method names
- Request and Event names should use MixedCaps names * Request and Event names should use MixedCaps names
- Request and Event json properties should use camelCase. For more detailed info on property naming, see [Google's JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml) * Request and Event json properties should use camelCase. For more detailed info on property naming, see [Google's JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml)
- Code is indented with Tabs. Assume they are 8 columns wide * Code is indented with Tabs. Assume they are 8 columns wide
- 80 columns max code width. (Docs can be larger) * 80 columns max code width. (Docs can be larger)
- New and updated requests/events must always come with accompanying documentation comments (see existing protocol elements for examples). * New and updated requests/events must always come with accompanying documentation comments (see existing protocol elements for examples).
These are required to automatically generate the [protocol specification document](docs/generated/protocol.md). These are required to automatically generate the [protocol specification document](docs/generated/protocol.md).
### Code Best-Practices ### Code Best-Practices
- Favor return-early code and avoid wrapping huge portions of code in conditionals. As an example, this: * Favor return-early code and avoid wrapping huge portions of code in conditionals. As an example, this:
```cpp ```cpp
if (success) { if (success) {
return req->SendOKResponse(); return req->SendOKResponse();
@ -43,23 +43,23 @@ if (!success) {
return req->SendOKResponse(); return req->SendOKResponse();
``` ```
- Some example common response/request property names are: * Some example common response/request property names are:
- `sceneName` - The name of a scene * `sceneName` - The name of a scene
- `sourceName` - The name of a source * `sourceName` - The name of a source
- `fromScene` - From a scene - scene name * `fromScene` - From a scene - scene name
### Commit Guidelines ### Commit Guidelines
- Commits follow the 50/72 standard: * Commits follow the 50/72 standard:
- 50 characters max for the commit title (excluding scope name) * 50 characters max for the commit title (excluding scope name)
- One empty line after the title * One empty line after the title
- Description wrapped to 72 columns max width per line. * Description wrapped to 72 columns max width per line.
- Commit titles: * Commit titles:
- Use present tense * Use present tense
- Prefix the title with a "scope" name * Prefix the title with a "scope" name
- e.g: "CI: fix wrong behaviour when packaging for OS X" * e.g: "CI: fix wrong behaviour when packaging for OS X"
- Typical scopes: CI, General, Requests, Events, Server * Typical scopes: CI, General, Requests, Events, Server
**Example commit:** **Example commit:**
@ -73,10 +73,10 @@ transitions.
### Pull Requests ### Pull Requests
- Pull Requests must never be based off your fork's main branch (in this case, `4.x-current`). * Pull Requests must never be based off your fork's main branch (in this case, `4.x-current`).
- Start your work in a newly named branch based on the upstream main one (e.g.: `feature/cool-new-feature`, `bugfix/fix-palakis-mistakes`, ...) * Start your work in a newly named branch based on the upstream main one (e.g.: `feature/cool-new-feature`, `bugfix/fix-palakis-mistakes`, ...)
- Only open a pull request if you are ready to show off your work. * Only open a pull request if you are ready to show off your work.
- If your work is not done yet, but for any reason you need to PR it (like collecting discussions, testing with CI, getting testers), * If your work is not done yet, but for any reason you need to PR it (like collecting discussions, testing with CI, getting testers),
create it as a Draft Pull Request** (open the little arrow menu next to the "Create pull request" button, then select "Create draft pull request"). create it as a Draft Pull Request (open the little arrow menu next to the "Create pull request" button, then select "Create draft pull request").

4
docs/partials/introduction.md
View File

@ -2,7 +2,7 @@
# General Introduction # General Introduction
Messages are exchanged between the client and the server as JSON objects. 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. 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 # Authentication
`obs-websocket` uses SHA256 to transmit credentials. `obs-websocket` uses SHA256 to transmit credentials.
@ -32,3 +32,5 @@ auth_response_string = secret + challenge
auth_response_hash = binary_sha256(auth_response_string) auth_response_hash = binary_sha256(auth_response_string)
auth_response = base64_encode(auth_response_hash) auth_response = base64_encode(auth_response_hash)
``` ```
You can also refer to any of the client libraries listed on the [README](README.md) for examples of how to authenticate.

2
docs/partials/requestsHeader.md
View File

@ -6,6 +6,6 @@ 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: Once a request is sent, the server will return a JSON response with at least the following fields:
- `message-id` _String_: The client defined identifier specified in the request. - `message-id` _String_: The client defined identifier specified in the request.
- `status` _String_: Response status, will be one of the following: `ok`, `error` - `status` _String_: Response status, will be one of the following: `ok`, `error`
- `error` _String_: An error message accompanying an `error` status. - `error` _String (Optional)_: An error message accompanying an `error` status.
Additional information may be required/returned depending on the request type. See below for more information. Additional information may be required/returned depending on the request type. See below for more information.

35
src/WSEvents.cpp
View File

@ -465,6 +465,8 @@ void WSEvents::OnSceneChange() {
* The scene list has been modified. * The scene list has been modified.
* Scenes have been added, removed, or renamed. * Scenes have been added, removed, or renamed.
* *
* Note: This event is not fired when the scenes are reordered.
*
* @api events * @api events
* @name ScenesChanged * @name ScenesChanged
* @category scenes * @category scenes
@ -756,7 +758,7 @@ void WSEvents::OnExit() {
} }
/** /**
* Emit every 2 seconds. * Emitted every 2 seconds when stream is active.
* *
* @return {boolean} `streaming` Current streaming state. * @return {boolean} `streaming` Current streaming state.
* @return {boolean} `recording` Current recording state. * @return {boolean} `recording` Current recording state.
@ -863,6 +865,7 @@ void WSEvents::StreamStatus() {
* @api events * @api events
* @name Heartbeat * @name Heartbeat
* @category general * @category general
* @since v0.3
*/ */
void WSEvents::Heartbeat() { void WSEvents::Heartbeat() {
@ -1427,7 +1430,7 @@ void WSEvents::OnSourceFilterOrderChanged(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaPlaying * @name MediaPlaying
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaPlaying(void* param, calldata_t* data) { void WSEvents::OnMediaPlaying(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1448,7 +1451,7 @@ void WSEvents::OnMediaPlaying(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaPaused * @name MediaPaused
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaPaused(void* param, calldata_t* data) { void WSEvents::OnMediaPaused(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1469,7 +1472,7 @@ void WSEvents::OnMediaPaused(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaRestarted * @name MediaRestarted
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaRestarted(void* param, calldata_t* data) { void WSEvents::OnMediaRestarted(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1490,7 +1493,7 @@ void WSEvents::OnMediaRestarted(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaStopped * @name MediaStopped
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaStopped(void* param, calldata_t* data) { void WSEvents::OnMediaStopped(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1511,7 +1514,7 @@ void WSEvents::OnMediaStopped(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaNext * @name MediaNext
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaNext(void* param, calldata_t* data) { void WSEvents::OnMediaNext(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1532,7 +1535,7 @@ void WSEvents::OnMediaNext(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaPrevious * @name MediaPrevious
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaPrevious(void* param, calldata_t* data) { void WSEvents::OnMediaPrevious(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1553,7 +1556,7 @@ void WSEvents::OnMediaPrevious(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaStarted * @name MediaStarted
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaStarted(void* param, calldata_t* data) { void WSEvents::OnMediaStarted(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1574,7 +1577,7 @@ void WSEvents::OnMediaStarted(void* param, calldata_t* data) {
* @api events * @api events
* @name MediaEnded * @name MediaEnded
* @category media * @category media
* @since 4.9.0 * @since unreleased
*/ */
void WSEvents::OnMediaEnded(void* param, calldata_t* data) { void WSEvents::OnMediaEnded(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param); auto self = reinterpret_cast<WSEvents*>(param);
@ -1585,7 +1588,7 @@ void WSEvents::OnMediaEnded(void* param, calldata_t* data) {
} }
/** /**
* Scene items have been reordered. * Scene items within a scene have been reordered.
* *
* @return {String} `scene-name` Name of the scene where items have been reordered. * @return {String} `scene-name` Name of the scene where items have been reordered.
* @return {Array<Object>} `scene-items` Ordered list of scene items * @return {Array<Object>} `scene-items` Ordered list of scene items
@ -1628,7 +1631,7 @@ void WSEvents::OnSceneReordered(void* param, calldata_t* data) {
} }
/** /**
* An item has been added to the current scene. * A scene item has been added to a scene.
* *
* @return {String} `scene-name` Name of the scene. * @return {String} `scene-name` Name of the scene.
* @return {String} `item-name` Name of the item added to the scene. * @return {String} `item-name` Name of the item added to the scene.
@ -1661,7 +1664,7 @@ void WSEvents::OnSceneItemAdd(void* param, calldata_t* data) {
} }
/** /**
* An item has been removed from the current scene. * A scene item has been removed from a scene.
* *
* @return {String} `scene-name` Name of the scene. * @return {String} `scene-name` Name of the scene.
* @return {String} `item-name` Name of the item removed from the scene. * @return {String} `item-name` Name of the item removed from the scene.
@ -1694,7 +1697,7 @@ void WSEvents::OnSceneItemDelete(void* param, calldata_t* data) {
} }
/** /**
* An item's visibility has been toggled. * A scene item's visibility has been toggled.
* *
* @return {String} `scene-name` Name of the scene. * @return {String} `scene-name` Name of the scene.
* @return {String} `item-name` Name of the item in the scene. * @return {String} `item-name` Name of the item in the scene.
@ -1732,7 +1735,7 @@ void WSEvents::OnSceneItemVisibilityChanged(void* param, calldata_t* data) {
} }
/** /**
* An item's locked status has been toggled. * A scene item's locked status has been toggled.
* *
* @return {String} `scene-name` Name of the scene. * @return {String} `scene-name` Name of the scene.
* @return {String} `item-name` Name of the item in the scene. * @return {String} `item-name` Name of the item in the scene.
@ -1770,7 +1773,7 @@ void WSEvents::OnSceneItemLockChanged(void* param, calldata_t* data) {
} }
/** /**
* An item's transform has been changed. * A scene item's transform has been changed.
* *
* @return {String} `scene-name` Name of the scene. * @return {String} `scene-name` Name of the scene.
* @return {String} `item-name` Name of the item in the scene. * @return {String} `item-name` Name of the item in the scene.
@ -1921,7 +1924,7 @@ void WSEvents::OnStudioModeSwitched(bool checked) {
} }
/** /**
* A custom broadcast message was received * A custom broadcast message, sent by the server, requested by one of the websocket clients.
* *
* @return {String} `realm` Identifier provided by the sender * @return {String} `realm` Identifier provided by the sender
* @return {Object} `data` User-defined data * @return {Object} `data` User-defined data

11
src/WSRequestHandler_General.cpp
View File

@ -171,6 +171,7 @@ RpcResponse WSRequestHandler::Authenticate(const RpcRequest& request) {
* @name SetHeartbeat * @name SetHeartbeat
* @category general * @category general
* @since 4.3.0 * @since 4.3.0
* @deprecated Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0.
*/ */
RpcResponse WSRequestHandler::SetHeartbeat(const RpcRequest& request) { RpcResponse WSRequestHandler::SetHeartbeat(const RpcRequest& request) {
if (!request.hasField("enable")) { if (!request.hasField("enable")) {
@ -231,7 +232,7 @@ RpcResponse WSRequestHandler::GetFilenameFormatting(const RpcRequest& request) {
/** /**
* Get OBS stats (almost the same info as provided in OBS' stats window) * Get OBS stats (almost the same info as provided in OBS' stats window)
* *
* @return {OBSStats} `stats` OBS stats * @return {OBSStats} `stats` [OBS stats](#obsstats)
* *
* @api requests * @api requests
* @name GetStats * @name GetStats
@ -319,12 +320,12 @@ RpcResponse WSRequestHandler::GetVideoInfo(const RpcRequest& request) {
/** /**
* Open a projector window or create a projector on a monitor. Requires OBS v24.0.4 or newer. * Open a projector window or create a projector on a monitor. Requires OBS v24.0.4 or newer.
* *
* @param {String (Optional)} `type` Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive). * @param {String (Optional)} `type` Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive).
* @param {int (Optional)} `monitor` Monitor to open the projector on. If -1 or omitted, opens a window. * @param {int (Optional)} `monitor` Monitor to open the projector on. If -1 or omitted, opens a window.
* @param {String (Optional)} `geometry` Size and position of the projector window (only if monitor is -1). Encoded in Base64 using Qt's geometry encoding (https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors. * @param {String (Optional)} `geometry` Size and position of the projector window (only if monitor is -1). Encoded in Base64 using [Qt's geometry encoding](https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors.
* @param {String (Optional)} `name` Name of the source or scene to be displayed (ignored for other projector types). * @param {String (Optional)} `name` Name of the source or scene to be displayed (ignored for other projector types).
* *
* @api requests * @api requests
* @name OpenProjector * @name OpenProjector
* @category general * @category general

22
src/WSRequestHandler_MediaControl.cpp
View File

@ -51,7 +51,7 @@ QString getSourceMediaState(obs_source_t *source)
* @api requests * @api requests
* @name PlayPauseMedia * @name PlayPauseMedia
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::PlayPauseMedia(const RpcRequest& request) { RpcResponse WSRequestHandler::PlayPauseMedia(const RpcRequest& request) {
if ((!request.hasField("sourceName")) || (!request.hasField("playPause"))) { if ((!request.hasField("sourceName")) || (!request.hasField("playPause"))) {
@ -81,7 +81,7 @@ RpcResponse WSRequestHandler::PlayPauseMedia(const RpcRequest& request) {
* @api requests * @api requests
* @name RestartMedia * @name RestartMedia
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::RestartMedia(const RpcRequest& request) { RpcResponse WSRequestHandler::RestartMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -110,7 +110,7 @@ RpcResponse WSRequestHandler::RestartMedia(const RpcRequest& request) {
* @api requests * @api requests
* @name StopMedia * @name StopMedia
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::StopMedia(const RpcRequest& request) { RpcResponse WSRequestHandler::StopMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -139,7 +139,7 @@ RpcResponse WSRequestHandler::StopMedia(const RpcRequest& request) {
* @api requests * @api requests
* @name NextMedia * @name NextMedia
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::NextMedia(const RpcRequest& request) { RpcResponse WSRequestHandler::NextMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -168,7 +168,7 @@ RpcResponse WSRequestHandler::NextMedia(const RpcRequest& request) {
* @api requests * @api requests
* @name PreviousMedia * @name PreviousMedia
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::PreviousMedia(const RpcRequest& request) { RpcResponse WSRequestHandler::PreviousMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -200,7 +200,7 @@ RpcResponse WSRequestHandler::PreviousMedia(const RpcRequest& request) {
* @api requests * @api requests
* @name GetMediaDuration * @name GetMediaDuration
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) { RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -232,7 +232,7 @@ RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) {
* @api requests * @api requests
* @name GetMediaTime * @name GetMediaTime
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) { RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -263,7 +263,7 @@ RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
* @api requests * @api requests
* @name SetMediaTime * @name SetMediaTime
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) { RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) {
if (!request.hasField("sourceName") || !request.hasField("timestamp")) { if (!request.hasField("sourceName") || !request.hasField("timestamp")) {
@ -295,7 +295,7 @@ RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) {
* @api requests * @api requests
* @name ScrubMedia * @name ScrubMedia
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::ScrubMedia(const RpcRequest& request) { RpcResponse WSRequestHandler::ScrubMedia(const RpcRequest& request) {
if (!request.hasField("sourceName") || !request.hasField("timeOffset")) { if (!request.hasField("sourceName") || !request.hasField("timeOffset")) {
@ -332,7 +332,7 @@ RpcResponse WSRequestHandler::ScrubMedia(const RpcRequest& request) {
* @api requests * @api requests
* @name GetMediaState * @name GetMediaState
* @category media control * @category media control
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::GetMediaState(const RpcRequest& request) { RpcResponse WSRequestHandler::GetMediaState(const RpcRequest& request) {
if (!request.hasField("sourceName")) { if (!request.hasField("sourceName")) {
@ -366,7 +366,7 @@ RpcResponse WSRequestHandler::GetMediaState(const RpcRequest& request) {
* @api requests * @api requests
* @name GetMediaSourcesList * @name GetMediaSourcesList
* @category sources * @category sources
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::GetMediaSourcesList(const RpcRequest& request) RpcResponse WSRequestHandler::GetMediaSourcesList(const RpcRequest& request)
{ {

8
src/WSRequestHandler_Outputs.cpp
View File

@ -71,7 +71,7 @@ RpcResponse findOutputOrFail(const RpcRequest& request, std::function<RpcRespons
return request.failed("specified output doesn't exist"); return request.failed("specified output doesn't exist");
} }
return callback(output); return callback(output);
} }
/** /**
@ -129,6 +129,8 @@ RpcResponse WSRequestHandler::GetOutputInfo(const RpcRequest& request)
/** /**
* Start an output * Start an output
* *
* 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.
*
* @param {String} `outputName` Output name * @param {String} `outputName` Output name
* *
* @api requests * @api requests
@ -157,6 +159,8 @@ RpcResponse WSRequestHandler::StartOutput(const RpcRequest& request)
/** /**
* Stop an output * Stop an output
* *
* 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.
*
* @param {String} `outputName` Output name * @param {String} `outputName` Output name
* @param {boolean (optional)} `force` Force stop (default: false) * @param {boolean (optional)} `force` Force stop (default: false)
* *
@ -171,7 +175,7 @@ RpcResponse WSRequestHandler::StopOutput(const RpcRequest& request)
if (!obs_output_active(output)) { if (!obs_output_active(output)) {
return request.failed("output not active"); return request.failed("output not active");
} }
bool forceStop = obs_data_get_bool(request.parameters(), "force"); bool forceStop = obs_data_get_bool(request.parameters(), "force");
if (forceStop) { if (forceStop) {
obs_output_force_stop(output); obs_output_force_stop(output);

5
src/WSRequestHandler_Profiles.cpp
View File

@ -4,7 +4,7 @@
/** /**
* Set the currently active profile. * Set the currently active profile.
* *
* @param {String} `profile-name` Name of the desired profile. * @param {String} `profile-name` Name of the desired profile.
* *
* @api requests * @api requests
@ -29,7 +29,7 @@ RpcResponse WSRequestHandler::SetCurrentProfile(const RpcRequest& request) {
/** /**
* Get the name of the current profile. * Get the name of the current profile.
* *
* @return {String} `profile-name` Name of the currently active profile. * @return {String} `profile-name` Name of the currently active profile.
* *
* @api requests * @api requests
@ -49,6 +49,7 @@ RpcResponse WSRequestHandler::GetCurrentProfile(const RpcRequest& request) {
* Get a list of available profiles. * Get a list of available profiles.
* *
* @return {Array<Object>} `profiles` List of available profiles. * @return {Array<Object>} `profiles` List of available profiles.
* @return {String} `profiles.*.profile-name` Filter name
* *
* @api requests * @api requests
* @name ListProfiles * @name ListProfiles

2
src/WSRequestHandler_Recording.cpp
View File

@ -43,7 +43,7 @@ RpcResponse WSRequestHandler::GetRecordingStatus(const RpcRequest& request) {
} }
/** /**
* Toggle recording on or off. * Toggle recording on or off (depending on the current recording state).
* *
* @api requests * @api requests
* @name StartStopRecording * @name StartStopRecording

2
src/WSRequestHandler_ReplayBuffer.cpp
View File

@ -23,7 +23,7 @@ RpcResponse WSRequestHandler::GetReplayBufferStatus(const RpcRequest& request) {
} }
/** /**
* Toggle the Replay Buffer on/off. * Toggle the Replay Buffer on/off (depending on the current state of the replay buffer).
* *
* @api requests * @api requests
* @name StartStopReplayBuffer * @name StartStopReplayBuffer

3
src/WSRequestHandler_SceneCollections.cpp
View File

@ -22,7 +22,7 @@ RpcResponse WSRequestHandler::SetCurrentSceneCollection(const RpcRequest& reques
return request.failed("invalid request parameters"); return request.failed("invalid request parameters");
} }
// TODO : Check if specified profile exists and if changing is allowed // TODO : Check if specified collection exists and if changing is allowed
obs_frontend_set_current_scene_collection(sceneCollection.toUtf8()); obs_frontend_set_current_scene_collection(sceneCollection.toUtf8());
return request.success(); return request.success();
} }
@ -51,6 +51,7 @@ RpcResponse WSRequestHandler::GetCurrentSceneCollection(const RpcRequest& reques
* List available scene collections * List available scene collections
* *
* @return {Array<String>} `scene-collections` Scene collections list * @return {Array<String>} `scene-collections` Scene collections list
* @return {String} `scene-collections.*.sc-name` Scene collection name
* *
* @api requests * @api requests
* @name ListSceneCollections * @name ListSceneCollections

1
src/WSRequestHandler_SceneItems.cpp
View File

@ -408,7 +408,6 @@ RpcResponse WSRequestHandler::ResetSceneItem(const RpcRequest& request) {
* @name SetSceneItemRender * @name SetSceneItemRender
* @category scene items * @category scene items
* @since 0.3 * @since 0.3
* @deprecated Since 4.3.0. Prefer the use of SetSceneItemProperties.
*/ */
RpcResponse WSRequestHandler::SetSceneItemRender(const RpcRequest& request) { RpcResponse WSRequestHandler::SetSceneItemRender(const RpcRequest& request) {
if (!request.hasField("source") || if (!request.hasField("source") ||

24
src/WSRequestHandler_Scenes.cpp
View File

@ -36,7 +36,7 @@ RpcResponse WSRequestHandler::SetCurrentScene(const RpcRequest& request) {
/** /**
* Get the current scene's name and source items. * Get the current scene's name and source items.
* *
* @return {String} `name` Name of the currently active scene. * @return {String} `name` Name of the currently active scene.
* @return {Array<SceneItem>} `sources` Ordered list of the current scene's source items. * @return {Array<SceneItem>} `sources` Ordered list of the current scene's source items.
* *
@ -58,7 +58,7 @@ RpcResponse WSRequestHandler::GetCurrentScene(const RpcRequest& request) {
/** /**
* Get a list of scenes in the currently active profile. * Get a list of scenes in the currently active profile.
* *
* @return {String} `current-scene` Name of the currently active scene. * @return {String} `current-scene` Name of the currently active scene.
* @return {Array<Scene>} `scenes` Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information). * @return {Array<Scene>} `scenes` Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information).
* *
@ -109,8 +109,8 @@ RpcResponse WSRequestHandler::CreateScene(const RpcRequest& request) {
* *
* @param {String (optional)} `scene` Name of the scene to reorder (defaults to current). * @param {String (optional)} `scene` Name of the scene to reorder (defaults to current).
* @param {Array<Scene>} `items` Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene * @param {Array<Scene>} `items` Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene
* @param {int (optional)} `items[].id` Id of a specific scene item. Unique on a scene by scene basis. * @param {int (optional)} `items.*.id` Id of a specific scene item. Unique on a scene by scene basis.
* @param {String (optional)} `items[].name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene. * @param {String (optional)} `items.*.name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene.
* *
* @api requests * @api requests
* @name ReorderSceneItems * @name ReorderSceneItems
@ -184,7 +184,7 @@ RpcResponse WSRequestHandler::ReorderSceneItems(const RpcRequest& request) {
* @api requests * @api requests
* @name SetSceneTransitionOverride * @name SetSceneTransitionOverride
* @category scenes * @category scenes
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& request) { RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& request) {
if (!request.hasField("sceneName") || !request.hasField("transitionName")) { if (!request.hasField("sceneName") || !request.hasField("transitionName")) {
@ -196,12 +196,12 @@ RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& reque
if (!source) { if (!source) {
return request.failed("requested scene does not exist"); return request.failed("requested scene does not exist");
} }
enum obs_source_type sourceType = obs_source_get_type(source); enum obs_source_type sourceType = obs_source_get_type(source);
if (sourceType != OBS_SOURCE_TYPE_SCENE) { if (sourceType != OBS_SOURCE_TYPE_SCENE) {
return request.failed("requested scene is invalid"); return request.failed("requested scene is invalid");
} }
QString transitionName = obs_data_get_string(request.parameters(), "transitionName"); QString transitionName = obs_data_get_string(request.parameters(), "transitionName");
if (!Utils::GetTransitionFromName(transitionName)) { if (!Utils::GetTransitionFromName(transitionName)) {
return request.failed("requested transition does not exist"); return request.failed("requested transition does not exist");
@ -218,7 +218,7 @@ RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& reque
obs_frontend_get_transition_duration() obs_frontend_get_transition_duration()
); );
} }
return request.success(); return request.success();
} }
@ -230,7 +230,7 @@ RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& reque
* @api requests * @api requests
* @name RemoveSceneTransitionOverride * @name RemoveSceneTransitionOverride
* @category scenes * @category scenes
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& request) { RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& request) {
if (!request.hasField("sceneName")) { if (!request.hasField("sceneName")) {
@ -242,7 +242,7 @@ RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& re
if (!source) { if (!source) {
return request.failed("requested scene does not exist"); return request.failed("requested scene does not exist");
} }
enum obs_source_type sourceType = obs_source_get_type(source); enum obs_source_type sourceType = obs_source_get_type(source);
if (sourceType != OBS_SOURCE_TYPE_SCENE) { if (sourceType != OBS_SOURCE_TYPE_SCENE) {
return request.failed("requested scene is invalid"); return request.failed("requested scene is invalid");
@ -266,7 +266,7 @@ RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& re
* @api requests * @api requests
* @name GetSceneTransitionOverride * @name GetSceneTransitionOverride
* @category scenes * @category scenes
* @since 4.9.0 * @since unreleased
*/ */
RpcResponse WSRequestHandler::GetSceneTransitionOverride(const RpcRequest& request) { RpcResponse WSRequestHandler::GetSceneTransitionOverride(const RpcRequest& request) {
if (!request.hasField("sceneName")) { if (!request.hasField("sceneName")) {
@ -278,7 +278,7 @@ RpcResponse WSRequestHandler::GetSceneTransitionOverride(const RpcRequest& reque
if (!source) { if (!source) {
return request.failed("requested scene does not exist"); return request.failed("requested scene does not exist");
} }
enum obs_source_type sourceType = obs_source_get_type(source); enum obs_source_type sourceType = obs_source_get_type(source);
if (sourceType != OBS_SOURCE_TYPE_SCENE) { if (sourceType != OBS_SOURCE_TYPE_SCENE) {
return request.failed("requested scene is invalid"); return request.failed("requested scene is invalid");

18
src/WSRequestHandler_Sources.cpp
View File

@ -23,7 +23,7 @@ bool isTextFreeType2Source(const QString& sourceKind)
* *
* @return {Array<Object>} `sources` Array of sources * @return {Array<Object>} `sources` Array of sources
* @return {String} `sources.*.name` Unique source name * @return {String} `sources.*.name` Unique source name
* @return {String} `sources.*.typeId` Non-unique source internal type (a.k.a type id) * @return {String} `sources.*.typeId` Non-unique source internal type (a.k.a kind)
* @return {String} `sources.*.type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" * @return {String} `sources.*.type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"
* *
* @api requests * @api requests
@ -382,7 +382,7 @@ RpcResponse WSRequestHandler::GetAudioActive(const RpcRequest& request)
/** /**
* Sets (aka rename) the name of a source. Also works with scenes since scenes are technically sources in OBS. * Sets (aka rename) the name of a source. Also works with scenes since scenes are technically sources in OBS.
* *
* Note: If the new name already exists as a source, OBS will automatically modify the name to not interfere. * Note: If the new name already exists as a source, obs-websocket will return an error.
* *
* @param {String} `sourceName` Source name. * @param {String} `sourceName` Source name.
* @param {String} `newName` New source name. * @param {String} `newName` New source name.
@ -415,7 +415,7 @@ RpcResponse WSRequestHandler::SetSourceName(const RpcRequest& request)
return request.success(); return request.success();
} else { } else {
return request.failed("a source with that newSourceName already exists"); return request.failed("a source with that name already exists");
} }
} }
@ -596,8 +596,8 @@ RpcResponse WSRequestHandler::SetSourceSettings(const RpcRequest& request)
* *
* @return {String} `source` Source name. * @return {String} `source` Source name.
* @return {String} `align` Text Alignment ("left", "center", "right"). * @return {String} `align` Text Alignment ("left", "center", "right").
* @return {int} `bk-color` Background color. * @return {int} `bk_color` Background color.
* @return {int} `bk-opacity` Background opacity (0-100). * @return {int} `bk_opacity` Background opacity (0-100).
* @return {boolean} `chatlog` Chat log. * @return {boolean} `chatlog` Chat log.
* @return {int} `chatlog_lines` Chat log lines. * @return {int} `chatlog_lines` Chat log lines.
* @return {int} `color` Text color. * @return {int} `color` Text color.
@ -656,8 +656,8 @@ RpcResponse WSRequestHandler::GetTextGDIPlusProperties(const RpcRequest& request
* *
* @param {String} `source` Name of the source. * @param {String} `source` Name of the source.
* @param {String (optional)} `align` Text Alignment ("left", "center", "right"). * @param {String (optional)} `align` Text Alignment ("left", "center", "right").
* @param {int (optional)} `bk-color` Background color. * @param {int (optional)} `bk_color` Background color.
* @param {int (optional)} `bk-opacity` Background opacity (0-100). * @param {int (optional)} `bk_opacity` Background opacity (0-100).
* @param {boolean (optional)} `chatlog` Chat log. * @param {boolean (optional)} `chatlog` Chat log.
* @param {int (optional)} `chatlog_lines` Chat log lines. * @param {int (optional)} `chatlog_lines` Chat log lines.
* @param {int (optional)} `color` Text color. * @param {int (optional)} `color` Text color.
@ -1013,7 +1013,7 @@ RpcResponse WSRequestHandler::SetTextFreetype2Properties(const RpcRequest& reque
* @name GetBrowserSourceProperties * @name GetBrowserSourceProperties
* @category sources * @category sources
* @since 4.1.0 * @since 4.1.0
* @deprecated Since 4.8.0. Prefer the use of GetSourceSettings. * @deprecated Since 4.8.0. Prefer the use of GetSourceSettings. Will be removed in v5.0.0
*/ */
RpcResponse WSRequestHandler::GetBrowserSourceProperties(const RpcRequest& request) RpcResponse WSRequestHandler::GetBrowserSourceProperties(const RpcRequest& request)
{ {
@ -1055,7 +1055,7 @@ RpcResponse WSRequestHandler::GetBrowserSourceProperties(const RpcRequest& reque
* @api requests * @api requests
* @name SetBrowserSourceProperties * @name SetBrowserSourceProperties
* @category sources * @category sources
* @deprecated Since 4.8.0. Prefer the use of SetSourceSettings. * @deprecated Since 4.8.0. Prefer the use of SetSourceSettings. Will be removed in v5.0.0
* @since 4.1.0 * @since 4.1.0
*/ */
RpcResponse WSRequestHandler::SetBrowserSourceProperties(const RpcRequest& request) RpcResponse WSRequestHandler::SetBrowserSourceProperties(const RpcRequest& request)

3
src/WSRequestHandler_Streaming.cpp
View File

@ -43,7 +43,7 @@ RpcResponse WSRequestHandler::GetStreamingStatus(const RpcRequest& request) {
} }
/** /**
* Toggle streaming on or off. * Toggle streaming on or off (depending on the current stream state).
* *
* @api requests * @api requests
* @name StartStopStreaming * @name StartStopStreaming
@ -292,7 +292,6 @@ RpcResponse WSRequestHandler::SaveStreamSettings(const RpcRequest& request) {
/** /**
* Send the provided text as embedded CEA-608 caption data. * Send the provided text as embedded CEA-608 caption data.
* As of OBS Studio 23.1, captions are not yet available on Linux.
* *
* @param {String} `text` Captions text * @param {String} `text` Captions text
* *

2
src/WSRequestHandler_StudioMode.cpp
View File

@ -166,7 +166,7 @@ RpcResponse WSRequestHandler::DisableStudioMode(const RpcRequest& request) {
} }
/** /**
* Toggles Studio Mode. * Toggles Studio Mode (depending on the current state of studio mode).
* *
* @api requests * @api requests
* @name ToggleStudioMode * @name ToggleStudioMode