如何編寫可在 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