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 branch '4.x-current' into enhancement/various-todos

Browse Source
This commit is contained in:
Stéphane Lepin 2020-07-15 15:02:00 +02:00 committed by GitHub
commit 2e32b7e299
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 295 additions and 253 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
- 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).
These are required to automatically generate the [protocol specification document](docs/generated/protocol.md).
* 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).
### 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
if (success) {
return req->SendOKResponse();
@ -43,23 +43,23 @@ if (!success) {
return req->SendOKResponse();
```
- Some example common response/request property names are:
- `sceneName` - The name of a scene
- `sourceName` - The name of a source
- `fromScene` - From a scene - scene name
* Some example common response/request property names are:
* `sceneName` - The name of a scene
* `sourceName` - The name of a source
* `fromScene` - From a scene - scene name
### Commit Guidelines
- Commits follow the 50/72 standard:
- 50 characters max for the commit title (excluding scope name)
- One empty line after the title
- Description wrapped to 72 columns max width per line.
* Commits follow the 50/72 standard:
* 50 characters max for the commit title (excluding scope name)
* One empty line after the title
* Description wrapped to 72 columns max width per line.
- Commit titles:
- Use present tense
- Prefix the title with a "scope" name
- e.g: "CI: fix wrong behaviour when packaging for OS X"
- Typical scopes: CI, General, Requests, Events, Server
* Commit titles:
* Use present tense
* Prefix the title with a "scope" name
* e.g: "CI: fix wrong behaviour when packaging for OS X"
* Typical scopes: CI, General, Requests, Events, Server
**Example commit:**
@ -73,10 +73,10 @@ transitions.
### Pull Requests
- 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`, ...)
* 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`, ...)
- 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),
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").
* 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").

217
docs/generated/comments.json
View File

@ -561,7 +561,7 @@
},
{
"subheads": [],
"description": "The scene list has been modified.\nScenes have been added, removed, or renamed.",
"description": "\n\nNote: This event is not fired when the scenes are reordered.",
"api": "events",
"name": "ScenesChanged",
"category": "scenes",
@ -588,7 +588,7 @@
"level": 2,
"text": "ScenesChanged"
},
"lead": "",
"lead": "The scene list has been modified. Scenes have been added, removed, or renamed.",
"type": "class",
"examples": []
},
@ -1190,7 +1190,7 @@
},
{
"subheads": [],
"description": "Emit every 2 seconds.",
"description": "Emitted every 2 seconds when stream is active.",
"return": [
"{boolean} `streaming` Current streaming state.",
"{boolean} `recording` Current recording state.",
@ -1730,6 +1730,7 @@
"api": "events",
"name": "Heartbeat",
"category": "general",
"since": "v0.3",
"returns": [
{
"type": "boolean",
@ -1804,6 +1805,12 @@
"description": "general"
}
],
"sinces": [
{
"name": "",
"description": "v0.3"
}
],
"heading": {
"level": 2,
"text": "Heartbeat"
@ -1814,7 +1821,7 @@
},
{
"subheads": [],
"description": "A custom broadcast message was received",
"description": "A custom broadcast message, sent by the server, requested by one of the websocket clients.",
"return": [
"{String} `realm` Identifier provided by the sender",
"{Object} `data` User-defined data"
@ -2574,7 +2581,7 @@
"api": "events",
"name": "MediaPlaying",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2602,7 +2609,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2623,7 +2630,7 @@
"api": "events",
"name": "MediaPaused",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2651,7 +2658,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2672,7 +2679,7 @@
"api": "events",
"name": "MediaRestarted",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2700,7 +2707,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2721,7 +2728,7 @@
"api": "events",
"name": "MediaStopped",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2749,7 +2756,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2770,7 +2777,7 @@
"api": "events",
"name": "MediaNext",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2798,7 +2805,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2819,7 +2826,7 @@
"api": "events",
"name": "MediaPrevious",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2847,7 +2854,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2868,7 +2875,7 @@
"api": "events",
"name": "MediaStarted",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2896,7 +2903,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2917,7 +2924,7 @@
"api": "events",
"name": "MediaEnded",
"category": "media",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -2945,7 +2952,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -2960,7 +2967,7 @@
"scene items": [
{
"subheads": [],
"description": "Scene items have been reordered.",
"description": "Scene items within a scene have been reordered.",
"return": [
"{String} `scene-name` Name of the scene where items have been reordered.",
"{Array<Object>} `scene-items` Ordered list of scene items",
@ -3021,7 +3028,7 @@
},
{
"subheads": [],
"description": "An item has been added to the current scene.",
"description": "A scene item has been added to a scene.",
"return": [
"{String} `scene-name` Name of the scene.",
"{String} `item-name` Name of the item added to the scene.",
@ -3076,7 +3083,7 @@
},
{
"subheads": [],
"description": "An item has been removed from the current scene.",
"description": "A scene item has been removed from a scene.",
"return": [
"{String} `scene-name` Name of the scene.",
"{String} `item-name` Name of the item removed from the scene.",
@ -3131,7 +3138,7 @@
},
{
"subheads": [],
"description": "An item's visibility has been toggled.",
"description": "A scene item's visibility has been toggled.",
"return": [
"{String} `scene-name` Name of the scene.",
"{String} `item-name` Name of the item in the scene.",
@ -3192,7 +3199,7 @@
},
{
"subheads": [],
"description": "An item's locked status has been toggled.",
"description": "A scene item's locked status has been toggled.",
"return": [
"{String} `scene-name` Name of the scene.",
"{String} `item-name` Name of the item in the scene.",
@ -3253,7 +3260,7 @@
},
{
"subheads": [],
"description": "An item's transform has been changed.",
"description": "A scene item's transform has been changed.",
"return": [
"{String} `scene-name` Name of the scene.",
"{String} `item-name` Name of the item in the scene.",
@ -3689,6 +3696,7 @@
"name": "SetHeartbeat",
"category": "general",
"since": "4.3.0",
"deprecated": "Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0.",
"params": [
{
"type": "boolean",
@ -3714,6 +3722,12 @@
"description": "4.3.0"
}
],
"deprecateds": [
{
"name": "",
"description": "Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0."
}
],
"heading": {
"level": 2,
"text": "SetHeartbeat"
@ -3807,7 +3821,7 @@
{
"subheads": [],
"description": "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",
"name": "GetStats",
"category": "general",
@ -3816,7 +3830,7 @@
{
"type": "OBSStats",
"name": "stats",
"description": "OBS stats"
"description": "[OBS stats](#obsstats)"
}
],
"names": [
@ -3989,9 +4003,9 @@
"subheads": [],
"description": "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).",
"{String (Optional)} `type` Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive).",
"{int (Optional)} `monitor` Monitor to open the projector on. If -1 or omitted, opens a window.",
"{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.",
"{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.",
"{String (Optional)} `name` Name of the source or scene to be displayed (ignored for other projector types)."
],
"api": "requests",
@ -4002,7 +4016,7 @@
{
"type": "String (Optional)",
"name": "type",
"description": "Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive)."
"description": "Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive)."
},
{
"type": "int (Optional)",
@ -4012,7 +4026,7 @@
{
"type": "String (Optional)",
"name": "geometry",
"description": "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."
"description": "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."
},
{
"type": "String (Optional)",
@ -4058,7 +4072,7 @@
"api": "requests",
"name": "PlayPauseMedia",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4086,7 +4100,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4104,7 +4118,7 @@
"api": "requests",
"name": "RestartMedia",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4127,7 +4141,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4145,7 +4159,7 @@
"api": "requests",
"name": "StopMedia",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4168,7 +4182,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4186,7 +4200,7 @@
"api": "requests",
"name": "NextMedia",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4209,7 +4223,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4227,7 +4241,7 @@
"api": "requests",
"name": "PreviousMedia",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4250,7 +4264,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4269,7 +4283,7 @@
"api": "requests",
"name": "GetMediaDuration",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "int",
@ -4299,7 +4313,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4318,7 +4332,7 @@
"api": "requests",
"name": "GetMediaTime",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "int",
@ -4348,7 +4362,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4369,7 +4383,7 @@
"api": "requests",
"name": "SetMediaTime",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4397,7 +4411,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4418,7 +4432,7 @@
"api": "requests",
"name": "ScrubMedia",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -4446,7 +4460,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4465,7 +4479,7 @@
"api": "requests",
"name": "GetMediaState",
"category": "media control",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -4495,7 +4509,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4520,7 +4534,7 @@
"api": "requests",
"name": "GetMediaSourcesList",
"category": "sources",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "Array<Object>",
@ -4558,7 +4572,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -4575,7 +4589,7 @@
"return": [
"{Array<Object>} `sources` Array of sources",
"{String} `sources.*.name` Unique source name",
"{String} `sources.*.typeId` Non-unique source internal type (a.k.a type id)",
"{String} `sources.*.typeId` Non-unique source internal type (a.k.a kind)",
"{String} `sources.*.type` Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\""
],
"api": "requests",
@ -4596,7 +4610,7 @@
{
"type": "String",
"name": "sources.*.typeId",
"description": "Non-unique source internal type (a.k.a type id)"
"description": "Non-unique source internal type (a.k.a kind)"
},
{
"type": "String",
@ -5069,7 +5083,7 @@
},
{
"subheads": [],
"description": "\n\nNote: If the new name already exists as a source, OBS will automatically modify the name to not interfere.",
"description": "\n\nNote: If the new name already exists as a source, obs-websocket will return an error.",
"param": [
"{String} `sourceName` Source name.",
"{String} `newName` New source name."
@ -5377,8 +5391,8 @@
"return": [
"{String} `source` Source name.",
"{String} `align` Text Alignment (\"left\", \"center\", \"right\").",
"{int} `bk-color` Background color.",
"{int} `bk-opacity` Background opacity (0-100).",
"{int} `bk_color` Background color.",
"{int} `bk_opacity` Background opacity (0-100).",
"{boolean} `chatlog` Chat log.",
"{int} `chatlog_lines` Chat log lines.",
"{int} `color` Text color.",
@ -5421,12 +5435,12 @@
},
{
"type": "int",
"name": "bk-color",
"name": "bk_color",
"description": "Background color."
},
{
"type": "int",
"name": "bk-opacity",
"name": "bk_opacity",
"description": "Background opacity (0-100)."
},
{
@ -5589,8 +5603,8 @@
"param": [
"{String} `source` Name of the source.",
"{String (optional)} `align` Text Alignment (\"left\", \"center\", \"right\").",
"{int (optional)} `bk-color` Background color.",
"{int (optional)} `bk-opacity` Background opacity (0-100).",
"{int (optional)} `bk_color` Background color.",
"{int (optional)} `bk_opacity` Background opacity (0-100).",
"{boolean (optional)} `chatlog` Chat log.",
"{int (optional)} `chatlog_lines` Chat log lines.",
"{int (optional)} `color` Text color.",
@ -5634,12 +5648,12 @@
},
{
"type": "int (optional)",
"name": "bk-color",
"name": "bk_color",
"description": "Background color."
},
{
"type": "int (optional)",
"name": "bk-opacity",
"name": "bk_opacity",
"description": "Background opacity (0-100)."
},
{
@ -6087,7 +6101,7 @@
"name": "GetBrowserSourceProperties",
"category": "sources",
"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",
"returns": [
{
"type": "String",
@ -6163,7 +6177,7 @@
"deprecateds": [
{
"name": "",
"description": "Since 4.8.0. Prefer the use of GetSourceSettings."
"description": "Since 4.8.0. Prefer the use of GetSourceSettings. Will be removed in v5.0.0"
}
],
"heading": {
@ -6192,7 +6206,7 @@
"api": "requests",
"name": "SetBrowserSourceProperties",
"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",
"params": [
{
@ -6261,7 +6275,7 @@
"deprecateds": [
{
"name": "",
"description": "Since 4.8.0. Prefer the use of SetSourceSettings."
"description": "Since 4.8.0. Prefer the use of SetSourceSettings. Will be removed in v5.0.0"
}
],
"sinces": [
@ -7120,7 +7134,7 @@
},
{
"subheads": [],
"description": "Start an output",
"description": "\n\nNote: 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",
"api": "requests",
"name": "StartOutput",
@ -7155,13 +7169,13 @@
"level": 2,
"text": "StartOutput"
},
"lead": "",
"lead": "Start an output",
"type": "class",
"examples": []
},
{
"subheads": [],
"description": "Stop an output",
"description": "\n\nNote: 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",
"{boolean (optional)} `force` Force stop (default: false)"
@ -7204,7 +7218,7 @@
"level": 2,
"text": "StopOutput"
},
"lead": "",
"lead": "Stop an output",
"type": "class",
"examples": []
}
@ -7295,7 +7309,10 @@
{
"subheads": [],
"description": "Get a list of available profiles.",
"return": "{Array<Object>} `profiles` List of available profiles.",
"return": [
"{Array<Object>} `profiles` List of available profiles.",
"{String} `profiles.*.profile-name` Filter name"
],
"api": "requests",
"name": "ListProfiles",
"category": "profiles",
@ -7305,6 +7322,11 @@
"type": "Array<Object>",
"name": "profiles",
"description": "List of available profiles."
},
{
"type": "String",
"name": "profiles.*.profile-name",
"description": "Filter name"
}
],
"names": [
@ -7392,7 +7414,7 @@
},
{
"subheads": [],
"description": "Toggle recording on or off.",
"description": "Toggle recording on or off (depending on the current recording state).",
"api": "requests",
"name": "StartStopRecording",
"category": "recording",
@ -7682,7 +7704,7 @@
},
{
"subheads": [],
"description": "Toggle the Replay Buffer on/off.",
"description": "Toggle the Replay Buffer on/off (depending on the current state of the replay buffer).",
"api": "requests",
"name": "StartStopReplayBuffer",
"category": "replay buffer",
@ -7899,7 +7921,10 @@
{
"subheads": [],
"description": "List available scene collections",
"return": "{Array<String>} `scene-collections` Scene collections list",
"return": [
"{Array<String>} `scene-collections` Scene collections list",
"{String} `scene-collections.*.sc-name` Scene collection name"
],
"api": "requests",
"name": "ListSceneCollections",
"category": "scene collections",
@ -7909,6 +7934,11 @@
"type": "Array<String>",
"name": "scene-collections",
"description": "Scene collections list"
},
{
"type": "String",
"name": "scene-collections.*.sc-name",
"description": "Scene collection name"
}
],
"names": [
@ -8465,7 +8495,6 @@
"name": "SetSceneItemRender",
"category": "scene items",
"since": "0.3",
"deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.",
"params": [
{
"type": "String (optional)",
@ -8501,12 +8530,6 @@
"description": "0.3"
}
],
"deprecateds": [
{
"name": "",
"description": "Since 4.3.0. Prefer the use of SetSceneItemProperties."
}
],
"heading": {
"level": 2,
"text": "SetSceneItemRender"
@ -9144,8 +9167,8 @@
"param": [
"{String (optional)} `scene` Name of the scene to reorder (defaults to current).",
"{Array<Scene>} `items` Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene",
"{int (optional)} `items[].id` Id of a specific scene item. Unique on a scene by scene basis.",
"{String (optional)} `items[].name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene."
"{int (optional)} `items.*.id` Id of a specific scene item. Unique on a scene by scene basis.",
"{String (optional)} `items.*.name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene."
],
"api": "requests",
"name": "ReorderSceneItems",
@ -9164,12 +9187,12 @@
},
{
"type": "int (optional)",
"name": "items[].id",
"name": "items.*.id",
"description": "Id of a specific scene item. Unique on a scene by scene basis."
},
{
"type": "String (optional)",
"name": "items[].name",
"name": "items.*.name",
"description": "Name of a scene item. Sufficiently unique if no scene items share sources within the scene."
}
],
@ -9210,7 +9233,7 @@
"api": "requests",
"name": "SetSceneTransitionOverride",
"category": "scenes",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -9243,7 +9266,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -9261,7 +9284,7 @@
"api": "requests",
"name": "RemoveSceneTransitionOverride",
"category": "scenes",
"since": "4.9.0",
"since": "unreleased",
"params": [
{
"type": "String",
@ -9284,7 +9307,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -9306,7 +9329,7 @@
"api": "requests",
"name": "GetSceneTransitionOverride",
"category": "scenes",
"since": "4.9.0",
"since": "unreleased",
"returns": [
{
"type": "String",
@ -9341,7 +9364,7 @@
"sinces": [
{
"name": "",
"description": "4.9.0"
"description": "unreleased"
}
],
"heading": {
@ -9423,7 +9446,7 @@
},
{
"subheads": [],
"description": "Toggle streaming on or off.",
"description": "Toggle streaming on or off (depending on the current stream state).",
"api": "requests",
"name": "StartStopStreaming",
"category": "streaming",
@ -9777,7 +9800,7 @@
},
{
"subheads": [],
"description": "Send the provided text as embedded CEA-608 caption data.\nAs of OBS Studio 23.1, captions are not yet available on Linux.",
"description": "Send the provided text as embedded CEA-608 caption data.",
"param": "{String} `text` Captions text",
"api": "requests",
"name": "SendCaptions",
@ -10072,7 +10095,7 @@
},
{
"subheads": [],
"description": "Toggles Studio Mode.",
"description": "Toggles Studio Mode (depending on the current state of studio mode).",
"api": "requests",
"name": "ToggleStudioMode",
"category": "studio mode",

120
docs/generated/protocol.md
View File

@ -4,7 +4,7 @@
# 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.
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
`obs-websocket` uses SHA256 to transmit credentials.
@ -35,6 +35,8 @@ auth_response_hash = binary_sha256(auth_response_string)
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.
@ -380,8 +382,9 @@ Indicates a scene change.
- Added in v0.3
The scene list has been modified.
Scenes have been added, removed, or renamed.
Note: This event is not fired when the scenes are reordered.
**Response Items:**
@ -616,7 +619,7 @@ _No additional response items._
- Added in v0.3
Emit every 2 seconds.
Emitted every 2 seconds when stream is active.
**Response Items:**
@ -799,7 +802,7 @@ _No additional response items._
### Heartbeat
- Added in v
- Added in vv0.3
Emitted every 2 seconds after enabling it by calling SetHeartbeat.
@ -828,7 +831,7 @@ Emitted every 2 seconds after enabling it by calling SetHeartbeat.
- Added in v4.7.0
A custom broadcast message was received
A custom broadcast message, sent by the server, requested by one of the websocket clients.
**Response Items:**
@ -1079,7 +1082,7 @@ Filters in a source have been reordered.
### MediaPlaying
- Added in v4.9.0
- Unreleased
@ -1098,7 +1101,7 @@ Note: This event is only emitted when something actively controls the media/VLC
### MediaPaused
- Added in v4.9.0
- Unreleased
@ -1117,7 +1120,7 @@ Note: This event is only emitted when something actively controls the media/VLC
### MediaRestarted
- Added in v4.9.0
- Unreleased
@ -1136,7 +1139,7 @@ Note: This event is only emitted when something actively controls the media/VLC
### MediaStopped
- Added in v4.9.0
- Unreleased
@ -1155,7 +1158,7 @@ Note: This event is only emitted when something actively controls the media/VLC
### MediaNext
- Added in v4.9.0
- Unreleased
@ -1174,7 +1177,7 @@ Note: This event is only emitted when something actively controls the media/VLC
### MediaPrevious
- Added in v4.9.0
- Unreleased
@ -1193,7 +1196,7 @@ Note: This event is only emitted when something actively controls the media/VLC
### MediaStarted
- Added in v4.9.0
- Unreleased
@ -1212,7 +1215,7 @@ Note: These events are emitted by the OBS sources themselves. For example when t
### MediaEnded
- Added in v4.9.0
- Unreleased
@ -1235,7 +1238,7 @@ Note: These events are emitted by the OBS sources themselves. For example when t
- Added in v4.0.0
Scene items have been reordered.
Scene items within a scene have been reordered.
**Response Items:**
@ -1254,7 +1257,7 @@ Scene items have been reordered.
- Added in v4.0.0
An item has been added to the current scene.
A scene item has been added to a scene.
**Response Items:**
@ -1272,7 +1275,7 @@ An item has been added to the current scene.
- Added in v4.0.0
An item has been removed from the current scene.
A scene item has been removed from a scene.
**Response Items:**
@ -1290,7 +1293,7 @@ An item has been removed from the current scene.
- Added in v4.0.0
An item's visibility has been toggled.
A scene item's visibility has been toggled.
**Response Items:**
@ -1309,7 +1312,7 @@ An item's visibility has been toggled.
- Added in v4.8.0
An item's locked status has been toggled.
A scene item's locked status has been toggled.
**Response Items:**
@ -1328,7 +1331,7 @@ An item's locked status has been toggled.
- Added in v4.6.0
An item's transform has been changed.
A scene item's transform has been changed.
**Response Items:**
@ -1424,7 +1427,7 @@ 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:
- `message-id` _String_: The client defined identifier specified in the request.
- `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.
@ -1500,6 +1503,7 @@ _No additional response items._
### SetHeartbeat
- **⚠️ Deprecated. Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0. ⚠️**
- Added in v4.3.0
@ -1573,7 +1577,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `stats` | _OBSStats_ | OBS stats |
| `stats` | _OBSStats_ | [OBS stats](#obsstats) |
---
@ -1638,9 +1642,9 @@ Open a projector window or create a projector on a monitor. Requires OBS v24.0.4
| Name | Type | Description |
| ---- | :---: | ------------|
| `type` | _String (Optional)_ | Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive). |
| `type` | _String (Optional)_ | Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive). |
| `monitor` | _int (Optional)_ | Monitor to open the projector on. If -1 or omitted, opens a window. |
| `geometry` | _String (Optional)_ | 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. |
| `geometry` | _String (Optional)_ | 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. |
| `name` | _String (Optional)_ | Name of the source or scene to be displayed (ignored for other projector types). |
@ -1655,7 +1659,7 @@ _No additional response items._
### PlayPauseMedia
- Added in v4.9.0
- Unreleased
Pause or play a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
@ -1676,7 +1680,7 @@ _No additional response items._
### RestartMedia
- Added in v4.9.0
- Unreleased
Restart a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
@ -1696,7 +1700,7 @@ _No additional response items._
### StopMedia
- Added in v4.9.0
- Unreleased
Stop a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
@ -1716,7 +1720,7 @@ _No additional response items._
### NextMedia
- Added in v4.9.0
- Unreleased
Skip to the next media item in the playlist. Supports only vlc media source (as of OBS v25.0.8)
@ -1736,7 +1740,7 @@ _No additional response items._
### PreviousMedia
- Added in v4.9.0
- Unreleased
Go to the previous media item in the playlist. Supports only vlc media source (as of OBS v25.0.8)
@ -1756,7 +1760,7 @@ _No additional response items._
### GetMediaDuration
- Added in v4.9.0
- Unreleased
Get the length of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
Note: For some reason, for the first 5 or so seconds that the media is playing, the total duration can be off by upwards of 50ms.
@ -1780,7 +1784,7 @@ Note: For some reason, for the first 5 or so seconds that the media is playing,
### GetMediaTime
- Added in v4.9.0
- Unreleased
Get the current timestamp of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
@ -1803,7 +1807,7 @@ Get the current timestamp of media in milliseconds. Supports ffmpeg and vlc medi
### SetMediaTime
- Added in v4.9.0
- Unreleased
Set the timestamp of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
@ -1824,7 +1828,7 @@ _No additional response items._
### ScrubMedia
- Added in v4.9.0
- Unreleased
Scrub media using a supplied offset. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
Note: Due to processing/network delays, this request is not perfect. The processing rate of this request has also not been tested.
@ -1846,7 +1850,7 @@ _No additional response items._
### GetMediaState
- Added in v4.9.0
- Unreleased
Get the current playing state of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
@ -1871,7 +1875,7 @@ Get the current playing state of a media source. Supports ffmpeg and vlc media s
### GetMediaSourcesList
- Added in v4.9.0
- Unreleased
List the media state of all media sources (vlc and media source)
@ -1908,7 +1912,7 @@ _No specified parameters._
| ---- | :---: | ------------|
| `sources` | _Array&lt;Object&gt;_ | Array of sources |
| `sources.*.name` | _String_ | Unique source name |
| `sources.*.typeId` | _String_ | Non-unique source internal type (a.k.a type id) |
| `sources.*.typeId` | _String_ | Non-unique source internal type (a.k.a kind) |
| `sources.*.type` | _String_ | Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" |
@ -2089,7 +2093,7 @@ Get the audio's active status of a specified source.
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.
**Request Fields:**
@ -2223,8 +2227,8 @@ Get the current properties of a Text GDI Plus source.
| ---- | :---: | ------------|
| `source` | _String_ | Source name. |
| `align` | _String_ | Text Alignment ("left", "center", "right"). |
| `bk-color` | _int_ | Background color. |
| `bk-opacity` | _int_ | Background opacity (0-100). |
| `bk_color` | _int_ | Background color. |
| `bk_opacity` | _int_ | Background opacity (0-100). |
| `chatlog` | _boolean_ | Chat log. |
| `chatlog_lines` | _int_ | Chat log lines. |
| `color` | _int_ | Text color. |
@ -2266,8 +2270,8 @@ Set the current properties of a Text GDI Plus source.
| ---- | :---: | ------------|
| `source` | _String_ | Name of the source. |
| `align` | _String (optional)_ | Text Alignment ("left", "center", "right"). |
| `bk-color` | _int (optional)_ | Background color. |
| `bk-opacity` | _int (optional)_ | Background opacity (0-100). |
| `bk_color` | _int (optional)_ | Background color. |
| `bk_opacity` | _int (optional)_ | Background opacity (0-100). |
| `chatlog` | _boolean (optional)_ | Chat log. |
| `chatlog_lines` | _int (optional)_ | Chat log lines. |
| `color` | _int (optional)_ | Text color. |
@ -2376,7 +2380,7 @@ _No additional response items._
### GetBrowserSourceProperties
- **⚠️ 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 ⚠️**
- Added in v4.1.0
@ -2408,7 +2412,7 @@ Get current properties for a Browser Source.
### SetBrowserSourceProperties
- **⚠️ 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 ⚠️**
- Added in v4.1.0
@ -2776,7 +2780,9 @@ Get information about a single output
- Added in v4.7.0
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.
**Request Fields:**
@ -2796,7 +2802,9 @@ _No additional response items._
- Added in v4.7.0
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.
**Request Fields:**
@ -2870,6 +2878,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `profiles` | _Array&lt;Object&gt;_ | List of available profiles. |
| `profiles.*.profile-name` | _String_ | Filter name |
---
@ -2903,7 +2912,7 @@ _No specified parameters._
- Added in v0.3
Toggle recording on or off.
Toggle recording on or off (depending on the current recording state).
**Request Fields:**
@ -3058,7 +3067,7 @@ _No specified parameters._
- Added in v4.2.0
Toggle the Replay Buffer on/off.
Toggle the Replay Buffer on/off (depending on the current state of the replay buffer).
**Request Fields:**
@ -3186,6 +3195,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `scene-collections` | _Array&lt;String&gt;_ | Scene collections list |
| `scene-collections.*.sc-name` | _String_ | Scene collection name |
---
@ -3336,7 +3346,6 @@ _No additional response items._
### SetSceneItemRender
- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️**
- Added in v0.3
@ -3607,8 +3616,8 @@ Changes the order of scene items in the requested scene.
| ---- | :---: | ------------|
| `scene` | _String (optional)_ | Name of the scene to reorder (defaults to current). |
| `items` | _Array&lt;Scene&gt;_ | Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene |
| `items[].id` | _int (optional)_ | Id of a specific scene item. Unique on a scene by scene basis. |
| `items[].name` | _String (optional)_ | Name of a scene item. Sufficiently unique if no scene items share sources within the scene. |
| `items.*.id` | _int (optional)_ | Id of a specific scene item. Unique on a scene by scene basis. |
| `items.*.name` | _String (optional)_ | Name of a scene item. Sufficiently unique if no scene items share sources within the scene. |
**Response Items:**
@ -3620,7 +3629,7 @@ _No additional response items._
### SetSceneTransitionOverride
- Added in v4.9.0
- Unreleased
Set a scene to use a specific transition override.
@ -3642,7 +3651,7 @@ _No additional response items._
### RemoveSceneTransitionOverride
- Added in v4.9.0
- Unreleased
Remove any transition override on a scene.
@ -3662,7 +3671,7 @@ _No additional response items._
### GetSceneTransitionOverride
- Added in v4.9.0
- Unreleased
Get the current scene transition override.
@ -3714,7 +3723,7 @@ _No specified parameters._
- Added in v0.3
Toggle streaming on or off.
Toggle streaming on or off (depending on the current stream state).
**Request Fields:**
@ -3849,7 +3858,6 @@ _No additional response items._
- Added in v4.6.0
Send the provided text as embedded CEA-608 caption data.
As of OBS Studio 23.1, captions are not yet available on Linux.
**Request Fields:**
@ -3991,7 +3999,7 @@ _No additional response items._
- Added in v4.1.0
Toggles Studio Mode.
Toggles Studio Mode (depending on the current state of studio mode).
**Request Fields:**

4
docs/partials/introduction.md
View File

@ -2,7 +2,7 @@
# 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.
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
`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 = 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:
- `message-id` _String_: The client defined identifier specified in the request.
- `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.

35
src/WSEvents.cpp
View File

@ -465,6 +465,8 @@ void WSEvents::OnSceneChange() {
* The scene list has been modified.
* Scenes have been added, removed, or renamed.
*
* Note: This event is not fired when the scenes are reordered.
*
* @api events
* @name ScenesChanged
* @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} `recording` Current recording state.
@ -863,6 +865,7 @@ void WSEvents::StreamStatus() {
* @api events
* @name Heartbeat
* @category general
* @since v0.3
*/
void WSEvents::Heartbeat() {
@ -1427,7 +1430,7 @@ void WSEvents::OnSourceFilterOrderChanged(void* param, calldata_t* data) {
* @api events
* @name MediaPlaying
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaPlaying(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1448,7 +1451,7 @@ void WSEvents::OnMediaPlaying(void* param, calldata_t* data) {
* @api events
* @name MediaPaused
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaPaused(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1469,7 +1472,7 @@ void WSEvents::OnMediaPaused(void* param, calldata_t* data) {
* @api events
* @name MediaRestarted
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaRestarted(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1490,7 +1493,7 @@ void WSEvents::OnMediaRestarted(void* param, calldata_t* data) {
* @api events
* @name MediaStopped
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaStopped(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1511,7 +1514,7 @@ void WSEvents::OnMediaStopped(void* param, calldata_t* data) {
* @api events
* @name MediaNext
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaNext(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1532,7 +1535,7 @@ void WSEvents::OnMediaNext(void* param, calldata_t* data) {
* @api events
* @name MediaPrevious
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaPrevious(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1553,7 +1556,7 @@ void WSEvents::OnMediaPrevious(void* param, calldata_t* data) {
* @api events
* @name MediaStarted
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaStarted(void* param, calldata_t* data) {
auto self = reinterpret_cast<WSEvents*>(param);
@ -1574,7 +1577,7 @@ void WSEvents::OnMediaStarted(void* param, calldata_t* data) {
* @api events
* @name MediaEnded
* @category media
* @since 4.9.0
* @since unreleased
*/
void WSEvents::OnMediaEnded(void* param, calldata_t* data) {
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 {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} `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} `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} `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} `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} `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 {Object} `data` User-defined data

11
src/WSRequestHandler_General.cpp
View File

@ -171,6 +171,7 @@ RpcResponse WSRequestHandler::Authenticate(const RpcRequest& request) {
* @name SetHeartbeat
* @category general
* @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) {
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)
*
* @return {OBSStats} `stats` OBS stats
* @return {OBSStats} `stats` [OBS stats](#obsstats)
*
* @api requests
* @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.
*
* @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 {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).
*
*
* @api requests
* @name OpenProjector
* @category general

22
src/WSRequestHandler_MediaControl.cpp
View File

@ -51,7 +51,7 @@ QString getSourceMediaState(obs_source_t *source)
* @api requests
* @name PlayPauseMedia
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::PlayPauseMedia(const RpcRequest& request) {
if ((!request.hasField("sourceName")) || (!request.hasField("playPause"))) {
@ -81,7 +81,7 @@ RpcResponse WSRequestHandler::PlayPauseMedia(const RpcRequest& request) {
* @api requests
* @name RestartMedia
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::RestartMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -110,7 +110,7 @@ RpcResponse WSRequestHandler::RestartMedia(const RpcRequest& request) {
* @api requests
* @name StopMedia
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::StopMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -139,7 +139,7 @@ RpcResponse WSRequestHandler::StopMedia(const RpcRequest& request) {
* @api requests
* @name NextMedia
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::NextMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -168,7 +168,7 @@ RpcResponse WSRequestHandler::NextMedia(const RpcRequest& request) {
* @api requests
* @name PreviousMedia
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::PreviousMedia(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -200,7 +200,7 @@ RpcResponse WSRequestHandler::PreviousMedia(const RpcRequest& request) {
* @api requests
* @name GetMediaDuration
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -232,7 +232,7 @@ RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) {
* @api requests
* @name GetMediaTime
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -263,7 +263,7 @@ RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
* @api requests
* @name SetMediaTime
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) {
if (!request.hasField("sourceName") || !request.hasField("timestamp")) {
@ -295,7 +295,7 @@ RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) {
* @api requests
* @name ScrubMedia
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::ScrubMedia(const RpcRequest& request) {
if (!request.hasField("sourceName") || !request.hasField("timeOffset")) {
@ -332,7 +332,7 @@ RpcResponse WSRequestHandler::ScrubMedia(const RpcRequest& request) {
* @api requests
* @name GetMediaState
* @category media control
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::GetMediaState(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
@ -366,7 +366,7 @@ RpcResponse WSRequestHandler::GetMediaState(const RpcRequest& request) {
* @api requests
* @name GetMediaSourcesList
* @category sources
* @since 4.9.0
* @since unreleased
*/
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 callback(output);
return callback(output);
}
/**
@ -129,6 +129,8 @@ RpcResponse WSRequestHandler::GetOutputInfo(const RpcRequest& request)
/**
* 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
*
* @api requests
@ -157,6 +159,8 @@ RpcResponse WSRequestHandler::StartOutput(const RpcRequest& request)
/**
* 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 {boolean (optional)} `force` Force stop (default: false)
*
@ -171,7 +175,7 @@ RpcResponse WSRequestHandler::StopOutput(const RpcRequest& request)
if (!obs_output_active(output)) {
return request.failed("output not active");
}
bool forceStop = obs_data_get_bool(request.parameters(), "force");
if (forceStop) {
obs_output_force_stop(output);

5
src/WSRequestHandler_Profiles.cpp
View File

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

1
src/WSRequestHandler_SceneCollections.cpp
View File

@ -57,6 +57,7 @@ RpcResponse WSRequestHandler::GetCurrentSceneCollection(const RpcRequest& reques
* List available scene collections
*
* @return {Array<String>} `scene-collections` Scene collections list
* @return {String} `scene-collections.*.sc-name` Scene collection name
*
* @api requests
* @name ListSceneCollections

1
src/WSRequestHandler_SceneItems.cpp
View File

@ -408,7 +408,6 @@ RpcResponse WSRequestHandler::ResetSceneItem(const RpcRequest& request) {
* @name SetSceneItemRender
* @category scene items
* @since 0.3
* @deprecated Since 4.3.0. Prefer the use of SetSceneItemProperties.
*/
RpcResponse WSRequestHandler::SetSceneItemRender(const RpcRequest& request) {
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.
*
*
* @return {String} `name` Name of the currently active scene.
* @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.
*
*
* @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).
*
@ -109,8 +109,8 @@ RpcResponse WSRequestHandler::CreateScene(const RpcRequest& request) {
*
* @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 {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 {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.
*
* @api requests
* @name ReorderSceneItems
@ -184,7 +184,7 @@ RpcResponse WSRequestHandler::ReorderSceneItems(const RpcRequest& request) {
* @api requests
* @name SetSceneTransitionOverride
* @category scenes
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& request) {
if (!request.hasField("sceneName") || !request.hasField("transitionName")) {
@ -196,12 +196,12 @@ RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& reque
if (!source) {
return request.failed("requested scene does not exist");
}
enum obs_source_type sourceType = obs_source_get_type(source);
if (sourceType != OBS_SOURCE_TYPE_SCENE) {
return request.failed("requested scene is invalid");
}
QString transitionName = obs_data_get_string(request.parameters(), "transitionName");
if (!Utils::GetTransitionFromName(transitionName)) {
return request.failed("requested transition does not exist");
@ -218,7 +218,7 @@ RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& reque
obs_frontend_get_transition_duration()
);
}
return request.success();
}
@ -230,7 +230,7 @@ RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& reque
* @api requests
* @name RemoveSceneTransitionOverride
* @category scenes
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& request) {
if (!request.hasField("sceneName")) {
@ -242,7 +242,7 @@ RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& re
if (!source) {
return request.failed("requested scene does not exist");
}
enum obs_source_type sourceType = obs_source_get_type(source);
if (sourceType != OBS_SOURCE_TYPE_SCENE) {
return request.failed("requested scene is invalid");
@ -266,7 +266,7 @@ RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& re
* @api requests
* @name GetSceneTransitionOverride
* @category scenes
* @since 4.9.0
* @since unreleased
*/
RpcResponse WSRequestHandler::GetSceneTransitionOverride(const RpcRequest& request) {
if (!request.hasField("sceneName")) {
@ -278,7 +278,7 @@ RpcResponse WSRequestHandler::GetSceneTransitionOverride(const RpcRequest& reque
if (!source) {
return request.failed("requested scene does not exist");
}
enum obs_source_type sourceType = obs_source_get_type(source);
if (sourceType != OBS_SOURCE_TYPE_SCENE) {
return request.failed("requested scene is invalid");

37
src/WSRequestHandler_Sources.cpp
View File

@ -23,7 +23,7 @@ bool isTextFreeType2Source(const QString& sourceKind)
*
* @return {Array<Object>} `sources` Array of sources
* @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"
*
* @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.
*
* 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} `newName` New source name.
@ -415,7 +415,7 @@ RpcResponse WSRequestHandler::SetSourceName(const RpcRequest& request)
return request.success();
} 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} `align` Text Alignment ("left", "center", "right").
* @return {int} `bk-color` Background color.
* @return {int} `bk-opacity` Background opacity (0-100).
* @return {int} `bk_color` Background color.
* @return {int} `bk_opacity` Background opacity (0-100).
* @return {boolean} `chatlog` Chat log.
* @return {int} `chatlog_lines` Chat log lines.
* @return {int} `color` Text color.
@ -656,8 +656,8 @@ RpcResponse WSRequestHandler::GetTextGDIPlusProperties(const RpcRequest& request
*
* @param {String} `source` Name of the source.
* @param {String (optional)} `align` Text Alignment ("left", "center", "right").
* @param {int (optional)} `bk-color` Background color.
* @param {int (optional)} `bk-opacity` Background opacity (0-100).
* @param {int (optional)} `bk_color` Background color.
* @param {int (optional)} `bk_opacity` Background opacity (0-100).
* @param {boolean (optional)} `chatlog` Chat log.
* @param {int (optional)} `chatlog_lines` Chat log lines.
* @param {int (optional)} `color` Text color.
@ -1013,7 +1013,7 @@ RpcResponse WSRequestHandler::SetTextFreetype2Properties(const RpcRequest& reque
* @name GetBrowserSourceProperties
* @category sources
* @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)
{
@ -1055,7 +1055,7 @@ RpcResponse WSRequestHandler::GetBrowserSourceProperties(const RpcRequest& reque
* @api requests
* @name SetBrowserSourceProperties
* @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
*/
RpcResponse WSRequestHandler::SetBrowserSourceProperties(const RpcRequest& request)
@ -1623,7 +1623,7 @@ RpcResponse WSRequestHandler::SetAudioMonitorType(const RpcRequest& request)
* Clients can specify `width` and `height` parameters to receive scaled pictures. Aspect ratio is
* preserved if only one of these two parameters is specified.
*
* @param {String} `sourceName` Source name. Note that, since scenes are also sources, you can also provide a scene name.
* @param {String (optional)} `sourceName` Source name. Note that, since scenes are also sources, you can also provide a scene name. If not provided, the currently active scene is used.
* @param {String (optional)} `embedPictureFormat` Format of the Data URI encoded picture. Can be "png", "jpg", "jpeg" or "bmp" (or any other value supported by Qt's Image module)
* @param {String (optional)} `saveToFilePath` Full file path (file extension included) where the captured image is to be saved. Can be in a format different from `pictureFormat`. Can be a relative path.
* @param {String (optional)} `fileFormat` Format to save the image file as (one of the values provided in the `supported-image-export-formats` response field of `GetVersion`). If not specified, tries to guess based on file extension.
@ -1641,18 +1641,19 @@ RpcResponse WSRequestHandler::SetAudioMonitorType(const RpcRequest& request)
* @since 4.6.0
*/
RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
return request.failed("missing request parameters");
}
if (!request.hasField("embedPictureFormat") && !request.hasField("saveToFilePath")) {
return request.failed("At least 'embedPictureFormat' or 'saveToFilePath' must be specified");
}
const char* sourceName = obs_data_get_string(request.parameters(), "sourceName");
OBSSourceAutoRelease source = obs_get_source_by_name(sourceName);
if (!source) {
return request.failed("specified source doesn't exist");;
OBSSourceAutoRelease source;
if (!request.hasField("sourceName")) {
source = obs_frontend_get_current_scene();
} else {
const char* sourceName = obs_data_get_string(request.parameters(), "sourceName");
source = obs_get_source_by_name(sourceName);
if (!source) {
return request.failed("specified source doesn't exist");;
}
}
const uint32_t sourceWidth = obs_source_get_base_width(source);

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
* @name StartStopStreaming
@ -292,7 +292,6 @@ RpcResponse WSRequestHandler::SaveStreamSettings(const RpcRequest& request) {
/**
* 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
*

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
* @name ToggleStudioMode