如何使用 OBS 資料設定物件？資料設定物件介紹

閱讀 21:09·字數 6347·更新 2025-1-10

OBS 資料設定物件

對於 OBS Python 腳本來說，資料設定物件（Data Settings Objects）是非常重要的，對來源（Sources）進行調整或修改腳本設定，都涉及到該物件。資料設定物件采用類似於鍵值組的方式來讀取及寫入資料，obspython模組提供了相關函式，使其可以轉換為 JSON 字串，或進行相反的操作。

建立 OBS 資料設定物件

在某些情況下，建立資料設定物件是沒有必要的，因為他們已經存在，比如目前的腳本設定就是一個資料設定物件。主動建立資料設定物件的原因，主要是需要調整來源設定，obspython模組提供了如下函式來實作該目標。

obs_data_create函式，用於建立一個空的資料設定物件，obs_data_create_from_json函式，用於從 JSON 字串建立資料設定物件。

obs_data_create() obs_data_create_from_json(json_string)

json_string 參數: json_string參數為用於建立資料設定物件的 JSON 字串。

使用 obs_data_release 函式釋放建立的資料設定物件

這裏需要指出，對於使用obs_data_create和obs_data_create_from_json建立的資料設定物件，最好通過obs_data_release釋放參考，以免發生錯誤。

JSON

要取得更多關於 JSON 的資訊，你可以檢視程式設計教學的JSON，JSON 字串，JSON 資料型別介紹一節。

在腳本檔案data_settings.py中，我們根據 JSON 字串建立了一個資料設定物件。

data_settings.py

# 匯入模組 obspython
import obspython as obs


# 根據 JSON 字串建立 OBS 資料設定物件
data = obs.obs_data_create_from_json('{"name":"Jack","age":12}')


# 釋放對資料設定物件的參考
obs.obs_data_release(data)

取得和設定 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參數為資料設定物件。
name 參數: name參數為需要取得或設定的項的名稱。
val 參數: val參數為需要寫入（設定）項的值。
obj 參數: obj參數為需要寫入（設定）項的資料設定物件。
array 參數: array參數為需要寫入（設定）項的資料陣列物件。

使用 obs_data_release，obs_data_array_release 函式釋放取得的資料設定物件和資料陣列物件

這裏需要指出，對於使用obs_data_get_obj取得的資料設定物件，以及使用obs_data_get_array取得的資料陣列物件，最好通過函式obs_data_release或obs_data_array_release釋放參考，當你不再需要他們時。

調整之前的程式碼，通過obs_data_get_string函式取得一個並不存在的項nickname，其傳回的結果為空字串，通過obs_data_set_int函式設定一個並不存在的項level，這將新增該項。

data_settings.py

# …
# 取得不存在的項
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

取得和設定 OBS 資料設定物件中項的預設值

你可以為資料設定物件中重要的項指定預設值，這對於腳本設定是非常有效的，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參數為項所在的資料設定物件。
name 參數: name參數為需要取得或設定預設值的項的名稱。
val 參數: val參數為需要為項寫入（設定）的預設值。
obj 參數: obj參數為需要為項寫入（設定）的預設資料設定物件。
array 參數: array參數為需要為項寫入（設定）的預設資料陣列物件。

obs_data_get_defaults函式可以取得資料設定物件中所有的預設值，這些預設值被包含在一個新的資料設定物件中傳回。

obs_data_get_defaults(data)

data 參數: data參數為需要取得所有預設值的資料設定物件。

使用 obs_data_release，obs_data_array_release 函式釋放作為預設值的資料設定物件和資料陣列物件

這裏需要指出，對於使用obs_data_get_default_obj，obs_data_get_default_array或obs_data_get_defaults取得的資料設定物件或資料陣列物件，最好通過函式obs_data_release或obs_data_array_release釋放參考，當你不再需要他們時。

無法通過 obs_data_get_defaults 函式傳回的資料設定物件更新預設值

雖然可以使用obs_data_get_defaults函式取得所有的預設值，但你不能通過其傳回的資料設定物件修改原有資料設定物件的預設值，那將沒有任何效果。

下面，我們為項balance設定預設值，由於該項在資料設定物件中尚不存在具體值，因此讀取他會傳回預設值99.9。

data_settings.py

# …
# 為項 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

合併 OBS 資料設定物件

obspython模組的obs_data_apply函式，可用於合併兩個資料設定物件，被合併資料設定物件中的項將被寫入目標資料設定物件，如果項在目標資料設定物件中已經存在，那麽他將被覆蓋。

obs_data_apply(target, apply_data)

target 參數: target參數為目標資料設定物件。
apply_data 參數: apply_data參數為被合併的資料設定物件。

下面，我們建立了一個新的資料設定物件，並將其合併至原有的資料設定物件，原有的項name被覆蓋，缺少的項enabled被新增。

data_settings.py

# …
# 建立新的 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

清除或抹除 OBS 資料設定物件中的項

obspython模組的obs_data_clear函式，可用於清除資料設定物件中的所有項，obs_data_erase函式，可用於從資料設定物件中抹除指定名稱的項。對於被清除或抹除的項，其對應的預設值也將被清除或抹除。

obs_data_clear(data) obs_data_erase(data, name)

data 參數: data參數為需要清除所有項或抹除指定項的資料設定物件。
name 參數: name參數為需要抹除的項的名稱。

在下面的程式碼中，我們刪除了other_data中的項enabled，為該項指定的預設值不再有效。

data_settings.py

# …
# 在刪除項 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

取得 OBS 資料設定物件對應的 JSON 字串

obspython模組的obs_data_get_json函式，可用於取得資料設定物件對應的 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_data_get_last_json 函式可能無法體現資料設定物件的改變

如果你在呼叫obs_data_get_json後，修改了資料設定物件中的內容，那麽這些改變不會體現在obs_data_get_last_json的傳回值中，除非再次呼叫obs_data_get_json。

data_settings.py

# …
# 傳回資料設定物件的 JSON 字串
obs.script_log(obs.LOG_INFO, obs.obs_data_get_json(data))
# …

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

使用 OBS 資料設定物件讀取和寫入 JSON 檔案

obspython模組的obs_data_create_from_json_file和obs_data_create_from_json_file_safe函式，可用於讀取 JSON 格式的檔案，並根據其內容傳回一個資料設定物件。

obspython模組的obs_data_save_json和obs_data_save_json_safe函式，可將資料設定物件儲存為一個 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參數為資料設定物件對應的 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 檔案的資料設定物件。
file 參數: file參數為儲存的 JSON 檔案的路徑，如果采用相對路徑，那麽預設從 OBS 可執行檔案所在的資料夾開始計算。
temp_ext 參數: temp_ext參數為臨時檔案的副檔名，他應該是有效的，不能為空值None。
backup_ext 參數: backup_ext參數為備份檔案的副檔名，如果指定的 JSON 檔案已經存在，那麽將以該副檔名進行備份。如果該參數為空字串或None，那麽備份不會發生。

使用 obs_data_release 函式釋放根據 JSON 檔案建立的資料設定物件

對於使用obs_data_create_from_json_file和obs_data_create_from_json_file_safe函式，從 JSON 檔案建立的資料設定物件，最好通過obs_data_release函式釋放參考，以免 OBS 發生錯誤。

在下面的程式碼中，我們把資料設定物件儲存為檔案player.json，如果該檔案已經存在，那麽會首先將其備份為player.json.backup。

data_settings.py

# …
# 儲存資料設定物件至檔案 player.json，如果檔案已經存在，則會將其備份為 player.json.backup
obs.obs_data_save_json_safe(data, 'player.json', '.temp', '.backup')
# …

新增和釋放對 OBS 資料設定物件的參考

很多情況下，你不需要為資料設定物件新增參考，除非希望資料設定物件能夠在多個位置被使用，但又無法確定在哪個位置釋放他。如果資料設定物件的參考未能正確釋放，那麽 OBS 可能會發生錯誤，尤其是在迴圈和計時器中。

obspython模組的obs_data_addref函式，可用於為資料設定物件新增參考。每當你額外呼叫一次obs_data_addref函式，就需要對等增加一次obs_data_release函式的呼叫。

obspython模組的obs_data_release函式，可用於為資料設定物件釋放參考，該函式適用於通過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 資料陣列物件

資料陣列物件可用於管理一組資料設定物件，其自身可以作為資料設定物件中項的值，obspython模組提供了以下與資料陣列物件相關的函式。其中，array參數為資料陣列物件，idx參數為資料設定物件所在的位置，0表示第一個位置，obj參數為新增的資料設定物件。

obs_data_array_create函式，可用於建立一個資料陣列物件。

obs_data_array_create()

obs_data_array_push_back函式，可用於將資料設定物件新增至資料陣列物件的末尾位置。

obs_data_array_insert函式，可用於將資料設定物件插入至資料陣列物件的指定位置。

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

obs_data_array_item函式，可用於取得資料陣列物件中指定位置的資料設定物件。

obs_data_array_item(array, idx)

obs_data_array_count函式，可用於取得資料陣列物件中包含的資料設定物件的個數。

obs_data_array_count(array)

obs_data_array_erase函式，可用於抹除資料陣列物件中指定位置的資料設定物件。

obs_data_array_erase(array, idx)

obs_data_array_addref函式，可用於為資料陣列物件新增參考，除非你的資料陣列物件需要在多個位置使用，並且無法確定在何處釋放參考，否則沒有必要執行該函式。

obs_data_array_release函式，可用於為資料陣列物件釋放參考，該函式適用於通過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)

使用 obs_data_release，obs_data_array_release 函式釋放建立或取得的資料設定物件和資料陣列物件

這裏需要指出，對於使用obs_data_array_create建立的資料陣列物件，以及使用obs_data_array_item取得的資料設定物件，最好通過函式obs_data_array_release和obs_data_release釋放參考，當你不再需要他們時。

在下面的程式碼中，add_hero可通過obs_data_array_push_back函式將表示英雄的資料設定物件新增至資料陣列物件。我們篩選所有的英雄，通過obs_data_array_erase函式抹除了其中生命值小於50的，並在稍後使用obs_data_array_count函式取得了剩余的英雄個數。

data_settings.py

# …
# 函式 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