前端 API

相关源文件

• docs/sphinx/reference-frontend-api.rst

OBS Studio 前端 API 提供了一个编程接口，供插件与 OBS Studio 用户界面 (UI) 进行交互。与处理视频/音频核心的 libobs API 不同，前端 API 允许插件控制 UI 元素、响应 UI 事件、访问配置、通过 UI 管理场景和源，以及控制直播和录制操作。

本页将介绍前端 API 的结构、函数、事件以及插件开发者可用的集成点。

概述

前端 API 定义在头文件 obs-frontend-api.h，并提供多个功能类别

• 事件监控（直播开始/停止、场景切换等）
• UI 自定义（添加菜单项、面板）
• 场景和源管理
• 直播和录制控制
• 配置文件和场景集合管理
• 配置访问
• 演播室模式控制

来源：docs/sphinx/reference-frontend-api.rst1-7

架构

前端 API 是插件与 OBS Studio UI 之间的桥梁。它在整个 OBS 架构中的作用如下：

来源：docs/sphinx/reference-frontend-api.rst4-8

前端事件

前端 API 提供了一个事件系统，插件可以使用它来响应 OBS Studio UI 中的各种操作。事件由 obs_frontend_event 枚举表示。

要订阅这些事件，插件可以使用 obs_frontend_add_event_callback() 并提供一个回调函数。当发生任何注册的事件时，将触发该回调。

示例事件类别

事件类别	示例	目的
流式传输	OBS_FRONTEND_EVENT_STREAMING_STARTING, OBS_FRONTEND_EVENT_STREAMING_STOPPED	通知直播状态更改
录制	OBS_FRONTEND_EVENT_RECORDING_STARTED, OBS_FRONTEND_EVENT_RECORDING_PAUSED	通知录制状态更改
场景	OBS_FRONTEND_EVENT_SCENE_CHANGED, OBS_FRONTEND_EVENT_SCENE_LIST_CHANGED	通知场景已修改
切换	OBS_FRONTEND_EVENT_TRANSITION_CHANGED, OBS_FRONTEND_EVENT_TRANSITION_STOPPED	通知切换状态更改
配置文件	OBS_FRONTEND_EVENT_PROFILE_CHANGED, OBS_FRONTEND_EVENT_PROFILE_LIST_CHANGED	通知配置文件已修改
演播室模式	OBS_FRONTEND_EVENT_STUDIO_MODE_ENABLED, OBS_FRONTEND_EVENT_PREVIEW_SCENE_CHANGED	通知演播室模式状态更改
应用程序	OBS_FRONTEND_EVENT_EXIT, OBS_FRONTEND_EVENT_FINISHED_LOADING	通知应用程序生命周期事件

来源：docs/sphinx/reference-frontend-api.rst14-186

场景和源管理

前端 API 允许插件通过 OBS UI 与场景和源进行交互

关键场景管理函数

功能	目的
obs_frontend_get_scenes()	获取可用场景列表
obs_frontend_get_current_scene()	获取当前活动的场景
obs_frontend_set_current_scene()	设置当前活动的场景
obs_frontend_get_transitions()	获取可用切换列表
obs_frontend_get_current_transition()	获取当前活动的切换
obs_frontend_set_current_transition()	设置当前活动的切换

来源：docs/sphinx/reference-frontend-api.rst246-366

直播和录制控制

前端 API 提供了控制直播、录制、回放缓冲区和虚拟摄像头操作的函数

这些函数允许插件以编程方式控制 OBS 的输出系统。例如，插件可以在特定时间自动录制或为直播操作提供自定义 UI 控件。

来源：docs/sphinx/reference-frontend-api.rst602-872

配置文件和场景集合管理

OBS Studio 使用配置文件来存储设置，使用场景集合来存储场景和源的排列。前端 API 提供了管理这些的函数

功能	目的
obs_frontend_get_scene_collections()	获取可用场景集合列表
obs_frontend_get_current_scene_collection()	获取当前场景集合的名称
obs_frontend_set_current_scene_collection()	切换到指定的场景集合
obs_frontend_add_scene_collection()	创建新的场景集合
obs_frontend_get_profiles()	获取可用配置文件列表
obs_frontend_get_current_profile()	获取当前配置文件的名称
obs_frontend_set_current_profile()	切换到指定的配置文件
obs_frontend_create_profile()	创建新的配置文件
obs_frontend_duplicate_profile()	创建当前配置文件的副本

来源：docs/sphinx/reference-frontend-api.rst368-443

UI 集成

前端 API 允许插件通过添加菜单项、面板和处理 UI 翻译来与 OBS Studio UI 集成

工具菜单集成

插件可以使用以下方法将菜单项添加到“工具”菜单中：

• obs_frontend_add_tools_menu_item() - 添加带有回调的菜单项
• obs_frontend_add_tools_menu_qaction() - 向菜单添加 QAction 以获得更复杂的控制

面板（Dock Widget）集成

插件可以向 OBS UI 添加面板

• obs_frontend_add_dock_by_id() - 添加一个标识符可以稍后移除的面板
• obs_frontend_add_custom_qdock() - 添加一个自定义 QDockWidget
• obs_frontend_remove_dock() - 移除先前添加的面板

UI 翻译

插件可以与 OBS 的翻译系统集成

• obs_frontend_push_ui_translation() - 注册一个翻译回调
• obs_frontend_pop_ui_translation() - 移除一个翻译回调

来源：docs/sphinx/reference-frontend-api.rst445-600

演播室模式控制

演播室模式在 OBS 中提供预览和节目视图。前端 API 提供了控制此功能的功能

功能	目的
obs_frontend_preview_program_mode_active()	检查演播室模式是否处于活动状态
obs_frontend_set_preview_program_mode()	启用或禁用演播室模式
obs_frontend_preview_program_trigger_transition()	触发从预览到节目的切换
obs_frontend_get_current_preview_scene()	获取当前预览中的场景
obs_frontend_set_current_preview_scene()	设置要显示在预览中的场景

来源：docs/sphinx/reference-frontend-api.rst783-832

配置访问

前端 API 提供对各种配置文件​​的访问

这些函数提供对 OBS Studio 使用的各种配置文件​​的访问。插件可以读取和修改这些设置以与 OBS 的配置系统集成。

来源：docs/sphinx/reference-frontend-api.rst733-759

常见用法模式

事件驱动的插件逻辑

许多插件使用前端 API 来响应 OBS 事件

// Register for frontend events
obs_frontend_add_event_callback(frontend_event_callback, plugin_data);

// Event callback function
void frontend_event_callback(enum obs_frontend_event event, void *data) {
    switch(event) {
        case OBS_FRONTEND_EVENT_STREAMING_STARTING:
            // Do something when streaming is starting
            break;
        case OBS_FRONTEND_EVENT_RECORDING_STOPPED:
            // Do something when recording stops
            break;
        // Other events...
    }
}

插件的 UI 集成

插件通常需要添加 UI 元素

// Add a tools menu item
obs_frontend_add_tools_menu_item("My Plugin", tools_menu_clicked, plugin_data);

// Add a dock widget
QWidget *widget = new QWidget();
// Configure widget
obs_frontend_add_dock_by_id("my_plugin_dock", "My Plugin Dock", widget);

场景和源管理

访问和管理场景和源

// Get current scene
obs_source_t *scene = obs_frontend_get_current_scene();
// Do something with the scene
obs_source_release(scene);

// Get list of all scenes
struct obs_frontend_source_list scenes = {0};
obs_frontend_get_scenes(&scenes);
// Process scenes
obs_frontend_source_list_free(&scenes);

来源：docs/sphinx/reference-frontend-api.rst200-220