第 27 课:界面如何驱动引擎 —— obs-frontend-api、属性面板

嘿,我是小方。 上一课我们看到"点按钮 → 调 obs_*",也看到界面和引擎那道双向桥。这一课再深一层,看两个很能体现设计功力的机制,它们都回答"怎么优雅地扩展/自动化界面": 一、obs-frontend-api —— 一套稳定的 C 接口,让前端插件(自定义面板、obs-websocket、自动化脚本)能驱动和观察 OBS,却不用碰内部的 OBSBasic; 二、属性面板(properties-view) —— 你打开源的"属性"看到那一堆控件(分辨率下拉、颜色、路径框…),OBS 并没有为每种源手写界面,而是根据源自己声明的 obs_properties,自动画出来。 两个机制,一个共同的追求:解耦。我会照例先补背景(什么是"稳定 API"、什么是"数据驱动 UI"),再进源码。

---

27.1 两个"怎么做到的?",这一课一起回答

📍我们在哪:上一课讲了界面与引擎怎么"咬合"。这一课看两个"扩展点"——它们让别人(插件、新源)能接进来,而不破坏已有的东西。

问题 ①:一个插件(自定义面板、obs-websocket、录制脚本…)想控制 / 观察 OBS —— 让它"开始录制"、或知道"场景切了"。但这个插件不是 OBSBasic 的一部分,它怎么做到?

问题 ②:你打开一个源的"属性",里面一堆控件。OBS 有几百种源,难道给每种源都手写了一个属性对话框?

两个答案:

• obs-frontend-api(遥控器) → 问题 ①;
• properties-view(自动生成) → 问题 ②。

而它们背后是同一个追求:解耦(decoupling)。obs-frontend-api 让插件驱动/观察 OBS 而不用碰(甚至不能碰)内部的 OBSBasic C++ 类;properties-view 让源只声明自己有哪些设置,而不用管界面怎么画。先讲第一个,得先弄明白它为什么要"隔一层"。

---

27.2 先补:什么是"稳定 API"和"门面(facade)"

📍为什么先讲这个:要理解 obs-frontend-api 的设计,得先明白"为什么不让插件直接用 OBSBasic"。

假如插件直接用 OBSBasic(内部类),会有三个大问题:

• OBSBasic 是内部实现,随版本随时改(改个成员名,插件就崩);
• 它是 C++,别的语言(Python、Rust、JS…)根本用不了;
• 插件和主程序**"焊死"** —— 改主程序就得改所有插件。太脆、太封闭。

OBS 的做法:稳定 C API + 门面(facade)。

• 对外:一套**"承诺不变"的 C 函数**(obs_frontend_*)—— 稳定接口;C 语言意味着任何语言都能调;
• 中间:隔一个**"门面"薄层**,把调用转发给真实现,插件看不到内部;
• 好处:内部随便改,只要门面(接口)不变,插件就一直能用。

门面 = 一层薄薄的"转发窗口":你敲这个窗口(调稳定的 obs_frontend_ 函数),窗口后面的人(真实现)去干活。窗口不变,后面的人怎么换、怎么改,你都不用管 —— 这就是"稳定 API"的价值。下面看这个门面在代码里长什么样。

---

27.3 obs-frontend-api:前端的"遥控器"

📍接上一节:把"门面"这个抽象,落到 obs_frontend_streaming_start() 这一次真实调用上。

一个插件调 obs_frontend_streaming_start(),一路是这样走到 OBSBasic 的:

1. 插件调 obs_frontend_streaming_start()（obs-frontend-api.h)—— 它只认这个稳定 C 函数;
2. obs-frontend-api.cpp 薄转发（:225）—— 查一下"门面装了没"(callbacks_valid()),再转发:

// frontend/api/obs-frontend-api.cpp:225
void obs_frontend_streaming_start(void)
{
	if (callbacks_valid())
		c->obs_frontend_streaming_start();   // c = 门面(下面)
}

3. c->obs_frontend_streaming_start() —— c 是那个门面 vtable(static unique_ptr<obs_frontend_callbacks> c;,obs-frontend-api.cpp:6;结构声明在 obs-frontend-internal.hpp:8,一堆纯虚方法,一个 API 一个);
4. OBSStudioAPI::obs_frontend_streaming_start()（OBSStudioAPI.cpp:221)—— 真实现,它持有 OBSBasic *main:

// frontend/OBSStudioAPI.cpp:221
void OBSStudioAPI::obs_frontend_streaming_start()
{
	QMetaObject::invokeMethod(main, "StartStreaming");   // 跨线程 → OBSBasic 真方法(第 26 课)
}

启动时,OBSBasic 把一个 OBSStudioAPI 对象"装进"门面(api = InitializeAPIInterface(this),OBSBasic.cpp:244;内部 new OBSStudioAPI(main) + obs_frontend_set_callbacks_internal)。从此,插件敲 obs_frontend_ 的每一下,都被转发到这个对象,再由它去指挥真正的主窗口(注意又用到第 26 课那个 invokeMethod 跨线程)。

薄转发层(.cpp)本身几乎没有逻辑 —— 真活儿全在 OBSStudioAPI + OBSBasic 里。 这就是门面:一边是稳定的对外接口,一边是可变的内部实现,中间一层解耦。那"观察 OBS"又怎么做?

---

27.4 遥控器也有"通知灯":事件回调

📍接上一节:上面是插件"主动按按钮"。反过来,插件怎么"听" OBS 的状态变化?

遥控器不只能"按按钮",还有"通知灯"—— 插件能注册回调,听 OBS 的事件:

1. 插件注册 obs_frontend_add_event_callback(我的函数, ...)（obs-frontend-api.h:162);
2. OBS 状态变了(切场景 / 开始直播 / 开始录制 / 退出…)→ OBSBasic::OnEvent(事件)（OBSBasic.cpp:2136)被调用;
3. 广播给所有订阅者：OBSStudioAPI::on_event（OBSStudioAPI.cpp:709)遍历注册表,挨个调用插件登记的那个函数。

OBS 会发哪些事件?看 enum obs_frontend_event（obs-frontend-api.h:16）:OBS_FRONTEND_EVENT_STREAMING_STARTED、_RECORDING_STARTED、_SCENE_CHANGED、_PROFILE_CHANGED、_EXIT、_FINISHED_LOADING……(这和第 8 课 libobs 的信号是类比关系,但这是前端层的事件,专给前端插件用。)

所以遥控器是双向的:"按钮" = 插件主动调 obs_frontend_*;"通知灯" = 插件注册回调听事件。这就是 obs-websocket(远程控制)、各种自动化脚本、Stream Deck 联动能同步 OBS 状态的原理 —— 它们全都只依赖这套稳定的 obs_frontend_ 接口,不碰 OBSBasic 一行代码。(插件还能用 obs_frontend_add_dock_by_id,obs-frontend-api.h:153,把自己的面板加进主窗口。)

第一个机制讲完。换第二个问题:属性对话框。

---

27.5 第二个问题:属性对话框里的控件,谁画的?

📍切换话题:从"插件怎么接进来",到"每种源的属性界面怎么来"。先看现象。

你双击一个源打开"属性",看到一堆控件:设备下拉、分辨率下拉、FPS 数字框、颜色空间下拉、缓冲复选框……每种源的属性都不一样(摄像头、文字、图片、浏览器源……长得都不同)。

OBS 有几百种源,难道给每种源都手写了一个对话框?—— 没有!

• OBS 只有**"一套" properties-view 代码**,自动生成所有源的属性对话框;
• 秘密和第 25 课(services.json)一模一样:数据驱动。源只"描述"自己有哪些设置(数据),properties-view 照着"翻译"成控件。

又是"数据驱动":把"会变的东西(每种源的设置)"做成数据,"不变的逻辑(画控件)"才是代码。下面拆开这套机制的两半 —— 先看"源怎么描述"。

---

27.6 obs_properties:源"描述"自己有哪些设置

📍机制的上半:源不画界面,它只交出一张"设置清单"。

还记得第 6 课吗?源的 obs_source_info 里有个 get_properties 回调(obs-source.h:291),它返回一个 obs_properties_t —— 一张"设置清单"。清单里每一项,是一个带类型的描述:

· OBS_PROPERTY_BOOL    "启用缓冲"
· OBS_PROPERTY_INT     "亮度"   min=0 max=100
· OBS_PROPERTY_LIST    "分辨率" {1080p, 720p, …}
· OBS_PROPERTY_PATH    "图片文件"
· OBS_PROPERTY_COLOR   "字体颜色"
· OBS_PROPERTY_BUTTON  "刷新设备"

那套"类型词汇",就是 enum obs_property_type（obs-properties.h:45：BOOL / INT / FLOAT / TEXT / PATH / LIST / COLOR / BUTTON …)。

关键分工:源负责"声明有什么设置"(WHAT),界面负责"怎么画"(HOW)—— 两边彻底分开。 源只说"我有这些设置、每个是什么类型、范围/选项是什么",至于怎么画成界面,源完全不管(就像第 25 课的平台只提供数据、不管界面)。于是写一个新源,你只描述属性;界面自动就有了,一行 Qt 代码都不用写。

那"翻译成界面"这下半,谁干?properties-view。

---

27.7 properties-view:一个 switch,把描述翻译成控件

📍机制的下半:拿到"设置清单",逐项翻译成 Qt 控件。

OBSPropertiesView 做两件事:遍历清单 + 对每项按类型造控件。

• 遍历:RefreshProperties 里 obs_properties_first → AddProperty → obs_property_next,把每个属性都处理一遍(properties-view.cpp:131);
• 翻译:AddProperty 里一个 switch,把每个类型映射到一个 Qt 控件构造器(properties-view.cpp:1490):

// shared/properties-view/properties-view.cpp:1490
switch (obs_property_get_type(property)) {
case OBS_PROPERTY_BOOL:   widget = AddCheckbox(property);  break;  // → 复选框
case OBS_PROPERTY_INT:    AddInt(property, layout, &label); break; // → 数字框 / 滑块
case OBS_PROPERTY_FLOAT:  AddFloat(...);                    break;
case OBS_PROPERTY_TEXT:   widget = AddText(...);            break; // → 文本框
case OBS_PROPERTY_PATH:   AddPath(...);                     break; // → 文件选择
case OBS_PROPERTY_LIST:   widget = AddList(...);            break; // → 下拉框
case OBS_PROPERTY_COLOR:  AddColor(...);                    break; // → 颜色按钮
case OBS_PROPERTY_BUTTON: widget = AddButton(property);    break; // → 按钮
...
}

遍历 + 这个 switch,就是"自动生成属性对话框"的全部魔法。 每个控件的范围/初值,从描述和 obs_data 里读 —— 比如 AddInt（:427）读 obs_property_int_min/max、再用 obs_data_get_int(settings, name) 填当前值,造一个 QSpinBox(+可选滑块),最后把它的 valueChanged 信号连到 ControlChanged（:467)。那条 connect,正是"改值回引擎"的起点。

---

27.8 你改一下值,怎么回到引擎(实时生效)

📍闭环:属性对话框不只是"显示",你一改,源立刻变。看这个往返。

属性对话框其实是一个 obs_data 的"可视化编辑器":改一下,立刻喂回源。以拖动"亮度"滑块为例:

1. 控件发 valueChanged 信号 → 落到 WidgetInfo::ControlChanged（properties-view.cpp:1962,按类型分派);
2. IntChanged 把新值写进 obs_data 设置(properties-view.cpp:1699):

// shared/properties-view/properties-view.cpp:1699
obs_data_set_int(view->settings, setting, spin->value());

3. 通过"视觉更新回调"调 obs_source_update(source, settings)（properties-view.cpp:2048)—— 把设置喂回源(第 6/7 课那个 update 回调),源实时重新配置,画面立刻变亮。

那个"视觉更新回调"是谁?就是对话框构造时传进去的 obs_source_update（OBSBasicProperties.cpp:71-73):

// frontend/dialogs/OBSBasicProperties.cpp:71
view = new OBSPropertiesView(nd_settings.Get(), source,
	(PropertiesReloadCallback)obs_source_properties,   // 重新读属性清单
	(PropertiesUpdateCallback) nullptr,
	(PropertiesVisualUpdateCb)obs_source_update);      // ★ 改值 → 喂回源

闭环:界面把你的改动写进 obs_data → obs_source_update 喂回源 → 源重配 → 画面变。(如果某项改动会影响别的选项显隐 —— obs_property_modified —— 还会重建对话框,回到 27.7 的遍历那步,properties-view.cpp:2053。)所见即所得,就是这么实现的。

---

27.9 全景回顾:两个机制,一个主题

• obs-frontend-api:让插件驱动 / 观察 OBS,而不碰内部的 OBSBasic。手段:稳定 C API + 门面 + 事件回调。受益者:obs-websocket、脚本、自定义面板、Stream Deck…
• properties-view:让源只声明有哪些设置,而不碰 UI 代码。手段:数据驱动 + 一个类型 switch。受益者:几百种源、滤镜、编码器,全靠它自动出界面。

模块 7 进度:26 界面怎么搭起来(OBSApp/OBSBasic/双向桥)→ 27 界面的两个扩展机制(本课)→ 28 全链路总复盘(下一课收官)。

带走一句话:好的架构,处处在"划界"—— 插件与主程序之间划一道稳定 API,源与界面之间划一道数据描述。各自独立演化,谁都不拖累谁。这种"划界"的思路,你在这门课里其实已经见了无数次(登记表、数据驱动、门面…),它们是同一种智慧的不同面孔。

---

27.10 本课小结

• 两个机制,一个主题(解耦):obs-frontend-api(让插件驱动/观察 OBS 而不碰 OBSBasic)+ properties-view(让源声明设置而不碰 UI)。
• 稳定 API / 门面:不让插件直接用 OBSBasic(内部 C++ 类,会变、封闭、焊死)。而是对外一套"承诺不变"的 C 函数 obs_frontend_*(任何语言可调),中间隔一个门面薄层转发给真实现。接口不变,内部随便改。
• obs-frontend-api 门面链:插件调 obs_frontend_streaming_start()(.h)→ .cpp 薄转发查 callbacks_valid 后转发(obs-frontend-api.cpp:225)→ 门面 c(static unique_ptr<obs_frontend_callbacks>,:6;结构 obs-frontend-internal.hpp:8)→ OBSStudioAPI::obs_frontend_streaming_start(OBSStudioAPI.cpp:221,invokeMethod(main,"StartStreaming"))。启动时 api = InitializeAPIInterface(this)(OBSBasic.cpp:244)装入门面。
• 事件回调(插件听 OBS):obs_frontend_add_event_callback(.h:162)注册 → OBS 状态变 → OBSBasic::OnEvent(:2136)→ OBSStudioAPI::on_event(:709)遍历广播。事件 enum obs_frontend_event(.h:16:STREAMING_STARTED/SCENE_CHANGED/EXIT…)。obs-websocket/脚本/Stream Deck 全靠这套接口。
• 属性面板 = 数据驱动 UI:OBS 没为几百种源手写对话框;只有一套 properties-view,照着源的"设置清单"自动生成(同第 25 课思想)。
• obs_properties(源描述设置):源的 get_properties(obs-source.h:291)返回 obs_properties_t —— 每项一个带类型描述(enum obs_property_type,obs-properties.h:45:BOOL/INT/LIST/PATH/COLOR/BUTTON…+名字/范围/选项)。源只声明 WHAT,不管 HOW。
• properties-view(翻译成控件):RefreshProperties 遍历(properties-view.cpp:131)+ AddProperty 一个 switch(类型)(:1490)→ 每类型造对应 Qt 控件(bool→复选框、int→AddInt滑块/数字框:427、list→AddList下拉、path→文件选、color→颜色按钮)。范围/初值从描述 + obs_data 读。
• 改值往返(实时生效):控件 valueChanged → ControlChanged(:1962)→ obs_data_set_int(:1699)写进设置 → 视觉更新回调 obs_source_update(:2048;对话框构造时传入,OBSBasicProperties.cpp:71)喂回源 → 源重配、画面变。改动影响布局则 obs_property_modified → 重建(:2053)。
• 一句话:好架构处处"划界" —— 插件↔主程序划稳定 API,源↔界面划数据描述,各自独立演化。

27.11 动手 / 观察(本课作业)

1. 理解门面:用自己的话说清 —— 为什么 OBS 不让插件直接用 OBSBasic,而要隔一层 obs_frontend_api?"稳定 API"对插件生态有什么好处?
2. 玩 obs-websocket:如果你装过 obs-websocket 插件(OBS 内置了),看它能远程"切场景/开始录制"—— 那背后就是本课的 obs_frontend_* 调用 + 事件回调。
3. 看属性自动生成:随便打开两个不同源(如"文本"和"图像")的属性,对比控件差异 —— 它们都是同一套 properties-view 照着各自的 obs_properties 画的。
4. 理解数据驱动:说清"源声明属性 → 界面自动生成"和第 25 课"平台写进 JSON → 自动填设置"是同一种思想。它们共同的好处是什么?
5. 翻源码:打开 frontend/api/obs-frontend-api.cpp:225 看 obs_frontend_streaming_start 的薄转发;frontend/OBSStudioAPI.cpp:221 看真实现;shared/properties-view/properties-view.cpp:1490 看那个类型 switch;:1699 看 obs_data_set_int 写回。

下一课预告

到这里,引擎(模块 1~6)和界面(模块 7 前两课)都讲完了。最后一课,把所有 28 课串成一个完整的故事:从你按下"开始直播",一帧画面如何被采集、合成、编码、封装、推流,一路走到观众的屏幕 —— 每一步落在前面哪一课、哪个 obs_* 函数上。

第 28 课:全链路总复盘 —— 追踪一帧的完整旅程 —— 模块 7、也是整门课的收官。我们不引入新知识,而是拿一帧真实的画面当主角,让它走完整条流水线,把你学过的一切连成一条线。下节课见。

---

📁 本课配图:imgs/27-01 ~ imgs/27-09 📌 源码锚点: obs-frontend-api frontend/api/obs-frontend-api.h:16(enum obs_frontend_event)、:160(event_cb typedef)、:162(add_event_callback)、:153(add_dock_by_id)；frontend/api/obs-frontend-internal.hpp:8(struct obs_frontend_callbacks 门面 vtable)、:15/:40/:65(成员)、:143(set_callbacks_internal)；frontend/api/obs-frontend-api.cpp:6(static unique_ptr c)、:8(setter)、:13(callbacks_valid)、:99(get_current_scene 转发)、:225(streaming_start 转发)、:330(add_event_callback 转发)、:314(add_dock_by_id 转发)；frontend/OBSStudioAPI.hpp:31(struct OBSStudioAPI : obs_frontend_callbacks)；frontend/OBSStudioAPI.cpp:54(get_current_scene 真实现)、:221(streaming_start → invokeMethod)、:709(on_event 广播)、:721(InitializeAPIInterface)、:332(add_dock 实现)；frontend/widgets/OBSBasic.cpp:244(api = InitializeAPIInterface)、:2136(OnEvent)、:1119(发 SCENE_CHANGED)、:1990(卸载门面)； properties-view libobs/obs-properties.h:45(enum obs_property_type)、:270(obs_property_get_type)、:274(obs_property_next)；libobs/obs-source.h:291(get_properties 回调)；libobs/obs-source.c:1024(obs_source_properties)；shared/properties-view/properties-view.cpp:131(RefreshProperties 遍历)、:1490(AddProperty type switch)、:427(AddInt)、:467(connect valueChanged→ControlChanged)、:618(AddList)、:1962(ControlChanged)、:1696/:1699(IntChanged / obs_data_set_int)、:2048(visUpdateCb = obs_source_update)、:2053(obs_property_modified → RefreshProperties)；shared/properties-view/properties-view.hpp:16-17(回调 typedef)；frontend/dialogs/OBSBasicProperties.cpp:71-73(装配 obs_source_properties + obs_source_update)。 注:稳定 API / 门面 / 数据驱动 UI 为通用软件设计思想,非 OBS 特有。