Scenes & Sources

This guide covers switching and managing scenes, per-scene transition overrides, and working with scene items (the source instances inside a scene), including transforms, ordering, locking, and blend modes.

Scene Management

Function	Description
`SetCurrentScene(Name)`	Switch to a scene
`GetSceneList()`	Refresh scene list from OBS
`GetGroupList()`	Get all scene groups
`GetCachedScenes()`	Get locally cached scene list
`GetCachedScenesWithItems()`	Get scenes with their source items
`SetSceneItemEnabled(Scene, ItemId, Enabled)`	Show/hide a source

Scene CRUD

Function	Description
`CreateScene(Name)`	Create a new empty scene
`RemoveScene(Name)`	Delete a scene (fails if it’s the current scene)
`SetSceneName(Name, NewName)`	Rename a scene

Events:

OnSceneCreated(SceneName, SceneUuid, bIsGroup): Scene was created
OnSceneRemoved(SceneName, SceneUuid, bIsGroup): Scene was deleted
OnSceneNameChanged(SceneUuid, OldName, NewName): Scene was renamed

Note: You cannot delete the currently active scene. Switch to another scene first.

Scene Transition Overrides

Per-scene transition overrides let you use different transitions when switching TO specific scenes.

Function	Description
`GetSceneTransitionOverride(SceneName)`	Fetch override settings for a scene (async)
`SetSceneTransitionOverride(SceneName, TransitionName, DurationMs)`	Set override (`-1` duration = keep current)
`ClearSceneTransitionOverride(SceneName)`	Remove override, use default transition
`GetCachedTransitionOverride(SceneName, OutOverride)`	Get locally cached override data
`FetchAllTransitionOverrides()`	Fetch overrides for all cached scenes

Events:

OnTransitionOverrideReceived(SceneName, Override): Override data was fetched

Override struct (FOBSSceneTransitionOverride):

Field	Type	Description
`TransitionName`	FString	Name of override transition (empty = no override)
`TransitionDuration`	int32	Duration in ms (`-1` = no override)
`bHasOverride`	bool	True if an override is set

Scene Item Transforms

Function	Description
`GetSceneItemTransform(Scene, ItemId)`	Fetch transform properties from OBS
`SetSceneItemTransform(Scene, ItemId, Transform)`	Set all transform properties
`SetSceneItemPosition(Scene, ItemId, X, Y)`	Set position only
`SetSceneItemScale(Scene, ItemId, ScaleX, ScaleY)`	Set scale only
`SetSceneItemRotation(Scene, ItemId, Rotation)`	Set rotation in degrees
`SetSceneItemCrop(Scene, ItemId, L, T, R, B)`	Set crop in pixels
`SetSceneItemBounds(Scene, ItemId, Type, W, H, Align)`	Set bounding box
`GetSceneItemId(Scene, SourceName)`	Convert source name to scene item ID
`GetCachedSceneItemTransform(Scene, ItemId, OutTransform)`	Get cached transform data

Transform properties:

Position: X/Y coordinates in pixels
Scale: X/Y multipliers (1.0 = 100%)
Rotation: Degrees (0 to 360)
Crop: Pixels removed from each edge
Bounds: Bounding box type, size, and alignment
Alignment: Bitflags (0=center, 1=left, 2=right, 4=top, 8=bottom)

Bounds types:

Type	Description
`None`	No bounding box
`Stretch`	Stretch to fit (ignores aspect ratio)
`ScaleInner`	Fit inside bounds (letterboxing)
`ScaleOuter`	Fill bounds (may crop)
`ScaleToWidth`	Scale to match width
`ScaleToHeight`	Scale to match height
`MaxOnly`	Maximum size only (no upscaling)

Important: Scene items are identified by SceneItemId, not source name. The same source can appear multiple times in a scene with different IDs. Use GetSceneItemId() to convert a source name to its ID.

Scene Item Management (CRUD)

Function	Description
`CreateSceneItem(Scene, SourceName, Enabled)`	Add an existing source to a scene
`RemoveSceneItem(Scene, ItemId)`	Remove item from scene (source not deleted)
`DuplicateSceneItem(Scene, ItemId, DestScene)`	Clone item (empty dest = same scene)
`GetSceneItemLocked(Scene, ItemId)`	Query if item is locked
`SetSceneItemLocked(Scene, ItemId, Locked)`	Lock/unlock item in OBS UI
`GetGroupSceneItemList(GroupName)`	Get all items within a group
`GetSceneItemSource(Scene, ItemId)`	Get source info for a scene item
`GetSceneItemIndex(Scene, ItemId)`	Query z-order position
`SetSceneItemIndex(Scene, ItemId, Index)`	Set z-order (0 = back, higher = front)
`GetSceneItemBlendMode(Scene, ItemId)`	Query blend mode
`SetSceneItemBlendMode(Scene, ItemId, Mode)`	Set compositing blend mode

Blend modes:

Mode	Description
`Normal`	Default blending
`Additive`	Brightens (adds colors)
`Subtract`	Darkens (subtracts colors)
`Screen`	Screen blending
`Multiply`	Multiply blending
`Lighten`	Keeps lighter pixels
`Darken`	Keeps darker pixels

Notes:

CreateSceneItem requires an existing source and cannot create new sources.
DuplicateSceneItem creates a reference, not a copy. Changes to the source affect both.
RemoveSceneItem only removes the reference. The underlying source remains available.
Index 0 is the back of the scene (rendered first), and higher values are closer to the front.
Blend mode changes do NOT fire OBS events, so track them locally if needed.

Events

Scenes

OnCurrentSceneChanged(SceneName, SceneUuid): Active scene changed
OnSceneListUpdated: Scene list was refreshed
OnSceneCreated(SceneName, SceneUuid, bIsGroup): New scene created
OnSceneRemoved(SceneName, SceneUuid, bIsGroup): Scene deleted
OnSceneNameChanged(SceneUuid, OldSceneName, NewSceneName): Scene renamed
OnTransitionOverrideReceived(SceneName, Override): Scene transition override data fetched

Scene Items

OnSceneItemTransformChanged(SceneName, SceneItemId, Transform): Scene item transform changed
OnSceneItemCreated(SceneName, SourceName, SceneItemId, SceneItemIndex): Item added to scene
OnSceneItemRemoved(SceneName, SourceName, SceneItemId): Item removed from scene
OnSceneItemEnableStateChanged(SceneName, SceneItemId, bEnabled): Item visibility changed
OnSceneItemLockStateChanged(SceneName, SceneItemId, bLocked): Item lock state toggled
OnSceneItemListReindexed(SceneName): Items reordered in scene (z-order changed)

For the full catalog of events across every OBS domain, see the Events reference.