OBS Source Record 插件开发指南：独立录制特定源的实现与应用

一、功能解析：OBS Source Record 核心价值

1.1 插件定位与优势

OBS Source Record 是一款专为 OBS Studio 设计的轻量级插件，核心功能是独立录制场景中的单个或多个音视频源。与传统全屏录制不同，它允许用户精准选择需要捕获的内容，避免后期剪辑的繁琐操作，特别适合教程制作、直播素材采集等场景。

1.2 核心功能清单

• 源隔离录制：支持同时录制多个独立源，如摄像头、窗口捕获、媒体文件等
• 自定义参数配置：可设置输出格式（MP4/MKV）、存储路径及视频质量
• 热键集成：通过 OBS 热键系统控制录制启停，提升操作效率
• 多语言支持：内置 7 种语言配置文件，包括中文、英文、日文等

1.3 技术栈概览

技术领域	选型方案	应用场景
开发语言	C	核心逻辑实现、性能敏感模块
构建系统	CMake	跨平台编译、依赖管理
外部依赖	OBS Studio API	音视频处理、插件生命周期管理
资源管理	INI 配置文件	本地化字符串、UI 文本定义
版本控制	CMake 模板文件	动态注入版本号、构建信息

二、环境搭建：从零开始的开发准备

2.1 开发环境要求

• 操作系统：Windows 10/11（64位）、macOS 12+ 或 Linux（Ubuntu 20.04+）
• 工具链：
  • Windows：Visual Studio 2022（含 C++ 桌面开发组件）
  • macOS：Xcode 13+ 及 Command Line Tools
  • Linux：GCC 9+、CMake 3.18+
• 依赖库：OBS Studio SDK（29.0.0+）、pthreads（跨平台线程库）

2.2 项目获取与编译步骤

1. 克隆代码仓库

   git clone https://gitcode.com/gh_mirrors/ob/obs-source-record
   cd obs-source-record
   

2. 创建构建目录

   mkdir build && cd build
   

3. 生成项目文件

   • Windows：cmake .. -G "Visual Studio 17 2022" -A x64
   • macOS：cmake .. -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0
   • Linux：cmake .. -DCMAKE_BUILD_TYPE=Release

4. 编译项目

   • Windows：在 Visual Studio 中打开生成的解决方案并构建
   • macOS/Linux：make -j4（-j4 表示使用4核并行编译）

2.3 开发工具推荐

• 代码编辑器：Visual Studio Code（建议安装 C/C++、CMake Tools 扩展）
• 调试工具：OBS Studio 内置日志（工具 > 脚本日志）、GDB（Linux/macOS）
• 文档参考：OBS Studio 官方 API 文档（本地可通过 SDK 附带的 HTML 文件访问）

三、核心模块：插件架构与实现逻辑

3.1 文件结构解析

obs-source-record/
├── 核心代码文件
│   ├── source-record.c       # 主逻辑实现（录制控制、帧处理）
│   ├── source-record.h       # 数据结构与函数声明
│   └── version.h.in          # 版本信息模板（由 CMake 动态生成）
├── 构建配置文件
│   ├── CMakeLists.txt        # 项目构建主配置
│   ├── buildspec.json        # 构建环境规范
│   └── cmake/
│       └── ObsPluginHelpers.cmake  # OBS 插件构建辅助函数
└── 资源文件
    ├── data/locale/          # 多语言配置（如 zh-CN.ini）
    ├── media/                # 图标资源
    └── resource.rc.in        # 资源编译模板

3.2 核心模块详解

3.2.1 录制引擎（source-record.c）

核心要点：该模块是插件的心脏，负责音视频数据的捕获、编码与存储。关键函数包括：

• source_record_filter_create：初始化录制上下文，建立与 OBS 主程序的通信
• video_filter_render：处理每一帧视频数据，实现源隔离
• audio_input_callback：处理音频输入，支持多轨道混合

3.2.2 构建系统（CMakeLists.txt）

通过 CMake 管理整个构建流程，主要功能包括：

• 版本控制：通过 configure_file(version.h.in version.h) 动态生成版本头文件
• 条件编译：针对不同平台（Windows/macOS/Linux）设置特定编译选项
• 安装规则：定义插件库文件和资源的安装路径

3.2.3 本地化系统（data/locale/）

通过 INI 格式文件实现多语言支持，例如 zh-CN.ini 包含中文界面文本。添加新语言时，需确保键名与英文版本（en-US.ini）保持一致，否则会导致界面文本缺失。

四、实战指南：常见操作与问题解决

4.1 基础功能使用步骤

1. 安装插件：将编译生成的插件文件（.dll/.so/.dylib）复制到 OBS 插件目录

   • Windows：C:\Program Files\obs-studio\obs-plugins\64bit\
   • macOS：~/Library/Application Support/obs-studio/plugins/
   • Linux：~/.config/obs-studio/plugins/

2. 配置录制参数：

   • 在 OBS 场景中添加需要录制的源
   • 打开插件设置面板（工具 > Source Record）
   • 设置输出路径、文件格式及视频质量

3. 开始录制：

   • 通过插件面板按钮或自定义热键启动录制
   • 录制状态会在 OBS 状态栏显示
   • 结束录制后文件自动保存至指定路径

4.2 常见问题 Q&A

Q：录制文件无法生成，如何排查？
A：首先检查输出路径是否存在且可写，可通过 source-record.c 中的 ensure_directory 函数确保目录创建。其次检查 OBS 日志（工具 > 脚本日志）是否有错误信息。

Q：多源录制时出现音画不同步怎么办？
A：在插件设置中降低视频帧率或调整音频缓冲区大小。核心代码中可修改 audio_input_callback 函数的同步逻辑。

Q：如何添加新的语言支持？
A：在 data/locale/ 目录下创建新的 INI 文件（如 fr-FR.ini），复制 en-US.ini 的内容并翻译，然后在 resource.rc.in 中添加该语言资源。

五、进阶方向：功能扩展与性能优化

5.1 功能扩展建议

5.1.1 多源同步录制

当前版本仅支持独立录制多个源，可通过修改 source_record_filter_context 结构体添加源列表管理，实现多源同步录制功能。需注意线程安全和资源占用问题。

5.1.2 录制计划任务

添加定时录制功能，可参考 OBS 的定时推流实现，在 source-record.c 中添加定时器逻辑，结合配置文件存储计划任务。

5.2 性能优化方向

• 视频处理优化：在 video_filter_render 函数中减少内存拷贝，使用直接内存访问（DMA）技术
• 编码参数调优：根据硬件性能动态调整编码参数，平衡质量与资源占用
• 日志系统改进：添加分级日志（DEBUG/INFO/WARN/ERROR），便于问题定位

5.3 学习资源推荐

• OBS 插件开发入门：官方文档中的 "Plugin Development" 章节
• 代码示例：参考 OBS 官方插件库中的 obs-websocket 项目
• 社区支持：OBS 开发者论坛及 Discord 社区

图：OBS Source Record 项目官方标识