如何编写可在 OBS 中运行的 Python 脚本

将 Python 脚本函数导出至 OBS

当一个 Python 脚本拥有特定名称和参数的函数时，OBS 将发现并使用这些函数来实现某些效果，比如，在 OBS 中显示一段说明脚本作用的文字。Python 脚本与 OBS 之间的这种联系，被官方称为脚本函数导出（Script Function Exports）。

在 OBS 中展示 Python 脚本说明

每一个成功载入 OBS 的 Python 脚本，都会在脚本窗口中拥有一段说明信息。通过在脚本中定义一个名为script_description的函数，你可以设置该脚本的相关说明文字，当然，script_description应返回一个字符串。

# 导入模块 obspython
import obspython as obs


def script_description():
	return '这是一个简单但没有任何效果的脚本\n作者：\t哎呦喂\n版本：\t0.1\n联系：\txxx'

在 OBS 中展示 Python 脚本属性

函数script_properties是非常重要的，当你希望 Python 脚本与用户可以交互时，该函数需要返回一个包含脚本相关属性信息的属性集对象。OBS 将根据script_properties返回的属性集对象，在脚本窗口中创建一系列的控件，比如文本框，按钮，复选框等。通过这些控件，用户可以修改调整脚本的属性，从而改变脚本所实现的功能。

def script_properties():
	# 创建一个属性集对象
	props = obs.obs_properties_create()


	# 添加一个对应数字显示框的脚本属性对象，用于表示小时
	obs.obs_properties_add_int(props, 'hours', '小时：', 2, 5, 1)
	return props

在 OBS 加载或卸载 Python 脚本时执行任务

如果希望在 Python 脚本被 OBS 加载或卸载时执行某些任务，比如从文件读取或写入数据，那么你可以在脚本中定义函数script_load，script_unload。

script_load(settings)

settings 参数

settings参数为 Python 脚本对应的脚本设置对象。

# 变量 data 表示脚本设置
data = None


def script_load(settings):
	global data
	data = settings


	# 读取脚本设置项 closed_time，他是脚本的停止时间
	closed_time = obs.obs_data_get_string(data, 'closed_time')
	if closed_time:
		obs.script_log(obs.LOG_INFO, f'上次脚本停止的时间为 {closed_time}')


def script_unload():
	# 将当前时间写入脚本设置项 closed_time，作为脚本的停止时间
	from datetime import datetime
	obs.obs_data_set_string(data, 'closed_time', datetime.now().ctime())

[exports.py] 上次脚本停止的时间为 Mon Mar 4 07:12:37 2024

在 OBS 用户修改 Python 脚本属性后执行任务

如果希望在用户修改脚本属性（通过脚本窗口）后执行某些任务，比如，根据修改后的脚本属性调整实现的功能，那么你可以在 Python 脚本中定义函数script_update，该函数的执行时间点在script_load函数与script_unload函数之间。

需要指出的是，任何脚本属性的修改都会导致script_update函数的调用。如果仅监视某一个脚本属性的变化，那么可以使用obspython模块的obs_property_set_modified_callback函数。

script_update(settings)

settings 参数

settings参数为 Python 脚本对应的脚本设置对象。

def script_update(settings):
	# 读取脚本设置项 hours 并显示
	hours = obs.obs_data_get_int(settings, 'hours')
	obs.script_log(obs.LOG_INFO, f'当前小时为 {hours}')

[exports.py] 当前小时为 0

在 OBS 关闭时将数据写入 Python 脚本设置

在 OBS 关闭时，Python 脚本中的script_save函数会被调用，此时可将一些重要的数据写入脚本设置，以便下次启动时读取他们。

script_save(settings)

settings 参数

settings参数为 Python 脚本对应的脚本设置对象。

def script_save(settings):
	# 将当前时间写入脚本设置项 closed_time，作为脚本的停止时间
	from datetime import datetime
	obs.obs_data_set_string(settings, 'closed_time', datetime.now().ctime())

为 Python 脚本属性指定默认值

在 OBS 官方提供的obspython模块中，你无法直接通过参数为脚本属性指定默认值，虽然一些添加脚本属性的函数可以达到近似的效果。要为脚本窗口中的控件设置默认值，应该在 Python 脚本中定义函数script_defaults，并在该函数中为脚本属性对应的脚本设置项指定默认值。

script_defaults(settings)

settings 参数

settings参数为 Python 脚本对应的脚本设置对象。

def script_defaults(settings):
	# 将设置项 hours 的默认值设置为 3
	obs.obs_data_set_default_int(settings, 'hours', 3)

在 OBS 绘制每一帧时执行任务

如果你希望在 OBS 绘制每一帧时执行某些任务，那么可以在 Python 脚本中定义函数script_tick。

script_tick(seconds)

seconds 参数

seconds参数是上一帧到本帧所经历的秒数。

def script_tick(seconds):
	obs.script_log(obs.LOG_INFO, f'{seconds} OBS 就要无法响应了！！！')

获取 Python 脚本所在的目录

对于添加的 Python 脚本，OBS 会为其定义一个名为script_path的函数（不属于obspython模块），该函数可用于获取当前脚本所在的目录。

def script_load(settings):
	# …
	obs.script_log(obs.LOG_INFO, script_path())

# Windows 中的输出结果
[exports.py] …/scripts/

为 OBS 添加或移除脚本计时器

通过obspython模块的timer_add和timer_remove函数，你可以为 OBS 添加或移除脚本计时器（Script Timers）。脚本计时器将在指定时间间隔下，反复调用给出的回调函数或方法，这不同于script_tick函数。

一旦使用了timer_add函数，被添加的脚本计时器就会开始工作。如果希望脚本计时器停止，可以通过timer_remove函数将其移除，或在回调函数和方法中调用obspython模块的remove_current_callback函数。

timer_add(callback, milliseconds)
timer_remove(callback)

callback 参数

callback参数是被脚本计时器回调的函数或方法，在timer_remove函数中，callback对应的脚本计时器将被移除。

milliseconds 参数

milliseconds参数是计时器触发的时间间隔，以毫秒为单位，接受整数类型的值。

# 脚本计时器的回调函数 welcome
def welcome():
	obs.script_log(obs.LOG_INFO, '这是只被调用一次的回调函数')
	# 移除 welcome 对应的脚本计时器
	obs.remove_current_callback()


# 添加脚本计时器，触发时间间隔为 3 秒
obs.timer_add(welcome, 3000)

[exports.py] 这是只被调用一次的回调函数

源码

exports.py·codebeatme/obs-python-scripting·GitHub