OBS Studio 前端集成指南：libobs 初始化、预览渲染、信号系统与输出管线配置

本文基于 OBS Studio 仓库中的官方前端文档 frontends.rst，系统讲解第三方程序如何以 libobs 作为底层渲染/采集引擎构建自己的前端（Frontend）：从 libobs 的初始化与模块加载顺序，到预览窗口（Display）的绘制机制、场景与转场的组织方式，再到输出、编码器、推流服务的完整接线流程与信号回调用法。读完本文，你可以为 OBS 内核编写一个独立的应用层，完成启动、预览、场景切换与直播/录制输出的全部核心工作，并能结合仓库源码验证每一步的 API 签名与实现位置。

libobs 的初始化与关闭流程

前端程序要使用 libobs，必须严格按照以下顺序完成启动：

1. 调用 obs_startup() 初始化 libobs 核心；
2. 调用 obs_reset_video() 设置视频参数（分辨率、帧率、色彩空间等）；
3. 调用 obs_reset_audio() 设置音频参数（采样率、声道布局等）；
4. 加载各插件模块（源、输出、编码器、转场等均由模块提供）。

模块加载有两种方式。其一是手动加载单个模块：先调用 obs_open_module() 打开模块，之后必须调用 obs_init_module() 完成该模块的初始化。从 obs-module.c 可以看到，obs_open_module() 负责解析模块的导出函数表并建立模块结构体，obs_init_module() 才真正调用模块的 obs_module_load 回调，两者缺一不可。其二是自动批量加载：先用 obs_add_module_path() 注册模块的 bin/data 搜索路径（声明见 obs.h），再调用 obs_load_all_modules() 扫描并加载路径下所有模块，实现位于 obs-module.c。

所有插件模块加载完毕后，还要调用 obs_post_load_modules()，给各模块提供"依赖模块已全部就绪"后的二次初始化时机。

此外，部分模块会用到一个可选的配置存储目录，该目录在 obs_startup() 的参数中设置，供模块持久化自身配置使用。

关闭流程则要求前端先释放所有对象的引用、释放所有动态数据，再调用 obs_shutdown()。文档特别指出，若确实存在未释放的 libobs 对象，它们会被自动销毁并记录一条警告日志，因此 shutdown 过程不会因遗留对象而崩溃。若要检测一般性内存分配是否有泄漏，可调用 bnum_allocs() 查询当前未释放的分配计数：返回值大于 0 即说明存在内存泄漏（该函数属于 libobs 基础内存分配 API，见 libobs/util）。

重新配置视频参数

初始化完成后的任何时刻，只要当前没有活动中的输出（output），都可以再次调用 obs_reset_video() 重新配置视频设置——这意味着前端可以在运行时修改分辨率、帧率等视频参数并热切换。

音频则不同：早期设计中音频也打算支持这种热重置能力，但当前版本下音频一旦初始化就无法重置；要重新配置音频参数，必须先把 libobs 完整 shutdown 再重新初始化。编写前端时需要对视频与音频的可重配置能力区别对待。

预览窗口（Display）的创建与绘制

Display 是前端用于呈现预览窗格的核心机制。使用 Display 的前提是你必须持有一个原生窗口句柄（或标识符），即实际要绘制上去的窗口表面。

完整的 Display 生命周期如下：

1. 创建：调用 obs_display_create() 初始化 display。从 obs.h 的声明注释可知，它会创建一条新的交换链（swap chain），每一帧都会随主渲染管线刷新，参数 graphics_data 就是交换链的初始化数据（struct gs_init_data），第二个参数是背景色；
2. 绑定绘制回调：用 obs_display_add_draw_callback() 注册每帧绘制回调，签名为 void (*draw)(void *param, uint32_t cx, uint32_t cy)（见 obs.h）；不再需要时用 obs_display_remove_draw_callback() 移除，参数需与添加时一致；
3. 绘制主预览：在绘制回调中，调用 obs_render_main_texture() 画主预览内容（即当前分配给输出通道的画面）；
4. 在次级窗口绘制单个源：把某个源"展示"到另一个 preview 窗口时，先调用 obs_source_inc_showing() 提升其 showing 计数，在绘制回调中用 obs_source_video_render() 绘制它，不再展示时调用 obs_source_dec_showing() 降计数；
5. 尺寸与外观：窗口尺寸变化时调用 obs_display_resize() 调整 display 大小；需要非黑色背景时调用 obs_display_set_background_color()（对应声明见 obs.h）；
6. 临时禁用：用 obs_display_set_enabled() 开启/禁用该 display，用 obs_display_enabled() 查询当前启用状态；
7. 销毁：不再需要时调用 obs_display_destroy()。

重要提示：不要在同一个基窗口的控件层级中同时使用多个 display 控件，这在 macOS 上会导致画面呈现（presentation）卡顿。

OBS 官方前端自带的 Qt 预览控件 OBSQTDisplay 就是文档所述 Display 用法的真实落地（旧文档中的 UI/qt-display.hpp/.cpp 在现仓库中已演进为此组件）。从 OBSQTDisplay.cpp 可以看到其实现路径与文档描述完全对应：构造函数中通过 nativeEvent 拿到平台窗口句柄后调用 obs_display_create(&info, backgroundColor)（OBSQTDisplay.cpp）；resizeEvent 中随窗口尺寸调用 obs_display_resize(display, size.width(), size.height())（OBSQTDisplay.cpp），默认背景色定义为 0xFF4C4C4C（见 OBSQTDisplay.hpp）。

对象的保存与加载

前端一般需要自行管理自己的对象。对源（source）来说，libobs 提供了一组便捷的批量保存/加载辅助函数：

• obs_save_sources() / obs_load_sources()：自动保存和加载所有非私有源；
• obs_save_source() / obs_load_source()：手动保存/加载单个源。

文档作者还留下一段自省式备注：这些批量辅助函数带来了一个副作用——不得不引入不可被批量保存的"私有源"概念（通过 obs_source_create_private() 创建），作者将其自嘲为"长期开发过程中常见的细微设计缺陷之一"。这提示第三方开发者：私有源不会被 obs_save_sources() 触及，必须自己管理其生命周期与持久化。

对输出（output）、编码器（encoder）和服务（service）则没有批量辅助函数，通常的做法是逐个取出它们的 settings 并保存为 JSON。文档给出的推荐方式是：不必把每个对象分开存文件，而是把多个对象的 settings 汇总到同一个较大的 obs_data_t 对象里，然后用 obs_data_save_json_safe() 落盘、用 obs_data_create_from_json_file_safe() 整体读回（单个输出的 settings 可参考 obs_output_get_settings() 获取）。

核心信号系统（Signals）

libobs 的核心（core）、场景（scene）和源（source）都带有一组标准信号，用于通知状态变化事件。其中最重要的是输出信号：start、stop、starting、stopping、reconnect、reconnect_success 这组信号是前端感知推流/录制生命周期的关键入口。

场景/源上的大多数信号，如果你是自己唯一的状态控制器，可以选择不监听；但文档仍建议尽量监听尽可能多的信号以保证行为一致性。

以"给输出连接 stop 回调"为例。stop 信号带两个参数：output 与 code，回调的典型写法为：

static void output_stopped(void *my_data, calldata_t *cd)
{
	obs_output_t *output = calldata_ptr(cd, "output");
	int code = calldata_int(cd, "code");

	[...]
}

注意：信号回调不是线程安全的（not thread-safe），不要假设它会在固定的线程上执行。

把回调挂到 stop 信号上，使用 signal_handler_connect()：

signal_handler_t *handler = obs_output_get_signal_handler(output);
signal_handler_connect(handler, "stop", output_stopped);

源的画面组织：输出通道、场景与转场

源画面最终通过**输出通道（output channels）**进入推流/录制。用 obs_set_output_source() 可以把源分配到通道上，共有 64 个通道，按索引升序依次叠加绘制。不过普通源通常不应直接分配到通道——实际使用中你会分配场景（scene）或包含场景的转场（transition）。

场景与场景项

场景用于把多个源按指定变换关系组合在一起。创建场景调用 obs_scene_create()；场景中的子源通过"场景项（scene item）"引用，变换则施加在场景项上。要点：

• 场景项不是源，而是源的容器：同一个源可以被同一场景内的多个场景项引用，也可以被多个不同场景引用；
• 为场景添加引用某个源的场景项，调用 obs_scene_add()，返回一个新引用的场景项；
• 修改场景项变换：obs_sceneitem_set_pos() 改位置、obs_sceneitem_set_rot() 改旋转、obs_sceneitem_set_scale() 改缩放；
• 边界框（bounding box）：场景项可强制源按特定尺寸与缩放约束绘制。启用方式为依次调用 obs_sceneitem_set_bounds_type()、obs_sceneitem_set_bounds()、obs_sceneitem_set_bounds_alignment()；
• 最省事的做法是直接 obs_sceneitem_set_info2() / obs_sceneitem_get_info2() 批量读写整套变换信息。

转场与推荐层级结构

场景之间的平滑切换依赖转场。转场本身也是源：像创建其他源一样用 obs_source_create() 或 obs_source_create_private() 创建，然后用 obs_transition_start() 激活。转场未激活、只展示单个源时，会直接透传（pass-through）当前正在显示的源。

文档推荐的层级结构是：

主输出源 = 转场
   └── 场景（转场的子项）
         └── 各个源（场景的子项）

即把转场作为主输出源，场景作为转场的子项，源作为场景的子项；需要切换场景时只需调用 obs_transition_start()。OBS 官方前端的场景集合、场景项与转场管理分别可见 OBSBasic_SceneCollections.cpp、OBSBasic_SceneItems.cpp、OBSBasic_Transitions.cpp。

输出、编码器与服务的接线

输出、编码器、服务三者配合使用，且管理方式与源不同——目前没有全局函数批量保存/加载它们，需要基于各自 settings 手动持久化（如前文 JSON 方式所述）。

• 编码器：用于期望接收编码数据的输出（几乎所有常规输出都是如此，如标准文件录制或推流）；
• 服务（service）：用于推流类输出，最典型的例子就是 RTMP 输出，其实现位于 plugins/obs-outputs/rtmp-stream.c。

文档给出的输出接线示例完整呈现了编码器与服务如何挂到输出上：

obs_encoder_set_video(my_h264_encoder, obs_get_video());
obs_encoder_set_audio(my_aac_encoder, obs_get_audio());
obs_output_set_video_encoder(my_output, my_h264_encoder);
obs_output_set_audio_encoder(my_output, my_aac_encoder);
obs_output_set_service(my_output, my_service); /* 推流时 */
obs_output_start(my_output);

obs_output_start() 成功启动后，输出会自动开始从当前视频/音频输出通道采集数据（也就是分配到 64 个输出通道上的那些源）。

若输出启动失败，它会发出 stop 信号，code 参数中携带错误码，并且通常还会附带一条经过翻译的错误信息，可再通过 obs_output_get_last_error() 取出——结合前文的 stop 信号回调，前端就能完整处理"启动失败"与"运行中停止"两种路径。

小结

frontends.rst 勾勒出的 libobs 前端集成路径可以浓缩为五条主线：

1. 启动/关闭：obs_startup() → obs_reset_video() → obs_reset_audio() → 模块加载 → obs_post_load_modules()；关闭时先释放对象再 obs_shutdown()，并用 bnum_allocs() 查漏；
2. 热重配置：视频可随 obs_reset_video() 重置（无活动输出时），音频必须完整重启 libobs；
3. 预览：obs_display_create() + 绘制回调 + obs_render_main_texture()，macOS 上同窗口层级避免多 display；
4. 持久化：源用 obs_save_sources()/obs_load_sources()（私有源需自理），输出/编码器/服务用 settings + obs_data_save_json_safe() 整体存 JSON；
5. 画面与输出：64 个输出通道 + 场景项变换 + 转场作为主输出源的推荐层级，编码器与服务通过 obs_output_set_* 接线，失败路径经由 stop 信号与 obs_output_get_last_error() 暴露。

掌握这套 API 契约，就能在 OBS Studio 内核之上构建自定义前端，而不必重复其 UI 层的任何逻辑。