OBSWebSocketv5修改源教程详解

本文深入解析了 OBS Studio 30 中 WebSocket v5 协议下动态更新文本与图像源内容的正确实践，重点揭示了已废弃的旧 API（如 SetSourceSettings 和 SetTextGDIPlusProperties）如何被统一、语义更清晰的 `SetInputSettings` 全面取代，并提供了开箱即用的 Python 示例代码和关键避坑指南——从精确匹配源名称、识别不同输入类型的配置字段（如 `"text"` 或 `"file"`），到实时生效机制与常见错误排查，助你无缝迁移到现代 OBS 自动化开发范式，真正掌握「一切皆 Input」的核心逻辑。

本文详解 OBS 30 内置 WebSocket（v5）下如何通过 `obs-websocket-py` 动态更新文本和图像源内容，重点说明 `SetInputSettings` 替代已废弃的 `SetSourceSettings` 和 `SetTextGDIPlusProperties` 的完整用法。

自 OBS 28 起，官方将 WebSocket 插件深度集成至核心，并升级为协议版本 5（v5）。该版本对 API 进行了重大重构：所有基于“Source”的旧请求（如 SetSourceSettings、SetTextGDIPlusProperties）均已移除，统一由更通用、语义更清晰的 SetInputSettings 接口替代。这意味着，无论目标是 GDI+ 文本、Browser 源、Image 源还是媒体源，只要其在 OBS 中被识别为 Input（即具有可配置属性的输入项），均需通过 inputName + inputSettings 方式进行设置。

以下是适配 OBS 30 + WebSocket v5 的完整、可运行代码示例：

from obswebsocket import obsws, requests

new_image_file_path = "image.png"
source_name_text = "text"      # OBS 中文本源的名称（非显示内容）
source_name_image = "image"    # OBS 中图像源的名称

def connect():
    host = "localhost"
    port = 4455
    password = "myPassword"
    ws = obsws(host, port, password)
    ws.connect()
    run(ws)

def run(ws):
    # ✅ 正确：使用 SetInputSettings 更新图像源路径
    ws.call(requests.SetInputSettings(
        inputName=source_name_image,
        inputSettings={"file": new_image_file_path}
    ))

    # ✅ 正确：使用 SetInputSettings 更新文本源内容
    ws.call(requests.SetInputSettings(
        inputName=source_name_text,
        inputSettings={"text": "Hello from WebSocket v5!"}
    ))

if __name__ == '__main__':
    connect()

⚠️ 关键注意事项：

• 名称必须精确匹配：inputName 是 OBS 源列表中显示的 源名称（即你在“来源”面板右键重命名的那个名称），而非源类型（如 "Text GDI+"）或文件名。
• 字段名因输入类型而异：不同输入类型支持的 inputSettings 键不同。例如：
  • 图像源（Image Source）：使用 "file"；
  • GDI+/DirectWrite 文本源：使用 "text"；
  • 浏览器源（Browser Source）：常用 "url"、"width"、"height" 等；
  • 建议通过 OBS Studio → 工具 → WebSocket Server Settings → “Open API Reference” 查阅最新文档，或使用 GetInputSettings 先获取当前配置结构作为参考。
• 无需重启或刷新：调用 SetInputSettings 后更改实时生效，无需切换场景或手动刷新。
• 错误静默？检查日志：若无报错但未生效，请确认：
  • 源确实存在于当前场景中（SetInputSettings 不校验场景上下文，但目标源必须已存在）；
  • OBS 日志（帮助 → 日志文件）中是否出现 Failed to find input 提示——这通常意味着 inputName 拼写错误或源已被删除。

总结：拥抱 WebSocket v5 的核心在于理解「一切皆 Input」的设计范式。摒弃旧版按源类型拆分的 API，转而使用统一、灵活的 SetInputSettings，不仅提升了 API 一致性，也为未来新增输入类型预留了良好扩展性。务必以 OBS 官方 API 文档为准，避免依赖过时的 v4 教程代码。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《OBSWebSocketv5修改源教程详解》文章吧，也可关注golang学习网公众号了解相关技术文章。