如何操作 OBS 場景項，群組

閱讀 24:15·字數 7277·更新 2025-1-10

先決條件

閱讀本節的先決條件是對 OBS 場景有所掌握，你可以檢視如何操作 OBS 場景？場景物件介紹一節來了解相關資訊。

OBS 場景項，群組

OBS 場景包含了一組場景項，每一個場景項都參考了一個 OBS 來源，當多個場景項參考同一個來源時，他們將在某些行為上表現一致，比如顯示的文字。OBS 群組與場景類似，也可以包含場景項，但群組中的場景項可被使用者編輯。

尋找和取得場景中的 OBS 場景項

obspython模組的obs_scene_find_source和obs_scene_find_source_recursive函式，均可用於尋找場景中指定名稱的場景項，兩者的區別在於，obs_scene_find_source_recursive將尋找群組中的項。如果指定名稱的場景項不存在，那麽函式會傳回空值None。

obs_scene_find_source(scene, name) obs_scene_find_source_recursive(scene, name)

scene 參數: scene參數為需要尋找場景項的場景物件。
name 參數: name參數為被尋找場景項的名稱，也是該場景項對應 OBS 來源的名稱。

obspython模組的obs_scene_find_sceneitem_by_id函式，可用於尋找場景中指定 ID 的場景項，場景項的 ID 是一個整數，不同場景項的 ID 不相同。如果指定 ID 的場景項不存在，那麽函式會傳回空值None。

obs_scene_find_sceneitem_by_id(scene, id)

scene 參數: scene參數為需要尋找場景項的場景物件。
id 參數: id參數為被尋找場景項的 ID。

obspython模組的obs_scene_sceneitem_from_source函式，可用於取得場景中指定來源對應的場景項。

obs_scene_sceneitem_from_source(scene, source)

scene 參數: scene參數為需要取得場景項的場景物件。
source 參數: source參數為場景項所參考的來源。

使用 obs_sceneitem_release 函式釋放取得的場景項物件

對於使用obs_scene_sceneitem_from_source函式取得的場景項物件，需要通過obs_sceneitem_release釋放參考，否則 OBS 可能會出現錯誤。

在下面的程式碼中，我們對場景項Welcome進行了兩次查詢，一次包括群組，一次不包括，假設Welcome是群組Group中的場景項。

items_and_groups.py

# 匯入模組 obspython 和 vec2
import obspython as obs
from obspython import vec2


def test(props, prop):
	# 取得場景 Scene 對應的場景物件
	source_scene = obs.obs_get_source_by_name('Scene')
	scene = obs.obs_scene_from_source(source_scene)


	# 兩次尋找場景項 Welcome，第二次包括群組
	welcome = obs.obs_scene_find_source(scene, 'Welcome')
	obs.script_log(obs.LOG_INFO, f'找到了 Welcome？{welcome != None}')
	welcome = obs.obs_scene_find_source_recursive(scene, 'Welcome')
	obs.script_log(obs.LOG_INFO, f'找到了 Welcome（包括群組中的）？{welcome != None}')


	# 釋放來源物件
	obs.obs_source_release(source_scene)


# 為腳本新增一個用於測試的按鈕，回呼函式為 test
def script_properties():
	props = obs.obs_properties_create()
	obs.obs_properties_add_button(props, 'test', '測試', test)
	return props

[items_and_groups.py] 找到了 Welcome？False
[items_and_groups.py] 找到了 Welcome（包括群組中的）？True

取得 OBS 場景項所在的場景

obspython模組的obs_sceneitem_get_scene函式，可用於取得場景項所在的場景。

obs_sceneitem_get_scene(item)

item 參數: item參數為需要取得所在場景的場景項物件。

取得 OBS 場景項參考的來源

obspython模組的obs_sceneitem_get_source函式，可用於取得場景項參考的來源物件。

obs_sceneitem_get_source(item)

item 參數: item參數為需要取得來源的場景項物件。

下面的程式碼，將顯示場景項Hi的來源類型識別碼。

items_and_groups.py

def test(props, prop):
	# …
	# 顯示場景項 Welcome 的來源類型識別碼
	source_welcome = obs.obs_sceneitem_get_source(welcome)
	obs.script_log(obs.LOG_INFO, f'{obs.obs_source_get_unversioned_id(source_welcome)}')
	# …

[items_and_groups.py] ffmpeg_source

移除場景中的 OBS 場景項

obspython模組的obs_sceneitem_remove函式，可用於移除場景中指定的場景項，無論該場景項是否處於群組內。

obs_sceneitem_remove(item)

item 參數: item參數為需要移除的場景項物件。

在下面的程式碼中，我們移除了Group群組的Welcome場景項。

items_and_groups.py

def test(props, prop):
	# …
	# 將場景項 Welcome 移除
	obs.obs_sceneitem_remove(welcome)
	# …

排序場景中的 OBS 場景項

obspython模組的obs_sceneitem_set_order函式，可將場景項的位置向上，向下移動，以及將場景項移動至開頭或末尾。需要註意，該函式對群組中的場景項無效。

obspython模組的obs_sceneitem_get_order_position和obs_sceneitem_set_order_position函式，可將場景項移動到指定索引位置。

obs_sceneitem_set_order(item, movement) obs_sceneitem_get_order_position(item) obs_sceneitem_set_order_position(item, position)

item 參數: item參數為需要移動位置的場景項物件。
movement 參數: movement參數為移動方式，可使用如下obspython模組變數進行設定，OBS_ORDER_MOVE_UP表示向上移動，OBS_ORDER_MOVE_DOWN表示向下移動，OBS_ORDER_MOVE_TOP表示移動至開頭，OBS_ORDER_MOVE_BOTTOM表示移動至末尾。
position 參數: position參數為目標位置的索引，0表示末尾（倒數第一），倒數第二為1。

items_and_groups.py

def test(props, prop):
	# …
	# 將場景項 Hi 移動至末尾
	hi = obs.obs_scene_find_source(scene, 'Hi')
	obs.obs_sceneitem_set_order_position(hi, 0)
	# …

取得 OBS 場景項的私用資料設定物件

obspython模組的obs_sceneitem_get_private_settings函式，可用於取得場景項對應的私用資料設定物件，這可以讓開發人員針對場景項新增自訂的設定項。

obs_sceneitem_get_private_settings(item)

item 參數: item參數為需要取得私用資料設定物件的場景項物件。

使用 obs_data_release 函式釋放場景項的私用資料設定物件

對於使用obs_sceneitem_get_private_settings函式取得的場景項對應的私用資料設定物件，需要通過obs_data_release釋放參考，否則 OBS 可能會出現錯誤。

取得和設定 OBS 場景項的變型

obspython模組的obs_sceneitem_get_pos，obs_sceneitem_set_pos函式，可用於取得和設定場景項在場景或群組中的位置。

obs_sceneitem_get_pos(item, pos) obs_sceneitem_set_pos(item, pos)

item 參數: item參數為需要取得或設定位置的場景項物件。
pos 參數: pos參數為包含了位置資訊的 OBSvec2物件。

obspython模組的obs_sceneitem_get_rot，obs_sceneitem_set_rot函式，可用於取得和設定場景項在場景或群組中的旋轉角度。

obs_sceneitem_get_rot(item) obs_sceneitem_set_rot(item, rot_deg)

item 參數: item參數為需要取得或設定旋轉角度的場景項物件。
rot_deg 參數: rot_deg參數為需要設定的旋轉角度。

obspython模組的obs_sceneitem_get_scale，obs_sceneitem_set_scale函式，可用於取得和設定場景項在場景或群組中的縮放。

obs_sceneitem_get_scale(item, scale) obs_sceneitem_set_scale(item, scale)

item 參數: item參數為需要取得或設定縮放的場景項物件。
scale 參數: scale參數為包含了縮放資訊的 OBSvec2物件。

obspython模組的obs_sceneitem_get_bounds_type，obs_sceneitem_set_bounds_type函式，可用於取得和設定場景項的邊線類型。一旦設定了有效的邊線，場景項中的內容可能會被縮放。

obs_sceneitem_get_bounds_type(item) obs_sceneitem_set_bounds_type(item, type)

item 參數: item參數為需要取得或設定邊線類型的場景項物件。
type 參數: type參數為邊線類型，可使用如下obspython模組變數進行設定，OBS_BOUNDS_NONE表示無邊線，OBS_BOUNDS_STRETCH表示依外框轉換，內容將填滿並全部顯示在邊線中，OBS_BOUNDS_SCALE_INNER表示等比例縮放至框內，內容將全部顯示在邊線中，並以保持原比例的方式盡量填入整個邊線，OBS_BOUNDS_SCALE_OUTER表示等比例縮放至框外，內容將以保持原比例的方式填入整個邊線，並盡量確保內容全部顯示在邊線中，OBS_BOUNDS_SCALE_TO_WIDTH表示等比例縮放至符合寬度，內容將以保持原比例的方式縮放，使其寬度與邊線寬度一致，OBS_BOUNDS_SCALE_TO_HEIGHT表示等比例縮放至符合高度，內容將以保持原比例的方式縮放，使其高度與邊線高度一致，OBS_BOUNDS_MAX_ONLY與OBS_BOUNDS_SCALE_INNER類似，表示等比例縮放至框內，但內容不會超過其原始大小。

在下面的程式碼中，我們設定了場景項Hi的位置，旋轉角度和縮放。

items_and_groups.py

def test(props, prop):
	# …
	# 設定場景項 Hi 的位置
	pos = vec2()
	pos.x = 100
	pos.y = 100
	obs.obs_sceneitem_set_pos(hi, pos)
	# 設定場景項 Hi 的旋轉角度
	obs.obs_sceneitem_set_rot(hi, 30)
	# 設定場景項 Hi 的縮放
	scale = vec2()
	scale.x = 1.5
	scale.y = 1.5
	obs.obs_sceneitem_set_scale(hi, scale)
	# …

儲存和載入 OBS 場景項的變型

obspython模組的obs_scene_save_transform_states函式，可用於將場景中所有場景項的變型，儲存至一個資料設定物件。

obs_scene_save_transform_states(scene, all_items)

scene 參數: scene參數為需要儲存變型的場景項所在的場景物件。
all_items 參數: all_items參數為True時，儲存場景中所有場景項的變型，為False時，僅儲存選取場景項的變型。

obspython模組的obs_scene_load_transform_states函式，可用於從一個資料設定物件載入場景項變型。

obs_scene_load_transform_states(states)

states 參數: states參數為包含了場景項變型資訊的資料設定物件。

使用 obs_data_release 函式釋放包含場景項變型資訊的資料設定物件

對於使用obs_scene_save_transform_states函式建立的包含場景項變型資訊的資料設定物件，需要通過obs_data_release釋放參考，否則 OBS 可能會出現錯誤。

在下面的程式碼中，我們通過儲存和載入所有場景項的變型資訊，使得對場景項Hi角度的修改無效。

items_and_groups.py

def test(props, prop):
	# …
	# 儲存並載入場景項的變型資訊，使中途的修改無效
	states = obs.obs_scene_save_transform_states(scene, True)
	# 設定場景項 Hi 的旋轉角度
	obs.obs_sceneitem_set_rot(hi, 90)
	obs.obs_scene_load_transform_states(obs.obs_data_get_json(states))
	# 釋放資料設定物件
	obs.obs_data_release(states)
	# …

取得和設定 OBS 場景項的選取狀態

obspython模組的obs_sceneitem_selected，obs_sceneitem_select函式，可用於取得和設定場景項的選取狀態。需要說明的是，設定某個場景項的選取狀態，並不會取消其他場景項的選取。

obs_sceneitem_selected(item) obs_sceneitem_select(item, select)

item 參數: item參數為需要取得或設定選取狀態的場景項物件。
select 參數: select參數為True時，表示選取場景項。

取得和設定 OBS 場景項是否可見

obspython模組的obs_sceneitem_visible，obs_sceneitem_set_visible函式，可用於取得和設定場景項是否可見。

obs_sceneitem_visible(item) obs_sceneitem_set_visible(item, visible)

item 參數: item參數為需要取得或設定是否可見的場景項物件。
visible 參數: visible參數為True時，表示場景項可見。

取得和設定 OBS 場景項的鎖定狀態

obspython模組的obs_sceneitem_locked，obs_sceneitem_set_locked函式，可用於取得和設定場景項的鎖定狀態。

obs_sceneitem_locked(item) obs_sceneitem_set_locked(item, locked)

item 參數: item參數為需要取得或設定鎖定狀態的場景項物件。
locked 參數: locked參數為True時，表示鎖定場景項。

取得和設定 OBS 場景項的轉場特效

obspython模組的obs_sceneitem_get_transition，obs_sceneitem_set_transition函式，可用於取得和設定場景項的轉場特效。

obs_sceneitem_get_transition(item, show) obs_sceneitem_set_transition(item, show, transition)

item 參數: item參數為需要取得或設定轉場特效的場景項物件。
show 參數: show參數為True時，將取得或設定顯示轉場特效，為False時，將取得或設定隱藏轉場特效。
transition 參數: transition參數為 OBS 轉場特效物件。

obspython模組的obs_sceneitem_get_transition_duration，obs_sceneitem_set_transition_duration函式，可用於取得和設定場景項的轉場特效持續時間。

obs_sceneitem_get_transition_duration(item, show) obs_sceneitem_set_transition_duration(item, show, duration_ms)

item 參數: item參數為需要取得或設定轉場特效持續時間的場景項物件。
show 參數: show參數為True時，將取得或設定顯示轉場特效的持續時間，為False時，將取得或設定隱藏轉場特效的持續時間。
duration_ms 參數: duration_ms參數為轉場特效的持續時間，以毫秒為單位。

觸發 OBS 場景項轉場特效

obspython模組的obs_sceneitem_do_transition函式，可用於觸發場景項的轉場特效。

obs_sceneitem_do_transition(item, visible)

item 參數: item參數為需要觸發轉場特效的場景項物件。
visible 參數: visible參數為True時，觸發顯示轉場特效，為False時，觸發隱藏轉場特效。

在為場景項Hi設定隱藏轉場特效之後，我們觸發了該特效，這需要首先讓Hi處於不可見（隱藏）狀態。

items_and_groups.py

def test(props, prop):
	# …
	# 為場景項 Hi 增加滑出的隱藏轉場效果
	transition = obs.obs_source_create('swipe_transition', 'hi_hide_transition', None, None)
	obs.obs_sceneitem_set_transition(hi, False, transition)
	obs.obs_sceneitem_do_transition(hi, False)
	# 釋放來源物件
	obs.obs_source_release(transition)
	# …

取得和設定 OBS 場景項的縮放濾鏡

obspython模組的obs_sceneitem_get_scale_filter，obs_sceneitem_set_scale_filter函式，可用於取得和設定場景項的縮放濾鏡。

obs_sceneitem_get_scale_filter(item) obs_sceneitem_set_scale_filter(item, filter)

item 參數: item參數為需要取得或設定縮放濾鏡的場景項物件。
filter 參數: filter參數為縮放濾鏡，可使用如下obspython模組變數來進行設定，OBS_SCALE_DISABLE，OBS_SCALE_POINT，OBS_SCALE_BICUBIC，OBS_SCALE_BILINEAR，OBS_SCALE_LANCZOS。

取得和設定 OBS 場景項的混合模式

obspython模組的obs_sceneitem_get_blending_mode，obs_sceneitem_set_blending_mode函式，可用於取得和設定場景項的混合模式。

obs_sceneitem_get_blending_mode(item) obs_sceneitem_set_blending_mode(item, type)

item 參數: item參數為需要取得或設定混合模式的場景項物件。
type 參數: type參數為混合模式，可使用如下obspython模組變數來進行設定，OBS_BLEND_NORMAL，OBS_BLEND_ADDITIVE，OBS_BLEND_SUBTRACT，OBS_BLEND_SCREEN，OBS_BLEND_MULTIPLY，OBS_BLEND_LIGHTEN，OBS_BLEND_DARKEN。

取得和設定 OBS 場景項的混合方式

obspython模組的obs_sceneitem_get_blending_method，obs_sceneitem_set_blending_method函式，可用於取得和設定場景項的混合方式。

obs_sceneitem_get_blending_method(item) obs_sceneitem_set_blending_method(item, method)

item 參數: item參數為需要取得或設定混合方式的場景項物件。
method 參數: method參數為混合方式，可使用如下obspython模組變數來進行設定，OBS_BLEND_METHOD_DEFAULT，OBS_BLEND_METHOD_SRGB_OFF。

取得和設定 OBS 場景項的 ID

場景項的 ID 是一個整數，不同場景項的 ID 不應相同，obspython模組提供了以下與場景項 ID 有關的函式。

obs_sceneitem_get_id函式，可用於取得場景項的 ID。

obs_sceneitem_set_id函式，可用於為場景項指定一個唯一的 ID，該函式不應被經常使用，他可能會產生一些錯誤。

obs_sceneitem_get_id(item) obs_sceneitem_set_id(item)

item 參數: item參數為需要取得或設定 ID 的場景項物件。

新增和釋放對 OBS 場景項的參考

obspython模組的obs_sceneitem_addref函式，可用於為場景項物件新增參考。每當你額外呼叫一次obs_sceneitem_addref函式，就需要對等增加一次obs_sceneitem_release函式的呼叫。

obspython模組的obs_sceneitem_release函式，可用於為場景項物件釋放參考，他適用於obs_scene_sceneitem_from_source函式所傳回的場景項物件。

obs_sceneitem_addref(item) obs_sceneitem_release(item)

item 參數: item參數為需要新增或釋放參考的場景項物件。

為場景建立並新增 OBS 群組

obspython模組的obs_scene_add_group，obs_scene_add_group2函式，可用於為場景建立並新增群組，群組物件會作為函式的傳回值。

obs_scene_add_group(scene, name) obs_scene_add_group2(scene, name, signal)

scene 參數: scene參數為需要新增群組的場景物件。
name 參數: name參數為群組名稱。
signal 參數: signal參數為True時，訊號將重新整理。

取得 OBS 群組

obspython模組的obs_scene_get_group函式，可用於取得場景中指定名稱的群組。

obs_scene_get_group(scene, name)

scene 參數: scene參數為需要取得的群組所在的場景物件。
name 參數: name參數為群組名稱。

取消 OBS 群組

obspython模組的obs_sceneitem_group_ungroup，obs_sceneitem_group_ungroup2函式，可用於取消一個群組。

obs_sceneitem_group_ungroup(group) obs_sceneitem_group_ungroup2(group, signal)

group 參數: group參數為需要取消的群組物件。
signal 參數: signal參數為True時，訊號將重新整理。

為 OBS 群組新增場景項

obspython模組的obs_sceneitem_group_add_item函式，可用於為群組新增場景項。

obs_sceneitem_group_add_item(group, item)

group 參數: group參數為需要新增場景項的群組物件。
item 參數: item參數為需要新增的場景項物件。

下面的程式碼，將建立新的群組Message，並新增場景項Hi。

items_and_groups.py

def test(props, prop):
	# …
	# 建立一個新的群組，並將 Hi 加入其中
	message = obs.obs_scene_add_group(scene, 'Message')
	obs.obs_sceneitem_group_add_item(message, hi)
	# …

為 OBS 群組移除場景項

obspython模組的obs_sceneitem_group_remove_item函式，可用於移除群組中的場景項。

obs_sceneitem_group_remove_item(group, item)

group 參數: group參數為需要移除場景項的群組物件。
item 參數: item參數為需要從群組中移除的場景項物件。

取得場景項所在的 OBS 群組

obspython模組的obs_sceneitem_get_group函式，可用於取得場景項所在的群組。

obs_sceneitem_get_group(scene, item)

scene 參數: scene參數為需要取得的群組所在的場景物件。
item 參數: item參數為群組中包含的場景項物件。

取得 OBS 群組所在的場景

obspython模組的obs_sceneitem_group_get_scene函式，可用於取得群組所在的場景。

obs_sceneitem_group_get_scene(group)

group 參數: group參數為需要取得場景的群組物件。

判斷場景項是否為 OBS 群組

obspython模組的obs_sceneitem_is_group函式，可用於判斷一個場景項是否為群組。

obs_sceneitem_is_group(item)

item 參數: item參數為需要判斷是否為群組的場景項物件。

在下面的程式碼中，我們首先取得了場景項Bye所在的群組，然後判斷其是否為群組，理所當然，結果顯示為True。

items_and_groups.py

def test(props, prop):
	# …
	# 取得場景項 Bye 所在的群組
	bye = obs.obs_scene_find_source_recursive(scene, 'Bye')
	group = obs.obs_sceneitem_get_group(scene, bye)
	obs.script_log(obs.LOG_INFO, f'是群組？{obs.obs_sceneitem_is_group(group)}')
	# …

[items_and_groups.py] 是群組？True

原始碼

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