探索 OBS Studio 音视频推流技术（6）：脚本编程

这个系列文章我们来介绍一位海外工程师如何探索 OBS Studio 音视频推流技术，对于想要开始学习音视频技术的朋友，这些文章是份不错的入门资料，这是第 6 篇：脚本编程。

—— 来自公众号关键帧Keyframe的分享

脚本编程 (21.0+) 增加了对 Python 3 和 Luajit 2（大致相当于 Lua 5.2）的支持，允许快速扩展、添加功能或自动化程序，无需构建原生插件模块。

可以通过 OBS Studio 的工具菜单中的脚本选项访问脚本编程，这将弹出脚本对话框。脚本可以在程序运行时实时添加、移除和重新加载。

注意： 在 Windows 或 macOS 上使用 Python 时，必须下载并安装与 OBS 架构匹配的 Python 版本。然后，在脚本对话框中，必须在 “Python 设置” 选项卡中设置 Python 安装路径。

所有 API 绑定在 Python 中通过 obspython 模块提供，在 Lua 中通过 obslua 模块提供。

为了提供脚本回调，某些函数已被更改/替换，更多信息请参见与 C API 的其他差异。

警告： 由于提供了整个 API 的绑定，使用编写不当的脚本可能会导致内存泄漏或程序崩溃。请在编写脚本时小心谨慎，并检查日志文件中的内存泄漏计数器，以确保您编写的脚本没有内存泄漏。请将 API 绑定视为编写 C 程序：阅读您所使用函数的文档，并通过 API 引用或创建的对象进行释放/销毁。

1、脚本功能导出

脚本可以提供以下多个全局函数：

1.1、script_description()

被调用以获取要在脚本窗口中显示给用户的描述字符串。

1.2、script_load(settings)

在脚本启动时被调用，具有与脚本相关的特定设置。提供的 settings 参数通常不用于用户设置的设置；相反，该参数用于脚本可能使用的任何额外内部设置数据。

参数：

settings – 与脚本相关的设置。

1.3、script_unload()

在脚本被卸载时被调用。

1.4、script_save(settings)

在脚本被保存时被调用。这对于用户设置的设置不是必需的；相反，这是用于脚本可能使用的任何额外内部设置数据。

参数：

settings – 与脚本相关的设置。

1.5、script_defaults(settings)

被调用以设置与脚本相关的默认设置（如果有）。通常会为设置调用默认值函数，以设置其默认值。

参数：

settings – 与脚本相关的设置。

1.6、script_update(settings)

在用户更改脚本的设置（如果有）时被调用。

参数：

settings – 与脚本相关的设置。

1.7、script_properties()

被调用以定义与脚本关联的用户属性。这些属性用于定义如何向用户显示设置属性。

返回值：

通过 obs_properties_create() 创建的 obs_properties_t 对象。

1.8、script_tick(seconds)

在每一帧中被调用，以满足每帧处理的需要。如果需要计时器，请使用脚本计时器，因为如果只需要基本计时器功能，计时器效率更高。不推荐在 Python 中使用此函数，因为 Python 的全局解释器锁。

参数：

seconds – 自上一帧以来经过的秒数。

2、获取当前脚本的路径

有一个可以用来获取当前脚本路径的函数。此函数在脚本加载之前自动实现到每个脚本中，并且是脚本名称空间的一部分，而不是 obslua/obspython 的一部分：

2.1、script_path()

返回值：

脚本的路径。

3、脚本计时器

脚本计时器提供了一种有效的计时器回调方式，无需每帧锁定脚本/解释器。

（这些函数是 obspython/obslua 模块/名称空间的一部分）。

3.1、timer_add(callback, milliseconds)

添加一个计时器回调，该回调每 milliseconds 触发一次。

注意：不支持将实例方法用作回调。请始终使用模块方法。

3.2、timer_remove(callback)

移除计时器回调。（注意：你也可以使用 remove_current_callback() 从计时器回调中终止计时器）

4、脚本源（仅限 Lua）

可以在 Lua 中注册源。为此，创建一个表，并像定义 obs_source_info 结构一样定义其键：

local info = {}
info.id = "my_source_id"
info.type = obslua.OBS_SOURCE_TYPE_INPUT
info.output_flags = obslua.OBS_SOURCE_VIDEO

info.get_name = function()
        return "My Source"
end

info.create = function(settings, source)
        -- 通常源数据将作为表存储
        local my_source_data = {}

        [...]

        return my_source_data
end

info.video_render = function(my_source_data, effect)
        [...]
end

info.get_width = function(my_source_data)
        [...]

        -- 假设源数据包含 'width' 键
        return my_source_data.width
end

info.get_height = function(my_source_data)
        [...]

        -- 假设源数据包含 'height' 键
        return my_source_data.height
end

-- 注册源
obs_register_source(info)

5、与 C API 的其他差异

由于回调的工作方式，某些函数的实现与 C API 不同。（这些函数是 obspython/obslua 模块/名称空间的一部分）。

5.1、obs_enum_sources()

枚举所有源。

返回值：

引用计数增加的源数组。使用 source_list_release() 释放。

5.2、obs_scene_enum_items(scene)

枚举场景中的场景项。

参数：

scene – 要枚举项的 obs_scene_t 对象。

返回值：

场景项列表。使用 sceneitem_list_release() 释放。

5.3、obs_sceneitem_group_enum_items(group)

枚举组中的场景项。

参数：

group – 要枚举项的 obs_sceneitem_t 对象。

返回值：

场景项列表。使用 sceneitem_list_release() 释放。

5.4、obs_add_main_render_callback(callback)

仅限 Lua： 添加主输出渲染回调。此回调没有参数。

参数：

callback – 渲染回调。使用 obs_remove_main_render_callback() 或 remove_current_callback() 移除回调。

5.5、obs_remove_main_render_callback(callback)

仅限 Lua： 移除主输出渲染回调。

参数：

callback – 要移除的热键回调。

5.6、signal_handler_connect(handler, signal, callback)

将回调添加到信号处理程序上的特定信号。此回调有一个参数：calldata_t 对象。

参数：

• handler – 信号处理程序对象。
• signal – 信号处理程序上的信号（字符串）。
• callback – 要连接到信号的回调。使用 signal_handler_disconnect() 或 remove_current_callback()移除回调。

5.7、signal_handler_disconnect(handler, signal, callback)

从信号处理程序上的特定信号移除回调。

参数：

• handler – 信号处理程序对象。
• signal – 信号处理程序上的信号（字符串）。
• callback – 要断开连接的回调。

5.8、signal_handler_connect_global(handler, callback)

将全局回调添加到信号处理程序。此回调有两个参数：第一个参数是信号字符串，第二个参数是 calldata_t 对象。

参数：

• handler – 信号处理程序对象。
• callback – 要连接的回调。使用 signal_handler_disconnect_global() 或 remove_current_callback() 移除回调。

5.9、signal_handler_disconnect_global(handler, callback)

从信号处理程序移除全局回调。

参数：

• handler – 信号处理程序对象。
• callback – 要断开连接的回调。

5.10、obs_hotkey_register_frontend(name, description, callback)

添加前端热键。回调有一个参数：表示 “按下” 参数的布尔值。

参数：

• name – 热键的唯一名称标识符字符串。
• description – 显示给用户的热键描述。
• callback – 热键回调。使用 obs_hotkey_unregister() 或 remove_current_callback() 移除回调。

5.11、obs_hotkey_unregister(callback)

注销与指定回调关联的热键。

参数：

callback – 要注销的热键回调。

5.12、obs_properties_add_button(properties, setting_name, text, callback)

向 obs_properties_t 对象添加按钮属性。回调有两个参数：第一个参数是 obs_properties_t 对象，第二个参数是按钮的 obs_property_t。

参数：

• properties – obs_properties_t 对象。
• setting_name – 设置标识符字符串。
• text – 按钮文本。
• callback – 按钮回调。此回调将自动清理。

5.13、remove_current_callback()

移除正在执行的当前回调。如果不在回调中，则不执行任何操作。

5.14、source_list_release(source_list)

释放源列表的引用。

参数：

source_list – 要释放的源数组。

5.15、sceneitem_list_release(item_list)

释放场景项列表的引用。

参数：

item_list – 要释放的场景项数组。

5.16、calldata_source(calldata, name)

将 calldata_t 对象的指针参数转换为 obs_source_t 对象。

参数：

• calldata – calldata_t 对象。
• name – 参数名称。

返回值：

对 obs_source_t 对象的借用引用。

5.17、calldata_sceneitem(calldata, name)

将 calldata_t 对象的指针参数转换为 obs_sceneitem_t 对象。

参数：

• calldata – calldata_t 对象。
• name – 参数名称。

返回值：

对 obs_sceneitem_t 对象的借用引用。

音视频方向学习、求职，欢迎加入我们的星球

丰富的音视频知识、面试题、技术方案干货分享，还可以进行面试辅导