如何在 Python 脚本中使用 OBS 数据设置对象？OBS 数据设置对象介绍

Python 脚本中的 OBS 数据设置对象

对于 OBS Python 脚本来说，OBS 数据设置对象（Data Settings Objects）是非常重要的，对来源（Sources）进行调整或修改脚本设置，都涉及到该对象。OBS 数据设置对象采用类似于键值对的方式来读写数据，obspython模块提供了相关函数，使其可以转换为 JSON 字符串，或进行相反的操作。

在 Python 脚本中创建 OBS 数据设置对象

在某些情况下，创建 OBS 数据设置对象是没有必要的，因为他们已经存在，比如当前的 Python 脚本设置就是一个 OBS 数据设置对象。主动创建数据设置对象的原因，主要是需要调整来源设置，obspython模块提供了如下函数来实现该目标。

obs_data_create函数，用于创建一个空的 OBS 数据设置对象，obs_data_create_from_json函数，用于从 JSON 字符串创建 OBS 数据设置对象。

obs_data_create()
obs_data_create_from_json(json_string)

json_string 参数

json_string参数为用于创建 OBS 数据设置对象的 JSON 字符串。

# 导入模块 obspython
import obspython as obs


# 根据 JSON 字符串创建 OBS 数据设置对象
data = obs.obs_data_create_from_json('{"name":"Jack","age":12}')


# 释放对数据设置对象的引用
obs.obs_data_release(data)

在 Python 脚本中获取和设置 OBS 数据设置对象中的项

OBS 数据设置对象可以包含多个项（设置项），每一个项都由名称和值组成，值可以是数字或字符串等简单类型，也可以是较为复杂的类型，比如，另一个数据设置对象。

obspython模块的obs_data_get_string，obs_data_get_int，obs_data_get_double，obs_data_get_bool，obs_data_get_obj，obs_data_get_array，obs_data_set_string，obs_data_set_int，obs_data_set_double，obs_data_set_bool，obs_data_set_obj，obs_data_set_array函数，可用于获取或设置数据设置对象中指定项的值。如果要获取的项不存在，则将返回对应类型的默认值，比如，obs_data_get_string函数将返回空字符串''。如果要设置的项不存在，则将新建该项。

obs_data_get_string(data, name)
obs_data_get_int(data, name)
obs_data_get_double(data, name)
obs_data_get_bool(data, name)
obs_data_get_obj(data, name)
obs_data_get_array(data, name)
obs_data_set_string(data, name, val)
obs_data_set_int(data, name, val)
obs_data_set_double(data, name, val)
obs_data_set_bool(data, name, val)
obs_data_set_obj(data, name, obj)
obs_data_set_array(data, name, array)

data 参数

data参数为 OBS 数据设置对象。

name 参数

name参数为需要获取或设置的项的名称。

val 参数

val参数为需要写入（设置）项的值。

obj 参数

obj参数为需要写入（设置）项的 OBS 数据设置对象。

array 参数

array参数为需要写入（设置）项的 OBS 数据数组对象。

# …
# 获取不存在的项
obs.script_log(obs.LOG_INFO, f'获取不存在的项 nickname {obs.obs_data_get_string(data, "nickname") == ""}')
# 设置不存在的项
obs.obs_data_set_int(data, 'level', 100)
obs.script_log(obs.LOG_INFO, f'设置了不存在的项，level 为 {obs.obs_data_get_int(data, "level")}')
# …

[data_settings.py] 获取不存在的项 nickname True
[data_settings.py] level 为 100

在 Python 脚本中获取和设置 OBS 数据设置对象中项的默认值

你可以为 OBS 数据设置对象中重要的项指定默认值，这对于 Python 脚本设置是非常有效的，obspython模块提供了以下函数来完成该目标。

obs_data_get_default_string，obs_data_get_default_int，obs_data_get_default_double，obs_data_get_default_bool，obs_data_get_default_obj，obs_data_get_default_array，obs_data_set_default_string，obs_data_set_default_int，obs_data_set_default_double，obs_data_set_default_bool，obs_data_set_default_obj，obs_data_set_default_array函数，可用于获取或设置数据设置对象中指定项的默认值。

obs_data_get_default_string(data, name)
obs_data_get_default_int(data, name)
obs_data_get_default_double(data, name)
obs_data_get_default_bool(data, name)
obs_data_get_default_obj(data, name)
obs_data_get_default_array(data, name)
obs_data_set_default_string(data, name, val)
obs_data_set_default_int(data, name, val)
obs_data_set_default_double(data, name, val)
obs_data_set_default_bool(data, name, val)
obs_data_set_default_obj(data, name, obj)
obs_data_set_default_array(data, name, array)

data 参数

data参数为项所在的 OBS 数据设置对象。

name 参数

name参数为需要获取或设置默认值的项的名称。

val 参数

val参数为需要为项写入（设置）的默认值。

obj 参数

obj参数为需要为项写入（设置）的默认 OBS 数据设置对象。

array 参数

array参数为需要为项写入（设置）的默认 OBS 数据数组对象。

obs_data_get_defaults函数可以获取 OBS 数据设置对象中所有的默认值，这些默认值被包含在一个新的数据设置对象中返回。

obs_data_get_defaults(data)

data 参数

data参数为需要获取所有默认值的 OBS 数据设置对象。

# …
# 为项 balance 设置默认值，然后读取
obs.obs_data_set_default_double(data, 'balance', 99.9)
obs.script_log(obs.LOG_INFO, f'balance 为 {obs.obs_data_get_double(data, "balance")}')
# …

[data_settings.py] balance 为 99.9

在 Python 脚本中合并 OBS 数据设置对象

obspython模块的obs_data_apply函数，可用于合并两个 OBS 数据设置对象，被合并数据设置对象中的项将被写入目标数据设置对象，如果项在目标数据设置对象中已经存在，那么他将被覆盖。

obs_data_apply(target, apply_data)

target 参数

target参数为目标 OBS 数据设置对象。

apply_data 参数

apply_data参数为被合并的 OBS 数据设置对象。

# …
# 创建新的 OBS 数据设置对象并合并至 data
other_data = obs.obs_data_create_from_json('{"name":"Tom","enabled":true}')
obs.obs_data_apply(data, other_data)
obs.script_log(obs.LOG_INFO, f'name 为 {obs.obs_data_get_string(data, "name")}')
obs.script_log(obs.LOG_INFO, f'enabled 为 {obs.obs_data_get_bool(data, "enabled")}')
# …
obs.obs_data_release(other_data)

[data_settings.py] name 为 Tom
[data_settings.py] enabled 为 True

在 Python 脚本中清除或擦除 OBS 数据设置对象中的项

obspython模块的obs_data_clear函数，可用于清除数据设置对象中的所有项，obs_data_erase函数，可用于从数据设置对象中擦除指定名称的项。对于被清除或擦除的项，其对应的默认值也将被清除或擦除。

obs_data_clear(data)
obs_data_erase(data, name)

data 参数

data参数为需要清除所有项或擦除指定项的 OBS 数据设置对象。

name 参数

name参数为需要擦除的项的名称。

# …
# 在删除项 enabled 之前，为其指定默认值
obs.obs_data_set_default_bool(other_data, 'enabled', True)
obs.obs_data_erase(other_data, 'enabled')
# 项 enabled 被删除之后，默认值也不再有效
obs.script_log(obs.LOG_INFO, f'other_data 中的 enabled 为 {obs.obs_data_get_bool(other_data, "enabled")}')
# …

[data_settings.py] other_data 中的 enabled 为 False

在 Python 脚本中获取 OBS 数据设置对象对应的 JSON 字符串

obspython模块的obs_data_get_json函数，可用于获取 OBS 数据设置对象对应的 JSON 字符串。

obspython模块的obs_data_get_last_json函数，可用于获取上一次调用obs_data_get_json时的返回值。如果数据设置对象尚未通过obs_data_get_json生成任何 JSON 字符串，那么obs_data_get_last_json将返回空值None。

obs_data_get_json(data)
obs_data_get_last_json(data)

data 参数

data参数是一个 OBS 数据设置对象。

# …
# 返回数据设置对象的 JSON 字符串
obs.script_log(obs.LOG_INFO, obs.obs_data_get_json(data))
# …

[data_settings.py] {"name":"Tom","age":12,"level":100,"enabled":true}

在 Python 脚本中使用 OBS 数据设置对象读取和写入 JSON 文件

obspython模块的obs_data_create_from_json_file和obs_data_create_from_json_file_safe函数，可用于读取 JSON 格式的文件，并根据其内容返回一个 OBS 数据设置对象。

obspython模块的obs_data_save_json和obs_data_save_json_safe函数，可将 OBS 数据设置对象保存为一个 JSON 格式的文件，当函数返回True时，表示保存成功，返回False时，表示保存失败。

obs_data_create_from_json_file(json_file)
obs_data_create_from_json_file_safe(json_file, backup_ext)

json_file 参数

json_file参数为 OBS 数据设置对象对应的 JSON 文件的路径，如果采用相对路径，那么默认从 OBS 可执行文件所在的文件夹开始计算。

backup_ext 参数

backup_ext参数为备份文件的扩展名，当无法正确读取 JSON 文件时，将尝试读取备份文件。

obs_data_save_json(data, file)
obs_data_save_json_safe(data, file, temp_ext, backup_ext)

data 参数

data参数为需要存储为 JSON 文件的 OBS 数据设置对象。

file 参数

file参数为存储的 JSON 文件的路径，如果采用相对路径，那么默认从 OBS 可执行文件所在的文件夹开始计算。

temp_ext 参数

temp_ext参数为临时文件的扩展名，他应该是有效的，不能为空值None。

backup_ext 参数

backup_ext参数为备份文件的扩展名，如果指定的 JSON 文件已经存在，那么将以该扩展名进行备份。如果该参数为空字符串或None，那么备份不会发生。

# …
# 保存数据设置对象至文件 player.json，如果文件已经存在，则会将其备份为 player.json.backup
obs.obs_data_save_json_safe(data, 'player.json', '.temp', '.backup')
# …

在 Python 脚本中添加和释放对 OBS 数据设置对象的引用

很多情况下，你不需要为 OBS 数据设置对象添加引用，除非希望数据设置对象能够在多个位置被使用，但又无法确定在哪个位置释放他。如果 OBS 数据设置对象的引用未能正确释放，那么 OBS 可能会发生错误，尤其是在循环和计时器中。

obspython模块的obs_data_addref函数，可用于为 OBS 数据设置对象添加引用。每当你额外调用一次obs_data_addref函数，就需要对等增加一次obs_data_release函数的调用。

obspython模块的obs_data_release函数，可用于为 OBS 数据设置对象释放引用，该函数适用于通过obs_data_create，obs_data_create_from_json，obs_data_create_from_json_file，obs_data_create_from_json_file_safe，obs_data_get_obj，obs_data_get_default_obj，obs_data_get_defaults，obs_data_get_autoselect_obj，obs_data_array_item，obs_source_get_settings，obs_source_get_private_settings，obs_sceneitem_get_private_settings函数创建或获取的数据设置对象。

obs_data_addref(data)
obs_data_release(data)

data 参数

data参数为需要添加或释放引用的 OBS 数据设置对象。

在 Python 脚本中使用 OBS 数据数组对象

OBS 数据数组对象可用于管理一组 OBS 数据设置对象，其自身可以作为数据设置对象中项的值，obspython模块提供了以下与数据数组对象相关的函数。其中，array参数为数据数组对象，idx参数为数据设置对象所在的位置，0表示第一个位置，obj参数为添加的数据设置对象。

obs_data_array_create函数，可用于创建一个 OBS 数据数组对象。

obs_data_array_create()

obs_data_array_push_back函数，可用于将数据设置对象添加至 OBS 数据数组对象的末尾位置。

obs_data_array_insert函数，可用于将数据设置对象插入至 OBS 数据数组对象的指定位置。

obs_data_array_push_back(array, obj)
obs_data_array_insert(array, idx, obj)

obs_data_array_item函数，可用于获取 OBS 数据数组对象中指定位置的数据设置对象。

obs_data_array_item(array, idx)

obs_data_array_count函数，可用于获取 OBS 数据数组对象中包含的数据设置对象的个数。

obs_data_array_count(array)

obs_data_array_erase函数，可用于擦除 OBS 数据数组对象中指定位置的数据设置对象。

obs_data_array_erase(array, idx)

obs_data_array_addref函数，可用于为 OBS 数据数组对象添加引用，除非你的数据数组对象需要在多个位置使用，并且无法确定在何处释放引用，否则没有必要执行该函数。

obs_data_array_release函数，可用于为 OBS 数据数组对象释放引用，该函数适用于通过obs_data_array_create，obs_data_get_array，obs_data_get_default_array，obs_data_get_autoselect_array，obs_source_backup_filters创建或获取的数据数组对象。

obs_data_array_addref(array)
obs_data_array_release(array)

# …
# 函数 add_hero 将一个英雄添加至 OBS 数据数组对象
def add_hero(array, name, hp):
	# 创建表示英雄的数据设置对象 hero
	hero = obs.obs_data_create()
	obs.obs_data_set_string(hero, 'name', name)
	obs.obs_data_set_int(hero, 'hp', hp)


	# 将数据设置对象 hero 添加到数据数组对象
	obs.obs_data_array_push_back(array, hero)
	obs.obs_data_release(hero)


# 创建一个 OBS 数据数组对象 heroes
heroes = obs.obs_data_array_create()


# 调用 add_hero 添加一些英雄，他们具有随机的生命值
import random
for i in range(10):
	add_hero(heroes, f'超人 {i}', random.randint(0, 100))


# 去掉所有生命值小于 50 的英雄
i = 0
while i < obs.obs_data_array_count(heroes):
	hero = obs.obs_data_array_item(heroes, i)


	if obs.obs_data_get_int(hero, 'hp') < 50:
		obs.obs_data_array_erase(heroes, i)
		obs.script_log(obs.LOG_INFO, f'英雄 {obs.obs_data_get_string(hero, "name")} 被删除')
	else:
		i += 1


	obs.obs_data_release(hero)


# 显示剩余英雄的个数
count = obs.obs_data_array_count(heroes)
obs.script_log(obs.LOG_INFO, f'剩余英雄 {count} 个')


# 将数据数组对象 heroes 添加至数据设置对象
obs.obs_data_set_array(data, 'heroes', heroes)
obs.obs_data_array_release(heroes)
# …

[data_settings.py] 英雄 超人 4 被删除
[data_settings.py] 英雄 超人 5 被删除
[data_settings.py] 英雄 超人 7 被删除
[data_settings.py] 英雄 超人 8 被删除
[data_settings.py] 剩余英雄 6 个

源码

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