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 ### 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").

217
docs/generated/comments.json
View File

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

120
docs/generated/protocol.md
View File

@ -4,7 +4,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.
@ -35,6 +35,8 @@ 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.
@ -380,8 +382,9 @@ Indicates a scene change.
- Added in v0.3 - 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:** **Response Items:**
@ -616,7 +619,7 @@ _No additional response items._
- Added in v0.3 - Added in v0.3
Emit every 2 seconds. Emitted every 2 seconds when stream is active.
**Response Items:** **Response Items:**
@ -799,7 +802,7 @@ _No additional response items._
### Heartbeat ### Heartbeat
- Added in v - Added in vv0.3
Emitted every 2 seconds after enabling it by calling SetHeartbeat. 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 - 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:** **Response Items:**
@ -1079,7 +1082,7 @@ Filters in a source have been reordered.
### MediaPlaying ### 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 ### 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 ### 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 ### 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 ### 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 ### 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 ### 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 ### 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 - Added in v4.0.0
Scene items have been reordered. Scene items within a scene have been reordered.
**Response Items:** **Response Items:**
@ -1254,7 +1257,7 @@ Scene items have been reordered.
- Added in v4.0.0 - 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:** **Response Items:**
@ -1272,7 +1275,7 @@ An item has been added to the current scene.
- Added in v4.0.0 - 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:** **Response Items:**
@ -1290,7 +1293,7 @@ An item has been removed from the current scene.
- Added in v4.0.0 - Added in v4.0.0
An item's visibility has been toggled. A scene item's visibility has been toggled.
**Response Items:** **Response Items:**
@ -1309,7 +1312,7 @@ An item's visibility has been toggled.
- Added in v4.8.0 - Added in v4.8.0
An item's locked status has been toggled. A scene item's locked status has been toggled.
**Response Items:** **Response Items:**
@ -1328,7 +1331,7 @@ An item's locked status has been toggled.
- Added in v4.6.0 - Added in v4.6.0
An item's transform has been changed. A scene item's transform has been changed.
**Response Items:** **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: 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.
@ -1500,6 +1503,7 @@ _No additional response items._
### SetHeartbeat ### 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 - Added in v4.3.0
@ -1573,7 +1577,7 @@ _No specified parameters._
| Name | Type | Description | | 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 | | 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. | | `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). | | `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 ### 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) 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 ### RestartMedia
- Added in v4.9.0 - Unreleased
Restart a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) 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 ### StopMedia
- Added in v4.9.0 - Unreleased
Stop a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) 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 ### 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) 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 ### 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) 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 ### 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) 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. 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 ### 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) 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 ### 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) 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 ### 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) 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. 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 ### 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) 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 ### GetMediaSourcesList
- Added in v4.9.0 - Unreleased
List the media state of all media sources (vlc and media source) 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` | _Array&lt;Object&gt;_ | Array of sources |
| `sources.*.name` | _String_ | Unique source name | | `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" | | `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:** **Request Fields:**
@ -2223,8 +2227,8 @@ Get the current properties of a Text GDI Plus source.
| ---- | :---: | ------------| | ---- | :---: | ------------|
| `source` | _String_ | Source name. | | `source` | _String_ | Source name. |
| `align` | _String_ | Text Alignment ("left", "center", "right"). | | `align` | _String_ | Text Alignment ("left", "center", "right"). |
| `bk-color` | _int_ | Background color. | | `bk_color` | _int_ | Background color. |
| `bk-opacity` | _int_ | Background opacity (0-100). | | `bk_opacity` | _int_ | Background opacity (0-100). |
| `chatlog` | _boolean_ | Chat log. | | `chatlog` | _boolean_ | Chat log. |
| `chatlog_lines` | _int_ | Chat log lines. | | `chatlog_lines` | _int_ | Chat log lines. |
| `color` | _int_ | Text color. | | `color` | _int_ | Text color. |
@ -2266,8 +2270,8 @@ Set the current properties of a Text GDI Plus source.
| ---- | :---: | ------------| | ---- | :---: | ------------|
| `source` | _String_ | Name of the source. | | `source` | _String_ | Name of the source. |
| `align` | _String (optional)_ | Text Alignment ("left", "center", "right"). | | `align` | _String (optional)_ | Text Alignment ("left", "center", "right"). |
| `bk-color` | _int (optional)_ | Background color. | | `bk_color` | _int (optional)_ | Background color. |
| `bk-opacity` | _int (optional)_ | Background opacity (0-100). | | `bk_opacity` | _int (optional)_ | Background opacity (0-100). |
| `chatlog` | _boolean (optional)_ | Chat log. | | `chatlog` | _boolean (optional)_ | Chat log. |
| `chatlog_lines` | _int (optional)_ | Chat log lines. | | `chatlog_lines` | _int (optional)_ | Chat log lines. |
| `color` | _int (optional)_ | Text color. | | `color` | _int (optional)_ | Text color. |
@ -2376,7 +2380,7 @@ _No additional response items._
### GetBrowserSourceProperties ### 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 - Added in v4.1.0
@ -2408,7 +2412,7 @@ Get current properties for a Browser Source.
### SetBrowserSourceProperties ### 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 - Added in v4.1.0
@ -2776,7 +2780,9 @@ Get information about a single output
- Added in v4.7.0 - 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:** **Request Fields:**
@ -2796,7 +2802,9 @@ _No additional response items._
- Added in v4.7.0 - 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:** **Request Fields:**
@ -2870,6 +2878,7 @@ _No specified parameters._
| Name | Type | Description | | Name | Type | Description |
| ---- | :---: | ------------| | ---- | :---: | ------------|
| `profiles` | _Array&lt;Object&gt;_ | List of available profiles. | | `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 - Added in v0.3
Toggle recording on or off. Toggle recording on or off (depending on the current recording state).
**Request Fields:** **Request Fields:**
@ -3058,7 +3067,7 @@ _No specified parameters._
- Added in v4.2.0 - 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:** **Request Fields:**
@ -3186,6 +3195,7 @@ _No specified parameters._
| Name | Type | Description | | Name | Type | Description |
| ---- | :---: | ------------| | ---- | :---: | ------------|
| `scene-collections` | _Array&lt;String&gt;_ | Scene collections list | | `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 ### SetSceneItemRender
- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️**
- Added in v0.3 - 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). | | `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` | _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.*.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.*.name` | _String (optional)_ | Name of a scene item. Sufficiently unique if no scene items share sources within the scene. |
**Response Items:** **Response Items:**
@ -3620,7 +3629,7 @@ _No additional response items._
### SetSceneTransitionOverride ### SetSceneTransitionOverride
- Added in v4.9.0 - Unreleased
Set a scene to use a specific transition override. Set a scene to use a specific transition override.
@ -3642,7 +3651,7 @@ _No additional response items._
### RemoveSceneTransitionOverride ### RemoveSceneTransitionOverride
- Added in v4.9.0 - Unreleased
Remove any transition override on a scene. Remove any transition override on a scene.
@ -3662,7 +3671,7 @@ _No additional response items._
### GetSceneTransitionOverride ### GetSceneTransitionOverride
- Added in v4.9.0 - Unreleased
Get the current scene transition override. Get the current scene transition override.
@ -3714,7 +3723,7 @@ _No specified parameters._
- Added in v0.3 - Added in v0.3
Toggle streaming on or off. Toggle streaming on or off (depending on the current stream state).
**Request Fields:** **Request Fields:**
@ -3849,7 +3858,6 @@ _No additional response items._
- Added in v4.6.0 - Added in v4.6.0
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.
**Request Fields:** **Request Fields:**
@ -3991,7 +3999,7 @@ _No additional response items._
- Added in v4.1.0 - Added in v4.1.0
Toggles Studio Mode. Toggles Studio Mode (depending on the current state of studio mode).
**Request Fields:** **Request Fields:**

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

7
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
@ -320,9 +321,9 @@ 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

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)
{ {

4
src/WSRequestHandler_Outputs.cpp
View File

@ -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)
* *

1
src/WSRequestHandler_Profiles.cpp
View File

@ -55,6 +55,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

1
src/WSRequestHandler_SceneCollections.cpp
View File

@ -57,6 +57,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") ||

10
src/WSRequestHandler_Scenes.cpp
View File

@ -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")) {
@ -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")) {
@ -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")) {

37
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)
@ -1623,7 +1623,7 @@ RpcResponse WSRequestHandler::SetAudioMonitorType(const RpcRequest& request)
* Clients can specify `width` and `height` parameters to receive scaled pictures. Aspect ratio is * Clients can specify `width` and `height` parameters to receive scaled pictures. Aspect ratio is
* preserved if only one of these two parameters is specified. * 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)} `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)} `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. * @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 * @since 4.6.0
*/ */
RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) { RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) {
if (!request.hasField("sourceName")) {
return request.failed("missing request parameters");
}
if (!request.hasField("embedPictureFormat") && !request.hasField("saveToFilePath")) { if (!request.hasField("embedPictureFormat") && !request.hasField("saveToFilePath")) {
return request.failed("At least 'embedPictureFormat' or 'saveToFilePath' must be specified"); return request.failed("At least 'embedPictureFormat' or 'saveToFilePath' must be specified");
} }
const char* sourceName = obs_data_get_string(request.parameters(), "sourceName"); OBSSourceAutoRelease source;
OBSSourceAutoRelease source = obs_get_source_by_name(sourceName); if (!request.hasField("sourceName")) {
if (!source) { source = obs_frontend_get_current_scene();
return request.failed("specified source doesn't exist");; } 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); 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 * @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