LiveSyncing#

class omni.kit.usd.layers.LiveSyncing( layers_instance: ILayersInstance, usd_context, layers_state, )#

Bases: object

Live Syncing includes the interfaces to management Live Sessions of all layers in the bound UsdContext. A Live Session is a concept that extends non-destructive live workflow for USD layers so all connectors can join the session to co-work together.

Each Live Session is bound to an USD file with unique URL to be identified. And it has only unique instance in the same UsdContext for each layer, which means the Live Sessions can be joined multiple times. User can only join the Live Sessions that belong to the used layers in the bound UsdContext, either those layers are added as sublayers or references/payloads. If a layer is added as both a local sublayer or reference/payload, the sublayer and reference/payload cannot join the same Live Session at the same time. However, a Live Session can be joined multiple times if the corresponding layer is added as multiple references/payloads.

Thread Safety: All interfaces of LiveSyncing are not thread-safe. And It’s recommended to call those interfaces in the same loop thread as UsdContext.

Methods

`__init__`(layers_instance, usd_context, ...)
`broadcast_merge_done_message_async`([...])	Broadcasts merge finished message to other peer clients.
`broadcast_merge_started_message_async`([...])	Broadcasts merge started message to other peer clients.
`create_live_session`(name[, layer_identifier])	Creates a named Live Session.
`find_live_session_by_name`(layer_identifier, ...)	Finds the Live Session with name specified by `session_name`.
`get_all_current_live_sessions`([prim_path])	Gets all Live Sessions that are joined for all sublayers of the stage or a specific prim.
`get_all_live_sessions`([layer_identifier])	Gets all existing Live Sessions on disk (including joined and not joined ones) for a specific layer.
`get_current_live_session`([layer_identifier])	Gets the current Live Session of the base layer joined.
`get_current_live_session_layers`([...])	[DEPRECATED] Returns the Live Session layers attached to this Live Session of specifc base layer.
`get_current_live_session_peer_users`([...])	[DEPRECATED] Returns the list of users that joined in this Live Session.
`get_live_session_by_url`(session_url)	Gets the Live Session by the url.
`get_live_session_for_live_layer`(...)	Gets the Live Session that the live layer is attached to.
`is_in_live_session`()	[DEPRECATED] If root layer is in a Live Session.
`is_layer_in_live_session`([layer_identifier, ...])	Checks if the given layer is in a Live Session or not.
`is_live_session_layer`(layer_identifier)	Checks if the layer is the live layer (.live layer) of a Live Session.
`is_live_session_merge_notice_muted`(...)	Checks if layer identifier is in the mute list.
`is_prim_in_live_session`(prim_path[, ...])	If the prim is in any Live Session.
`is_stage_in_live_session`()	Checks if any layers that are in the used layers of the current stage are in a Live Session.
`join_live_session`(live_session[, prim_path])	Joins the Live Session.
`join_live_session_by_url`(layer_identifier, ...)	Joins the Live Session specified by the Live Session URL.
`merge_and_stop_live_session_async`([...])	Saves chagnes of Live Session to their base layer if it's in live mode.
`merge_changes_to_base_layers`(stop_session)	[DEPRECATED] Merges changes of root layer's Live Session to its base layer.
`merge_changes_to_specific_layer`(...)	[DEPRECATED] Merges changes of root layer's Live Session to specified layer.
`merge_live_session_changes`(layer_identifier, ...)	Merge Live Session for base layer.
`merge_live_session_changes_to_specific_layer`(...)	Merge Live Session for base layer to specified target layer.
`mute_live_session_merge_notice`(layer_identifier)	By default, when session owner merges the session, it will notify peer clients to leave the session by showing a prompt.
`open_stage_with_live_session_async`(stage_url)	Opens stage with Live Session joined.
`register_open_stage_addon`(callback)
`stop_all_live_sessions`()	Stops all the Live Sessions that are enabled for the current stage.
`stop_live_session`([layer_identifier, prim_path])	Stops the Live Session for specificed layer or prim.
`try_cancelling_live_session_join`(...)	Try to cancel the Live Session when LayerEventType.LIVE_SESSION_JOINING is received.
`unmute_live_session_merge_notice`(...)	Remove layer identifier from mute list.

Attributes

`layers_instance`	Native handle of Layers instance that's bound to an UsdContext.
`permission_to_merge_current_session`	[DEPRECATED] Checks to see if it can merge the current Live Session of specified layer.
`usd_context`	Instance of UsdContext.

__init__( layers_instance: ILayersInstance, usd_context, layers_state, ) → None#

async broadcast_merge_done_message_async( destroy: bool = True, layer_identifier: str | None = None, )#

Broadcasts merge finished message to other peer clients. This is normally called after merging the Live Session to its base layer.

“Args:

destroy (bool): If it needs to destroy the session channel after merging.

layer_identifier (str): The base layer of the Live Session.

async broadcast_merge_started_message_async( layer_identifier: str | None = None, )#: Broadcasts merge started message to other peer clients. This is normally called before merging the Live Session to its base layer.

create_live_session( name: str, layer_identifier: str | None = None, ) → LiveSession#

Creates a named Live Session.

Parameters:

name (str) – Name of the session. Currently, name should be unique across all Live Sessions.
layer_identifier (str) – The base layer to create a Live Session. If it’s not provided, it will be root layer by default.

Returns:

The Live Session handle if it’s success, or None otherwise. See Layers.get_last_error_type to get more details.

find_live_session_by_name( layer_identifier: str, session_name: str, ) → LiveSession#

Finds the Live Session with name specified by `session_name`. If it has multiple sessions that has the same name, it will return the first one found.

Parameters:

layer_identifier (str) – The base layer to search Live Sessions.
session_name (str) – The session name.

get_all_current_live_sessions( prim_path: Path | None = None, ) → List[LiveSession]#

Gets all Live Sessions that are joined for all sublayers of the stage or a specific prim.

Parameters:: prim_spec (Sdf.Path) – Specified prim to query. If prim_path is not None, it will return all live sessions joined for this prim. If it’s None, it will return the live sessions joined for all sublayers of the current stage.

get_all_live_sessions( layer_identifier: str | None = None, ) → List[LiveSession]#

Gets all existing Live Sessions on disk (including joined and not joined ones) for a specific layer. See `get_current_live_session` to query joined session for a specific layer.

Parameters:: layer_identifier (str) – The base layer to query Live Sessions. If it’s empty, it will be root layer by default.
Returns:: A list of Live Sessions.

get_current_live_session( layer_identifier: str | None = None, ) → LiveSession#

Gets the current Live Session of the base layer joined.

Parameters:: layer_identifier (str) – Base layer identifier. It’s root layer if it’s not provided.

get_current_live_session_layers( layer_identifier: str | None = None, ) → List[str]#: [DEPRECATED] Returns the Live Session layers attached to this Live Session of specifc base layer.

get_current_live_session_peer_users( layer_identifier: str | None = None, ) → List[LiveSessionUser]#

[DEPRECATED] Returns the list of users that joined in this Live Session.

Parameters:: layer_identifier (str) – It’s root layer if it’s not provided.

get_live_session_by_url( session_url, ) → LiveSession#: Gets the Live Session by the url. It can only get the Live Session belongs to one of the used layers in the current stage.

get_live_session_for_live_layer( live_layer_identifier: str, ) → LiveSession#

Gets the Live Session that the live layer is attached to.

Parameters:: live_layer_identifier (str) – The .live layer that’s in the Live Session.

is_in_live_session() → bool#: [DEPRECATED] If root layer is in a Live Session.

is_layer_in_live_session( layer_identifier: str | None = None, live_prim_only: bool = False, ) → bool#

Checks if the given layer is in a Live Session or not.

Parameters:

layer_identifier (str) – Base layer identifier. Root layer by default.
live_prim_only (bool) – When live_prim_only is True, it will only check the Live Sessions that are bound to reference/payload prims for the base layer. Otherwise, it will check all. False by default.

is_live_session_layer(layer_identifier: str) → bool#: Checks if the layer is the live layer (.live layer) of a Live Session.

is_live_session_merge_notice_muted( layer_identifier: str, ) → bool#: Checks if layer identifier is in the mute list.

is_prim_in_live_session( prim_path: Path, layer_identifier: str | None = None, from_reference_or_payload_only=False, ) → bool#

If the prim is in any Live Session.

Parameters:

prim_path (Sdf.Path) – Prim path to check.
layer_identifier (str) – If layer identifier is specified, it will check if prim is in the Live Session of that layer only.
from_reference_or_payload_only (bool) – If it’s True, it will check only references and payloads to see if the same Live Session is enabled already. Otherwise, it checks both the prim specificed by primPath and its references and payloads. This is normally used to check if the Live Session can be stopped as the prim that is in the Live Session may not own the Live Session, which is owned by its references or payloads, so it cannot stop the Live Session with the specified prim.

is_stage_in_live_session() → bool#: Checks if any layers that are in the used layers of the current stage are in a Live Session.

join_live_session( live_session: LiveSession, prim_path: Path | str | None = None, ) → bool#

Joins the Live Session.

Parameters:

live_session (LiveSession) – The Live Session to join. The base layer of the Live Session must be in the used layers of the current stage.
prim_path (Union[Sdf.Path, str]) – If prim path is provided, it means to join a Live Session for a reference or payload prim.

Returns:

True if it joins the session successfully. False otherwise. See Layers.get_last_error_type to get more details.

join_live_session_by_url( layer_identifier: str, live_session_url: str, create_if_not_existed: bool = False, ) → bool#

Joins the Live Session specified by the Live Session URL.

Parameters:

layer_identifier (str) – The base layer of the Live Session.
live_session_url (str) – The unique URL of the Live Session. The Live Session must be created against with the base layer, otherwise, it will fail to join.
create_if_not_existed (bool) – Creates the Live Session if it does not exist.

Returns:

True if it joins the session successfully. False otherwise. See Layers.get_last_error_type to get more details.

async merge_and_stop_live_session_async( target_layer: str | None = None, comment='', pre_merge: Callable[[LiveSession], Awaitable] | None = None, post_merge: Callable[[bool], Awaitable] | None = None, layer_identifier: str | None = None, ) → bool#

Saves chagnes of Live Session to their base layer if it’s in live mode.

Parameters:

target_layer (str) – Target layer to merge all live changes to.
comment (str) – The checkpoint comments.
pre_merge (Callable[[LiveSession], Awaitable]) – It will be called before merge.
post_merge (Callable[[bool, str], Awaitable]) – It will be called after merge is done. The first param means if it’s successful, and the second includes the error message if it’s not.
layer_identifier (str) – The base layer of the Live Session. It’s root layer if it’s not provided.

merge_changes_to_base_layers(stop_session: bool) → bool#: [DEPRECATED] Merges changes of root layer’s Live Session to its base layer.

merge_changes_to_specific_layer( target_layer_identifier: str, stop_session: bool, clear_target_layer: bool, ) → bool#: [DEPRECATED] Merges changes of root layer’s Live Session to specified layer.

merge_live_session_changes( layer_identifier: str, stop_session: bool, ) → bool#

Merge Live Session for base layer.

Parameters:

layer_identifier (str) – The base layer to merge Live Session.
stop_session (bool) – Stops the Live Session or not after merging.

Returns:

True if it’s successful, or False otherwise. If it returns False, it’s possible that the layer is not in the used layers of the current stage. Or it has no Live Session joined. Or it has not permissions to merge the Live Session. See Layers.get_last_error_type to get more details.

merge_live_session_changes_to_specific_layer( layer_identifier: str, target_layer_identifier: str, stop_session: bool, clear_target_layer: bool, ) → bool#

Merge Live Session for base layer to specified target layer.

Parameters:

layer_identifier (str) – The base layer to merge Live Session.
target_layer_identifier (str) – The target layer to merge the Live Session.
stop_session (bool) – Stops the Live Session or not after merging.
clear_target_layer (bool) – If it needs to clear the target layer before merging.

Returns:

True if it’s successful, or False otherwise. If it returns False, it’s possible that the layer is not in the used layers of the current stage. Or it has no Live Session joined. Or it has not permissions to merge the Live Session. See Layers.get_last_error_type to get more details.

mute_live_session_merge_notice(layer_identifier: str)#: By default, when session owner merges the session, it will notify peer clients to leave the session by showing a prompt. This is used to disable the prompt and stop session directly so it will not be disruptive especially for applications that don’t have layer window and manages all layers’ Live Sessions with scripting and don’t want to receive prompt for leaving sessions.

async open_stage_with_live_session_async( stage_url, session_name=None, ) → Tuple[bool, str]#

Opens stage with Live Session joined. This function is used to reduce the composition cost of opening a stage, then joining a Live Session by preparing the Live Session in the session layer before opening the stage. It supports to pass the name of Live Session as query string, for example, `omniverse://localhost/test/stage.usd?live_session_name=my_session`.

Parameters:

stage_url (str) – The stage url to open.
session_name (str) – If the session name is not provided in the stage url, this param will be used. If both stage url and this param don’t include a valid session, it will return false.

Returns:

A (bool, str) tutple, where the first element means if it’s success, and the error string int the second.

stop_all_live_sessions()#: Stops all the Live Sessions that are enabled for the current stage.

stop_live_session( layer_identifier: str | None = None, prim_path: Path | None = None, )#

Stops the Live Session for specificed layer or prim.

Parameters:

layer_identifier (str) – The base layer to stop its current Live Session. If it’s None and prim_path is None, it’s root layer by default.
prim_path (Sdf.Path) – The specified prim to stop the Live Session. If prim_path is given, and layer_identifier is None, it will stop all joined Live Sessions for this prim. Or if layer_identifier is not None, it will stop only the Live Session for the layer.

try_cancelling_live_session_join( layer_identifier: str, ) → LiveSession | None#

Try to cancel the Live Session when LayerEventType.LIVE_SESSION_JOINING is received.

Parameters:: layer_identifier (str) – The base layer to cancel.
Returns:: Instance of Live Session if it’s cancelled successfully. Or None otherwise.

unmute_live_session_merge_notice(layer_identifier: str)#: Remove layer identifier from mute list.

property layers_instance: ILayersInstance#: Native handle of Layers instance that’s bound to an UsdContext.

property permission_to_merge_current_session: bool#

[DEPRECATED] Checks to see if it can merge the current Live Session of specified layer.

Parameters:: layer_identifier (str) – The base layer of the Live Session. It’s root layer if it’s not provided.

property usd_context: UsdContext#: Instance of UsdContext.