OBS-WebSocket 5.x协议详解：实时控制OBS的RPC接口指南

OBS-WebSocket 5.x协议详解：实时控制OBS的RPC接口指南

obs-websocket 项目地址: https://gitcode.com/gh_mirrors/obs/obs-websocket

概述

OBS-WebSocket是一个基于WebSocket协议的远程控制接口，它允许开发者通过RPC（远程过程调用）方式与OBS Studio进行交互。本文将深入解析5.x版本的协议规范，帮助开发者理解其设计理念和实现细节。

协议设计理念

OBS-WebSocket 5.x协议在设计上遵循了几个核心原则：

1. 模块化消息类型：将不同类型的通信抽象为专用消息类型（OpCode），包括身份验证、事件通知、请求响应等
2. 命名一致性：采用统一的命名规范，如Get、Set、Toggle等前缀使API更易理解
3. 错误处理系统：定义了一套完整的错误代码体系，每个错误都有对应的数字代码和可选描述
4. 多编码支持：协议支持JSON和MessagePack两种消息编码格式
5. 发布-订阅机制：客户端可以灵活订阅所需的事件类型，避免不必要的数据传输
6. 版本协商：客户端和服务端通过版本协商机制确保兼容性

连接建立流程

初始握手

1. 客户端首先发起HTTP升级请求，建立WebSocket连接
2. 服务端立即发送Hello消息（OpCode 0），包含版本信息和可能的认证挑战
3. 客户端响应Identify消息（OpCode 1），完成身份验证和参数协商
4. 服务端确认后发送Identified消息（OpCode 2），连接正式建立

认证机制详解

当服务端启用密码保护时，认证流程采用SHA256哈希链：

1. 服务端在Hello消息中提供随机salt和challenge
2. 客户端需要：
   • 将密码与salt拼接
   • 计算SHA256哈希并Base64编码（称为base64_secret）
   • 将base64_secret与challenge拼接
   • 再次计算SHA256哈希并Base64编码，得到最终的认证字符串

这种双重哈希机制有效防止了重放攻击，确保认证过程的安全性。

核心消息类型

1. Hello (OpCode 0)

服务端在连接建立后立即发送，包含：

• OBS-WebSocket版本号
• 支持的RPC协议版本
• 认证挑战信息（如需要认证）

2. Identify (OpCode 1)

客户端响应Hello的消息，包含：

• 客户端支持的RPC版本
• 认证字符串（如需认证）
• 事件订阅配置（位掩码形式）

3. Event (OpCode 5)

服务端向客户端推送的事件通知，如场景切换、源静音等。每个事件包含：

• 事件类型字符串
• 事件意图（订阅要求）
• 事件相关数据

4. Request/Response模式

客户端可以发送请求（OpCode 6）并接收响应（OpCode 7）。请求包含：

• 请求类型
• 唯一请求ID
• 请求参数

响应包含：

• 请求状态（成功/失败）
• 错误代码（如失败）
• 响应数据（如成功）

5. 批量请求机制

客户端可以发送批量请求（OpCode 8），服务端按顺序处理并返回批量响应（OpCode 9）。批量请求支持：

• 设置失败中断选项
• 多种执行模式（默认串行实时执行）

开发实践建议

1. 版本兼容性：始终检查negotiatedRpcVersion，确保客户端和服务端使用兼容的协议版本
2. 错误处理：正确处理各种请求状态码，特别是参数错误等常见问题
3. 事件订阅：合理配置eventSubscriptions，避免订阅不必要的高频事件
4. 连接稳定性：实现重连机制，处理网络中断等异常情况
5. 性能优化：对于高频操作，考虑使用批量请求减少网络往返

典型应用场景

1. 远程控制面板：构建自定义的控制界面，实现场景切换、源控制等功能
2. 自动化直播：与聊天机器人、游戏事件等集成，实现自动化直播效果
3. 状态监控：实时获取OBS状态，用于仪表盘显示或异常检测
4. 多机位控制：协调多个OBS实例的同步操作

通过深入理解OBS-WebSocket协议，开发者可以构建出功能强大、稳定可靠的OBS控制应用，充分发挥OBS Studio的潜力。

obs-websocket 项目地址: https://gitcode.com/gh_mirrors/obs/obs-websocket