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

Merge pull request #254 from Lange/typedefs

Browse Source 
docs: improve consistency of array typings; introduce typedefs category
This commit is contained in:
Stéphane Lepin 2018-12-07 20:45:30 +01:00 committed by GitHub
commit fc637eef6d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 240 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/comments.js
View File

@ -30,6 +30,14 @@ const processComments = comments => {
let errors = [];
comments.forEach(comment => {
if (comment.typedef) {
comment.comment = undefined;
comment.context = undefined;
sorted['typedefs'] = sorted['typedefs'] || [];
sorted['typedefs'].push(comment);
return;
}
if (typeof comment.api === 'undefined') return;
let validationFailures = validateComment(comment);
@ -84,9 +92,7 @@ const validateComment = comment => {
fullContext: Object.assign({}, comment)
};
}
return;
}
};
const files = glob.sync(config.srcGlob);
const comments = processComments(parseFiles(files));

178
docs/generated/comments.json
View File

@ -6,7 +6,7 @@
"description": "Indicates a scene change.",
"return": [
"{String} `scene-name` The new scene.",
"{Array} `sources` List of sources in the new scene."
"{Array<Source>} `sources` List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
],
"api": "events",
"name": "SwitchScenes",
@ -19,9 +19,9 @@
"description": "The new scene."
},
{
"type": "Array",
"type": "Array<Source>",
"name": "sources",
"description": "List of sources in the new scene."
"description": "List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
}
],
"names": [
@ -1246,7 +1246,7 @@
"description": "The selected preview scene has changed (only available in Studio Mode).",
"return": [
"{String} `scene-name` Name of the scene being previewed.",
"{Source|Array} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
"{Array<Source>} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
],
"api": "events",
"name": "PreviewSceneChanged",
@ -1259,7 +1259,7 @@
"description": "Name of the scene being previewed."
},
{
"type": "Source|Array",
"type": "Array<Source>",
"name": "sources",
"description": "List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
}
@ -1702,14 +1702,14 @@
{
"subheads": [],
"description": "Get a list of available profiles.",
"return": "{Object|Array} `profiles` List of available profiles.",
"return": "{Array<Object>} `profiles` List of available profiles.",
"api": "requests",
"name": "ListProfiles",
"category": "profiles",
"since": "4.0.0",
"returns": [
{
"type": "Object|Array",
"type": "Array<Object>",
"name": "profiles",
"description": "List of available profiles."
}
@ -2144,24 +2144,16 @@
{
"subheads": [],
"description": "List available scene collections",
"return": [
"{Object|Array} `scene-collections` Scene collections list",
"{String} `scene-collections.*.`"
],
"return": "{Array<String>} `scene-collections` Scene collections list",
"api": "requests",
"name": "ListSceneCollections",
"category": "scene collections",
"since": "4.0.0",
"returns": [
{
"type": "Object|Array",
"type": "Array<String>",
"name": "scene-collections",
"description": "Scene collections list"
},
{
"type": "String",
"name": "scene-collections.*.",
"description": ""
}
],
"names": [
@ -2861,7 +2853,7 @@
"description": "Get the current scene's name and source items.",
"return": [
"{String} `name` Name of the currently active scene.",
"{Source|Array} `sources` Ordered list of the current scene's source items."
"{Array<Source>} `sources` Ordered list of the current scene's source items."
],
"api": "requests",
"name": "GetCurrentScene",
@ -2874,7 +2866,7 @@
"description": "Name of the currently active scene."
},
{
"type": "Source|Array",
"type": "Array<Source>",
"name": "sources",
"description": "Ordered list of the current scene's source items."
}
@ -2910,7 +2902,7 @@
"description": "Get a list of scenes in the currently active profile.",
"return": [
"{String} `current-scene` Name of the currently active scene.",
"{Scene|Array} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information)."
"{Array<Scene>} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information)."
],
"api": "requests",
"name": "GetSceneList",
@ -2923,7 +2915,7 @@
"description": "Name of the currently active scene."
},
{
"type": "Scene|Array",
"type": "Array<Scene>",
"name": "scenes",
"description": "Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information)."
}
@ -2960,7 +2952,7 @@
"subheads": [],
"description": "List all sources available in the running OBS instance",
"return": [
"{Array of Objects} `sources` Array of sources as objects",
"{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.*.type` Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\""
@ -2971,9 +2963,9 @@
"since": "4.3.0",
"returns": [
{
"type": "Array of Objects",
"type": "Array<Object>",
"name": "sources",
"description": "Array of sources as objects"
"description": "Array of sources"
},
{
"type": "String",
@ -3021,7 +3013,7 @@
"subheads": [],
"description": "Get a list of all available sources types",
"return": [
"{Array of Objects} `ids` Array of sources as objects",
"{Array<Object>} `ids` Array of source types",
"{String} `ids.*.typeId` Non-unique internal source type ID",
"{String} `ids.*.displayName` Display name of the source type",
"{String} `ids.*.type` Type. Value is one of the following: \"input\", \"filter\", \"transition\" or \"other\"",
@ -3041,9 +3033,9 @@
"since": "4.3.0",
"returns": [
{
"type": "Array of Objects",
"type": "Array<Object>",
"name": "ids",
"description": "Array of sources as objects"
"description": "Array of source types"
},
{
"type": "String",
@ -4493,7 +4485,7 @@
"description": "List filters applied to a source",
"param": "{String} `sourceName` Source name",
"return": [
"{Array of Objects} `filters` List of filters for the specified source",
"{Array<Object>} `filters` List of filters for the specified source",
"{String} `filters.*.type` Filter type",
"{String} `filters.*.name` Filter name",
"{Object} `filters.*.settings` Filter settings"
@ -4504,7 +4496,7 @@
"since": "unreleased",
"returns": [
{
"type": "Array of Objects",
"type": "Array<Object>",
"name": "filters",
"description": "List of filters for the specified source"
},
@ -5303,7 +5295,7 @@
"description": "Get the name of the currently previewed scene and its list of sources.\nWill return an `error` if Studio Mode is not enabled.",
"return": [
"{String} `name` The name of the active preview scene.",
"{Source|Array} `sources`"
"{Array<Source>} `sources`"
],
"api": "requests",
"name": "GetPreviewScene",
@ -5316,7 +5308,7 @@
"description": "The name of the active preview scene."
},
{
"type": "Source|Array",
"type": "Array<Source>",
"name": "sources",
"description": ""
}
@ -5549,8 +5541,8 @@
"description": "List of all transitions available in the frontend's dropdown menu.",
"return": [
"{String} `current-transition` Name of the currently active transition.",
"{Object|Array} `transitions` List of transitions.",
"{String} `transitions[].name` Name of the transition."
"{Array<Object>} `transitions` List of transitions.",
"{String} `transitions.*.name` Name of the transition."
],
"api": "requests",
"name": "GetTransitionList",
@ -5563,13 +5555,13 @@
"description": "Name of the currently active transition."
},
{
"type": "Object|Array",
"type": "Array<Object>",
"name": "transitions",
"description": "List of transitions."
},
{
"type": "String",
"name": "transitions[].name",
"name": "transitions.*.name",
"description": "Name of the transition."
}
],
@ -5772,5 +5764,121 @@
"examples": []
}
]
},
"typedefs": [
{
"subheads": [],
"typedef": "{Object} `Scene`",
"property": [
"{String} `name` Name of the currently active scene.",
"{Array<Source>} `sources` Ordered list of the current scene's source items."
],
"properties": [
{
"type": "String",
"name": "name",
"description": "Name of the currently active scene."
},
{
"type": "Array<Source>",
"name": "sources",
"description": "Ordered list of the current scene's source items."
}
],
"typedefs": [
{
"type": "Object",
"name": "Scene",
"description": ""
}
],
"name": "",
"heading": {
"level": 2,
"text": ""
},
"examples": []
},
{
"subheads": [],
"typedef": "{Object} `Source` An OBS Scene Item.",
"property": [
"{Number} `cy`",
"{Number} `cx`",
"{String} `name` The name of this Scene Item.",
"{Boolean} `render` Whether or not this Scene Item is set to \"visible\".",
"{Number} `source_cx`",
"{Number} `source_cy`",
"{String} `type` Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\"",
"{Number} `volume`",
"{Number} `x`",
"{Number} `y`"
],
"properties": [
{
"type": "Number",
"name": "cy",
"description": ""
},
{
"type": "Number",
"name": "cx",
"description": ""
},
{
"type": "String",
"name": "name",
"description": "The name of this Scene Item."
},
{
"type": "Boolean",
"name": "render",
"description": "Whether or not this Scene Item is set to \"visible\"."
},
{
"type": "Number",
"name": "source_cx",
"description": ""
},
{
"type": "Number",
"name": "source_cy",
"description": ""
},
{
"type": "String",
"name": "type",
"description": "Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\""
},
{
"type": "Number",
"name": "volume",
"description": ""
},
{
"type": "Number",
"name": "x",
"description": ""
},
{
"type": "Number",
"name": "y",
"description": ""
}
],
"typedefs": [
{
"type": "Object",
"name": "Source",
"description": "An OBS Scene Item."
}
],
"name": "",
"heading": {
"level": 2,
"text": ""
},
"examples": []
}
]
}

53
docs/generated/protocol.md
View File

@ -43,6 +43,9 @@ auth_response = base64_encode(auth_response_hash)
<!-- toc -->
- [Typedefs](#typedefs)
* [Scene](#scene)
* [Source](#source)
- [Events](#events)
* [Scenes](#scenes)
+ [SwitchScenes](#switchscenes)
@ -174,6 +177,31 @@ auth_response = base64_encode(auth_response_hash)
<!-- tocstop -->
# Typedefs
These are complex types, such as `Source` and `Scene`, which are used as arguments or return values in multiple requests and/or events.
## Scene
| Name | Type | Description |
| ---- | :---: | ------------|
| `name` | _String_ | Name of the currently active scene. |
| `sources` | _Array&lt;Source&gt;_ | Ordered list of the current scene's source items. |
## Source
| Name | Type | Description |
| ---- | :---: | ------------|
| `cy` | _Number_ | |
| `cx` | _Number_ | |
| `name` | _String_ | The name of this Scene Item. |
| `render` | _Boolean_ | Whether or not this Scene Item is set to "visible". |
| `source_cx` | _Number_ | |
| `source_cy` | _Number_ | |
| `type` | _String_ | Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" |
| `volume` | _Number_ | |
| `x` | _Number_ | |
| `y` | _Number_ | |
# Events
Events are broadcast by the server to each connected client when a recognized action occurs within OBS.
@ -201,7 +229,7 @@ Indicates a scene change.
| Name | Type | Description |
| ---- | :---: | ------------|
| `scene-name` | _String_ | The new scene. |
| `sources` | _Array_ | List of sources in the new scene. |
| `sources` | _Array&lt;Source&gt;_ | List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene). |
---
@ -661,7 +689,7 @@ The selected preview scene has changed (only available in Studio Mode).
| Name | Type | Description |
| ---- | :---: | ------------|
| `scene-name` | _String_ | Name of the scene being previewed. |
| `sources` | _Source\|Array_ | List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene). |
| `sources` | _Array&lt;Source&gt;_ | List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene). |
---
@ -883,7 +911,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `profiles` | _Object\|Array_ | List of available profiles. |
| `profiles` | _Array&lt;Object&gt;_ | List of available profiles. |
---
@ -1117,8 +1145,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `scene-collections` | _Object\|Array_ | Scene collections list |
| `scene-collections.*.` | _String_ | |
| `scene-collections` | _Array&lt;String&gt;_ | Scene collections list |
---
@ -1357,7 +1384,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `name` | _String_ | Name of the currently active scene. |
| `sources` | _Source\|Array_ | Ordered list of the current scene's source items. |
| `sources` | _Array&lt;Source&gt;_ | Ordered list of the current scene's source items. |
---
@ -1378,7 +1405,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `current-scene` | _String_ | Name of the currently active scene. |
| `scenes` | _Scene\|Array_ | Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information). |
| `scenes` | _Array&lt;Scene&gt;_ | Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information). |
---
@ -1400,7 +1427,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `sources` | _Array of Objects_ | Array of sources as objects |
| `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.*.type` | _String_ | Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" |
@ -1423,7 +1450,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `ids` | _Array of Objects_ | Array of sources as objects |
| `ids` | _Array&lt;Object&gt;_ | Array of source types |
| `ids.*.typeId` | _String_ | Non-unique internal source type ID |
| `ids.*.displayName` | _String_ | Display name of the source type |
| `ids.*.type` | _String_ | Type. Value is one of the following: "input", "filter", "transition" or "other" |
@ -1900,7 +1927,7 @@ List filters applied to a source
| Name | Type | Description |
| ---- | :---: | ------------|
| `filters` | _Array of Objects_ | List of filters for the specified source |
| `filters` | _Array&lt;Object&gt;_ | List of filters for the specified source |
| `filters.*.type` | _String_ | Filter type |
| `filters.*.name` | _String_ | Filter name |
| `filters.*.settings` | _Object_ | Filter settings |
@ -2217,7 +2244,7 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `name` | _String_ | The name of the active preview scene. |
| `sources` | _Source\|Array_ | |
| `sources` | _Array&lt;Source&gt;_ | |
---
@ -2335,8 +2362,8 @@ _No specified parameters._
| Name | Type | Description |
| ---- | :---: | ------------|
| `current-transition` | _String_ | Name of the currently active transition. |
| `transitions` | _Object\|Array_ | List of transitions. |
| `transitions[].name` | _String_ | Name of the transition. |
| `transitions` | _Array&lt;Object&gt;_ | List of transitions. |
| `transitions.*.name` | _String_ | Name of the transition. |
---

2
docs/partials/typedefsHeader.md Normal file
View File

@ -0,0 +1,2 @@
# Typedefs
These are complex types, such as `Source` and `Scene`, which are used as arguments or return values in multiple requests and/or events.

13
docs/protocol.hbs
View File

@ -7,6 +7,19 @@
{{#read "partials/typedefsHeader.md"}}{{/read}}
{{#each typedefs}}
## {{typedefs.0.name}}
| Name | Type | Description |
| ---- | :---: | ------------|
{{#each properties}}
| `{{name}}` | _{{depipe type}}_ | {{{depipe description}}} |
{{/each}}
{{/each}}
{{#read "partials/eventsHeader.md"}}{{/read}}
{{#each events}}

4
src/WSEvents.cpp
View File

@ -292,7 +292,7 @@ const char* WSEvents::GetRecordingTimecode() {
* Indicates a scene change.
*
* @return {String} `scene-name` The new scene.
* @return {Array} `sources` List of sources in the new scene.
* @return {Array<Source>} `sources` List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene).
*
* @api events
* @name SwitchScenes
@ -907,7 +907,7 @@ void WSEvents::OnSceneItemVisibilityChanged(void* param, calldata_t* data) {
* The selected preview scene has changed (only available in Studio Mode).
*
* @return {String} `scene-name` Name of the scene being previewed.
* @return {Source|Array} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene).
* @return {Array<Source>} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene).
*
* @api events
* @name PreviewSceneChanged

2
src/WSRequestHandler_Profiles.cpp
View File

@ -50,7 +50,7 @@ void WSRequestHandler::HandleGetCurrentProfile(WSRequestHandler* req) {
/**
* Get a list of available profiles.
*
* @return {Object|Array} `profiles` List of available profiles.
* @return {Array<Object>} `profiles` List of available profiles.
*
* @api requests
* @name ListProfiles

3
src/WSRequestHandler_SceneCollections.cpp
View File

@ -50,8 +50,7 @@ void WSRequestHandler::HandleGetCurrentSceneCollection(WSRequestHandler* req) {
/**
* List available scene collections
*
* @return {Object|Array} `scene-collections` Scene collections list
* @return {String} `scene-collections.*.`
* @return {Array<String>} `scene-collections` Scene collections list
*
* @api requests
* @name ListSceneCollections

10
src/WSRequestHandler_Scenes.cpp
View File

@ -3,6 +3,12 @@
#include "WSRequestHandler.h"
/**
* @typedef {Object} `Scene`
* @property {String} `name` Name of the currently active scene.
* @property {Array<Source>} `sources` Ordered list of the current scene's source items.
*/
/**
* Switch to the specified scene.
*
@ -34,7 +40,7 @@
* Get the current scene's name and source items.
*
* @return {String} `name` Name of the currently active scene.
* @return {Source|Array} `sources` Ordered list of the current scene's source items.
* @return {Array<Source>} `sources` Ordered list of the current scene's source items.
*
* @api requests
* @name GetCurrentScene
@ -56,7 +62,7 @@ void WSRequestHandler::HandleGetCurrentScene(WSRequestHandler* req) {
* Get a list of scenes in the currently active profile.
*
* @return {String} `current-scene` Name of the currently active scene.
* @return {Scene|Array} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information).
* @return {Array<Scene>} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information).
*
* @api requests
* @name GetSceneList

20
src/WSRequestHandler_Sources.cpp
View File

@ -3,10 +3,24 @@
#include "WSRequestHandler.h"
/**
* @typedef {Object} `Source` An OBS Scene Item.
* @property {Number} `cy`
* @property {Number} `cx`
* @property {String} `name` The name of this Scene Item.
* @property {Boolean} `render` Whether or not this Scene Item is set to "visible".
* @property {Number} `source_cx`
* @property {Number} `source_cy`
* @property {String} `type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"
* @property {Number} `volume`
* @property {Number} `x`
* @property {Number} `y`
*/
/**
* List all sources available in the running OBS instance
*
* @return {Array of Objects} `sources` Array of sources as objects
* @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.*.type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"
@ -64,7 +78,7 @@ void WSRequestHandler::HandleGetSourcesList(WSRequestHandler* req) {
/**
* Get a list of all available sources types
*
* @return {Array of Objects} `ids` Array of sources as objects
* @return {Array<Object>} `ids` Array of source types
* @return {String} `ids.*.typeId` Non-unique internal source type ID
* @return {String} `ids.*.displayName` Display name of the source type
* @return {String} `ids.*.type` Type. Value is one of the following: "input", "filter", "transition" or "other"
@ -1119,7 +1133,7 @@ void WSRequestHandler::HandleDuplicateSceneItem(WSRequestHandler* req) {
*
* @param {String} `sourceName` Source name
*
* @return {Array of Objects} `filters` List of filters for the specified source
* @return {Array<Object>} `filters` List of filters for the specified source
* @return {String} `filters.*.type` Filter type
* @return {String} `filters.*.name` Filter name
* @return {Object} `filters.*.settings` Filter settings

2
src/WSRequestHandler_StudioMode.cpp
View File

@ -27,7 +27,7 @@
* Will return an `error` if Studio Mode is not enabled.
*
* @return {String} `name` The name of the active preview scene.
* @return {Source|Array} `sources`
* @return {Array<Source>} `sources`
*
* @api requests
* @name GetPreviewScene

4
src/WSRequestHandler_Transitions.cpp
View File

@ -7,8 +7,8 @@
* List of all transitions available in the frontend's dropdown menu.
*
* @return {String} `current-transition` Name of the currently active transition.
* @return {Object|Array} `transitions` List of transitions.
* @return {String} `transitions[].name` Name of the transition.
* @return {Array<Object>} `transitions` List of transitions.
* @return {String} `transitions.*.name` Name of the transition.
*
* @api requests
* @name GetTransitionList