d0074858bf
界面与品牌 - 默认 UI 语言固定为英文，不再跟随系统区域设置自动切换（frontend/OBSApp.cpp），用户仍可在设置中手动切换 - 程序图标更换为 CAIIC logo：exe 图标 obs-studio.ico 及界面/托盘/About 图标 obs.png - About 窗口精简为 logo + 名称 + 版本号，移除项目介绍、赞助名单、Authors/License 标签页 - 版本号定为 1.0.0（构建参数 OBS_VERSION_OVERRIDE=1.0.0） 分辨率支持 - 移除首次启动将画布强制限制为 1920x1080 的逻辑，默认使用显示器原生分辨率 - 设置-视频 与自动配置向导新增 3840x2160 / 2560x1440 预设 - 自动配置向导性能测试上限放宽至 4K60（软硬件编码数据率上限及起始分辨率钳制） 插件 - 集成 obs-shaderfilter 2.6.0（绿幕抠图/自定义着色器滤镜），并适配新版 libobs 的 gs_image_file_ex API - 补齐缺失的源码：obs-browser、obs-websocket、libdshowcapture（含 external/capture-device-support） 工程 - 新增 .gitignore，排除 deploy/ 发布目录与构建日志
141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
# obs-websocket documentation
|
|
|
|
## If you're looking for the documentation page, it's [here](generated/protocol.md)
|
|
|
|
This is the documentation for obs-websocket. Run `build_docs.sh` to auto generate the latest docs from the `src` directory. There are 3 components to the docs generation:
|
|
|
|
- `comments/comments.js`: Generates the `work/comments.json` file from the code comments in the src directory.
|
|
- `docs/process_comments.py`: Processes `work/comments.json` to create `generated/protocol.json`, which is a machine-readable documentation format that can be used to create obs-websocket client libraries.
|
|
- `docs/generate_md.py`: Processes `generated/protocol.json` to create `generated/protocol.md`, which is the actual human-readable documentation.
|
|
|
|
Some notes about documenting:
|
|
|
|
- The `complexity` comment line is a suggestion to the user about how much knowledge about OBS's inner workings is required to safely use the associated feature. `1` for easy, `5` for megadeath-expert.
|
|
- The `rpcVersion` comment line is used to specify the latest available version that the feature is available in. If a feature is deprecated, then the placeholder value of `-1` should be replaced with the last RPC version that the feature will be available in. Manually specifying an RPC version automatically adds the `Deprecated` line to the entry in `generated/protocol.md`.
|
|
- The description can be multiple lines, but must be contained above the first documentation property (the lines starting with `@`).
|
|
- Value types are in reference to JSON values. The only ones you should use are `Any`, `String`, `Boolean`, `Number`, `Array`, `Object`.
|
|
- `Array` types follow this format: `Array<subtype>`, for example `Array<String>` to specify an array of strings.
|
|
|
|
Formatting notes:
|
|
|
|
- Fields should have their columns aligned. So in a request, the columns of all `@requestField`s should be aligned.
|
|
- We suggest looking at how other enums/events/requests have been documented before documenting one of your own, to get a general feel of how things have been formatted.
|
|
|
|
## Creating enum documentation
|
|
|
|
Enums follow this code comment format:
|
|
|
|
```js
|
|
/**
|
|
* [description]
|
|
*
|
|
* @enumIdentifier [identifier]
|
|
* @enumValue [value]
|
|
* @enumType [type]
|
|
* @rpcVersion [latest available RPC version, use `-1` unless deprecated.]
|
|
* @initialVersion [first obs-websocket version this is found in]
|
|
* @api enums
|
|
*/
|
|
```
|
|
|
|
Example code comment:
|
|
|
|
```js
|
|
/**
|
|
* The initial message sent by obs-websocket to newly connected clients.
|
|
*
|
|
* @enumIdentifier Hello
|
|
* @enumValue 0
|
|
* @enumType WebSocketOpCode
|
|
* @rpcVersion -1
|
|
* @initialVersion 5.0.0
|
|
* @api enums
|
|
*/
|
|
```
|
|
|
|
- This is the documentation for the `WebSocketOpCode::Hello` enum identifier.
|
|
|
|
## Creating event documentation
|
|
|
|
Events follow this code comment format:
|
|
|
|
```js
|
|
/**
|
|
* [description]
|
|
*
|
|
* @dataField [field name] | [value type] | [field description]
|
|
* [... more @dataField entries ...]
|
|
*
|
|
* @eventType [type]
|
|
* @eventSubscription [EventSubscription requirement]
|
|
* @complexity [complexity rating, 1-5]
|
|
* @rpcVersion [latest available RPC version, use `-1` unless deprecated.]
|
|
* @initialVersion [first obs-websocket version this is found in]
|
|
* @category [event category]
|
|
* @api events
|
|
*/
|
|
```
|
|
|
|
Example code comment:
|
|
|
|
```js
|
|
/**
|
|
* Studio mode has been enabled or disabled.
|
|
*
|
|
* @dataField studioModeEnabled | Boolean | True == Enabled, False == Disabled
|
|
*
|
|
* @eventType StudioModeStateChanged
|
|
* @eventSubscription General
|
|
* @complexity 1
|
|
* @rpcVersion -1
|
|
* @initialVersion 5.0.0
|
|
* @category general
|
|
* @api events
|
|
*/
|
|
```
|
|
|
|
## Creating request documentation
|
|
|
|
Requests follow this code comment format:
|
|
|
|
```js
|
|
/**
|
|
* [description]
|
|
*
|
|
* @requestField [optional flag][field name] | [value type] | [field description] | [value restrictions (only include if the value type is `Number`)] | [default behavior (only include if optional flag is set)]
|
|
* [... more @requestField entries ...]
|
|
*
|
|
* @responseField [field name] | [value type] | [field description]
|
|
* [... more @responseField entries ...]
|
|
*
|
|
* @requestType [type]
|
|
* @complexity [complexity rating, 1-5]
|
|
* @rpcVersion [latest available RPC version, use `-1` unless deprecated.]
|
|
* @initialVersion [first obs-websocket version this is found in]
|
|
* @category [request category]
|
|
* @api requests
|
|
*/
|
|
```
|
|
|
|
- The optional flag is a `?` that prefixes the field name, telling the docs processor that the field is optionally specified.
|
|
|
|
Example code comment:
|
|
|
|
```js
|
|
/**
|
|
* Gets the value of a "slot" from the selected persistent data realm.
|
|
*
|
|
* @requestField realm | String | The data realm to select. `OBS_WEBSOCKET_DATA_REALM_GLOBAL` or `OBS_WEBSOCKET_DATA_REALM_PROFILE`
|
|
* @requestField slotName | String | The name of the slot to retrieve data from
|
|
*
|
|
* @responseField slotValue | String | Value associated with the slot. `null` if not set
|
|
*
|
|
* @requestType GetPersistentData
|
|
* @complexity 2
|
|
* @rpcVersion -1
|
|
* @initialVersion 5.0.0
|
|
* @category config
|
|
* @api requests
|
|
*/
|
|
```
|