如何在 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