omni.usd module

omni.usd module reference

class omni.usd.AudioManager
class omni.usd.Enum(value)

Generic enumeration.

Derive from this class to define new enumerations.

name

The name of the Enum member.

value

The value of the Enum member.

class omni.usd.LayerEditMode

Members:

AUTO_AUTHORING

NORMAL

AUTO_AUTHORING = LayerEditMode.AUTO_AUTHORING
NORMAL = LayerEditMode.NORMAL
property name

handle) -> str

Type

(self

class omni.usd.LayerSpecState

Members:

NORMAL

LINKED

LOCKED

LINKED = LayerSpecState.LINKED
LOCKED = LayerSpecState.LOCKED
NORMAL = LayerSpecState.NORMAL
property name

handle) -> str

Type

(self

class omni.usd.Layers
get_all_locked_specs(self: omni.usd._usd.Layers) → List[str]
get_default_edit_layer_identifier(self: omni.usd._usd.Layers) → str
get_dirty_sublayers(self: omni.usd._usd.Layers) → List[str]
get_layer_edit_mode(self: omni.usd._usd.Layers) → omni::usd::LayerEditMode
get_layer_lock_user_name(self: omni.usd._usd.Layers, arg0: str) → str
get_layer_name(self: omni.usd._usd.Layers, arg0: str) → str

Gets layer links for specific specs.

Parameters

  • spec_paths (List[str]) – List of spec paths.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Dictionary that key is the spec path, and value is the list of layer identifiers.

Return type

Dict[str, List[str]]

Gets spec paths linked to layers.

Parameters

layer_identifiers (List[str]) – List of layer identifiers to query.

Returns

Dictionary that key is the layer identifier, and value is the list of spec paths.

Return type

Dict[str, List[str]]

get_specs_states(self: omni.usd._usd.Layers, spec_paths: List[str], hierarchy: bool = False) → Dict[str, omni::usd::LayerSpecState]

Gets states for specific specs.

Parameters

  • spec_paths (List[str]) – List of spec paths.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Dictionary that key is the spec path, and value is state with type LayerSpecState.

Return type

Dict[str, List[str]]

get_used_sublayers(self: omni.usd._usd.Layers) → List[str]
is_auto_authoring_layer(self: omni.usd._usd.Layers, arg0: str) → bool
is_layer_globally_muted(self: omni.usd._usd.Layers, arg0: str) → bool
is_layer_in_fast_replication(self: omni.usd._usd.Layers, arg0: str) → bool
is_layer_locally_muted(self: omni.usd._usd.Layers, arg0: str) → bool
is_layer_locked(self: omni.usd._usd.Layers, arg0: str) → bool
is_layer_locked_by_other(self: omni.usd._usd.Layers, arg0: str) → bool
is_layer_muteness_global(self: omni.usd._usd.Layers) → bool
is_layer_writable(self: omni.usd._usd.Layers, arg0: str) → bool

Link specs to layers so layer edits to those specs will only be authored to those layers.

Parameters

  • spec_paths (List[str]) – List of spec paths to be linked.

  • layer_identifiers (List[str]) – List of layer identifiers to link the spec to.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Dict that key is spec path that is linked successfully, value is the layers it links to.

Return type

Dict[str, List[str]]

lock_specs(self: omni.usd._usd.Layers, spec_paths: List[str], hierarchy: bool = False) → Set[str]

Lock specs so that any edits to those specs will be discarded.

Parameters

  • spec_paths (List[str]) – List of spec paths to be locked.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Set of locked spec paths.

Return type

Set[str]

merge_layers(self: omni.usd._usd.Layers, arg0: str, arg1: str, arg2: bool) → None
merge_prim_spec(self: omni.usd._usd.Layers, arg0: str, arg1: str, arg2: str, arg3: bool) → None

Restores spec links from dictionary.

Parameters

spec_links (Dict[str, List[str]]) – Dict of spec links, of which key is the spec path, and value is list of linked layers.

set_default_edit_layer_identifier(self: omni.usd._usd.Layers, arg0: str) → None
set_layer_edit_mode(self: omni.usd._usd.Layers, arg0: omni::usd::LayerEditMode) → None
set_layer_fast_replication_state(self: omni.usd._usd.Layers, arg0: str, arg1: bool) → None
set_layer_lock_state(self: omni.usd._usd.Layers, arg0: str, arg1: bool) → None
set_layer_muteness_scope(self: omni.usd._usd.Layers, arg0: bool) → None
subscribe_to_default_edit_layer_events(self: omni.usd._usd.Layers, fn: Callable[[str, str], None]) → carb._carb.Subscription

Subscribes to change of default edit layer events.

subscribe_to_layer_edit_mode_events(self: omni.usd._usd.Layers, fn: Callable[[omni::usd::LayerEditMode, omni::usd::LayerEditMode], None]) → carb._carb.Subscription

Subscribes to change of edit mode events.

subscribe_to_layer_metadata_events(self: omni.usd._usd.Layers, fn: Callable[[str, List[str]], None]) → carb._carb.Subscription

Subscribes to change of metadata events.

subscribe_to_layer_muteness_events(self: omni.usd._usd.Layers, fn: Callable[], None]) → carb._carb.Subscription

Subscribes to global muteness events of root layer.

subscribe_to_layer_muteness_scope_events(self: omni.usd._usd.Layers, fn: Callable[[bool], None]) → carb._carb.Subscription

Subscribes to change of muteness scope events.

subscribe_to_lock_events(self: omni.usd._usd.Layers, fn: Callable[[str, str, str, bool], None]) → carb._carb.Subscription

Subscribes to lock events of layer.

subscribe_to_prim_spec_events(self: omni.usd._usd.Layers, fn: Callable[[str, str], None]) → carb._carb.Subscription

Subscribes to prim spec events of layer.

Subscribes to change of spec links events.

subscribe_to_spec_locks_events(self: omni.usd._usd.Layers, fn: Callable[[bool, List[str]], None]) → carb._carb.Subscription

Subscribes to change of spec locks events.

subscribe_to_sublayer_events(self: omni.usd._usd.Layers, fn: Callable[[str, str, omni::usd::SublayerChangeType], None]) → carb._carb.Subscription

Subscribes to sublayer events of layer.

Remove spec links from layers.

Parameters

  • spec_paths (List[str]) – List of spec paths to be removed.

  • layer_identifiers (List[str]) – List of layer identifiers. If layer_identifiers is empty, it means to remove specified specs from all linked layers. Otherwise, it will remove specified spec links from specified layers.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Set of specs that are successfully unlinked.

Return type

Set[str]

Removes specified specs that are linked to any layers.

Parameters

  • spec_paths (List[str]) – List of spec paths to be removed.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Set of specs that are successfully unlinked.

Return type

Set[str]

Removes all spec links that are linked to specific layers.

Parameters

layer_identifiers (List[str]) – List of layer identifiers.

Returns

Set of specs that are successfully unlinked.

Return type

Set[str]

unlock_all_specs(self: omni.usd._usd.Layers) → None
unlock_specs(self: omni.usd._usd.Layers, spec_paths: List[str], hierarchy: bool = False) → Set[str]

Unlock specs so it can be authored.

Parameters

  • spec_paths (List[str]) – List of spec paths to be unlocked.

  • hierarchy (bool) – Consider all descendents of the prims specified by the path attribute.

Returns

Set of locked spec paths.

Return type

Set[str]

class omni.usd.PickingMode

Members:

NONE

RESET_AND_SELECT

MERGE_SELECTION

INVERT_SELECTION

TRACK

INVERT_SELECTION = PickingMode.INVERT_SELECTION
MERGE_SELECTION = PickingMode.MERGE_SELECTION
NONE = PickingMode.NONE
RESET_AND_SELECT = PickingMode.RESET_AND_SELECT
TRACK = PickingMode.TRACK
property name

handle) -> str

Type

(self

class omni.usd.PrimCaching(usd_type, stage, on_changed=None)
destroy()
get_cache_state()
get_stage()
set_cache_state(state)
class omni.usd.Selection
clear_selected_prim_paths(self: omni.usd._usd.Selection) → bool
get_selected_prim_paths(self: omni.usd._usd.Selection) → List[str]
is_prim_path_selected(self: omni.usd._usd.Selection, arg0: str) → bool
select_all_prims(self: omni.usd._usd.Selection, type_names: object = None) → None

Select all prims with specific types.

select_inverted_prims(self: omni.usd._usd.Selection) → None
set_prim_path_selected(self: omni.usd._usd.Selection, arg0: str, arg1: bool, arg2: bool, arg3: bool, arg4: bool) → bool
set_selected_prim_paths(self: omni.usd._usd.Selection, arg0: List[str], arg1: bool) → bool
class omni.usd.StageEventType

Stage operation results.

Members:

SAVED

SAVE_FAILED

OPENED

OPEN_FAILED

CLOSING

CLOSED

SELECTION_CHANGED

ASSETS_LOADED

ASSETS_LOAD_ABORTED

GIZMO_TRACKING_CHANGED

MDL_PARAM_LOADED

SETTINGS_LOADED

SETTINGS_SAVING

ASSETS_LOADED = StageEventType.ASSETS_LOADED
ASSETS_LOAD_ABORTED = StageEventType.ASSETS_LOAD_ABORTED
CLOSED = StageEventType.CLOSED
CLOSING = StageEventType.CLOSING
GIZMO_TRACKING_CHANGED = StageEventType.GIZMO_TRACKING_CHANGED
MDL_PARAM_LOADED = StageEventType.MDL_PARAM_LOADED
OPENED = StageEventType.OPENED
OPEN_FAILED = StageEventType.OPEN_FAILED
SAVED = StageEventType.SAVED
SAVE_FAILED = StageEventType.SAVE_FAILED
SELECTION_CHANGED = StageEventType.SELECTION_CHANGED
SETTINGS_LOADED = StageEventType.SETTINGS_LOADED
SETTINGS_SAVING = StageEventType.SETTINGS_SAVING
property name

handle) -> str

Type

(self

class omni.usd.StageLiveModeType

Stage Live Mode Type.

Members:

ALWAYS_ON

TOGGLE_ON

TOGGLE_OFF

ALWAYS_ON = StageLiveModeType.ALWAYS_ON
TOGGLE_OFF = StageLiveModeType.TOGGLE_OFF
TOGGLE_ON = StageLiveModeType.TOGGLE_ON
property name

handle) -> str

Type

(self

class omni.usd.StageRenderingEventType

Rendering Events.

Members:

NEW_FRAME

NEW_FRAME = StageRenderingEventType.NEW_FRAME
property name

handle) -> str

Type

(self

class omni.usd.StageState

Stage states.

Members:

CLOSED

CLOSING

OPENING

OPENED

CLOSED = StageState.CLOSED
CLOSING = StageState.CLOSING
OPENED = StageState.OPENED
OPENING = StageState.OPENING
property name

handle) -> str

Type

(self

class omni.usd.SublayerChangeType

Members:

ADD

REMOVE

OFFSET

ADD = SublayerChangeType.ADD
OFFSET = SublayerChangeType.OFFSET
REMOVE = SublayerChangeType.REMOVE
property name

handle) -> str

Type

(self

class omni.usd.TransformHelper
add_to_attr_order(attr_order, path, use_placeholder=False)
get_transform_attr(attrs)
is_common_attr(source_attr)
is_transform(source_path: str)
order_attrs(attrs, order)
class omni.usd.UsdContext
add_to_pending_creating_mdl_paths(self: omni.usd._usd.UsdContext, path: str = '', recreate: bool = False, loadInputs: bool = True) → bool
async attach_stage_async(stage) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().attach_stage_with_callback(). It’s used to attach an existing opened stage. Return a (result, error) tuple. Where error string is empty if result is False.

attach_stage_with_callback(self: omni.usd._usd.UsdContext, stage_id: int, on_finish_fn: Callable[[bool, str], None] = None) → bool
can_close_stage(self: omni.usd._usd.UsdContext) → bool
can_open_stage(self: omni.usd._usd.UsdContext) → bool
can_save_stage(self: omni.usd._usd.UsdContext) → bool
close_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None] = None) → bool
async close_stage_async() → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().close_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

close_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None]) → bool
compute_path_world_bounding_box(self: omni.usd._usd.UsdContext, arg0: str) → Tuple[carb._carb.Double3, carb._carb.Double3]
compute_path_world_transform(self: omni.usd._usd.UsdContext, arg0: str) → List[float[16]]
disable_save_to_recent_files(self: omni.usd._usd.UsdContext) → None
enable_save_to_recent_files(self: omni.usd._usd.UsdContext) → None
export_as_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None] = None) → bool
async export_as_stage_async(url: str) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().export_as_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

export_as_stage_with_callback(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None]) → bool
get_attached_hydra_engine_names(self: omni.usd._usd.UsdContext) → List[str]
get_layers(self: omni.usd._usd.UsdContext) → omni::usd::Layers
get_rendering_event_stream(self: omni.usd._usd.UsdContext) → carb.events._events.IEventStream
get_selection(self: omni.usd._usd.UsdContext) → omni::usd::Selection
get_stage()

Returns current pxr.Usd.Stage

get_stage_audio_manager(self: omni.usd._usd.UsdContext) → omni.usd._usd.AudioManager
get_stage_event_stream(self: omni.usd._usd.UsdContext) → carb.events._events.IEventStream
get_stage_id(self: omni.usd._usd.UsdContext) → int
get_stage_live_mode(self: omni.usd._usd.UsdContext) → omni.usd._usd.StageLiveModeType
get_stage_loading_status(self: omni.usd._usd.UsdContext) → Tuple[str, int, int]
get_stage_state(self: omni.usd._usd.UsdContext) → omni.usd._usd.StageState
get_stage_url(self: omni.usd._usd.UsdContext) → str
has_pending_edit(self: omni.usd._usd.UsdContext) → bool
is_layer_live(self: omni.usd._usd.UsdContext, arg0: str) → bool
is_new_stage(self: omni.usd._usd.UsdContext) → bool
is_omni_stage(self: omni.usd._usd.UsdContext) → bool
is_stage_live(self: omni.usd._usd.UsdContext) → bool
is_writable(self: omni.usd._usd.UsdContext) → bool
async load_mdl_parameters_for_prim_async(prim)
load_render_settings_from_stage(self: omni.usd._usd.UsdContext, arg0: int) → None
new_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None] = None) → bool
async new_stage_async() → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().new_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

new_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None]) → bool
async next_frame_async(inViewportId=0) → None

Wait for frame complete event from Kit for specific viewport.

async next_stage_event_async() → Tuple[omni.usd._usd.StageEventType, Dict[Any, Any]]

Wait for next stage event of omni.usd.

async next_usd_async(inViewportId=0) → None

Wait for frame complete event from Kit for specific viewport.

open_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None] = None, load_set: omni.usd._usd.UsdContextInitialLoadSet = UsdContextInitialLoadSet.LOAD_ALL) → bool
async open_stage_async(url: str, load_set: omni.usd._usd.UsdContextInitialLoadSet = UsdContextInitialLoadSet.LOAD_ALL) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().open_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

open_stage_with_callback(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None], load_set: omni.usd._usd.UsdContextInitialLoadSet = UsdContextInitialLoadSet.LOAD_ALL) → bool
register_selection_group(self: omni.usd._usd.UsdContext) → int
remove_all_hydra_engines(self: omni.usd._usd.UsdContext) → None
reopen_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None] = None, load_set: omni.usd._usd.UsdContextInitialLoadSet = UsdContextInitialLoadSet.LOAD_ALL) → bool
async reopen_stage_async(load_set: omni.usd._usd.UsdContextInitialLoadSet = UsdContextInitialLoadSet.LOAD_ALL) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().reopen_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

reopen_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None], load_set: omni.usd._usd.UsdContextInitialLoadSet = UsdContextInitialLoadSet.LOAD_ALL) → bool
save_as_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str, List[str]], None] = None) → bool
async save_as_stage_async(url: str) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().save_as_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

save_as_stage_with_callback(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str, List[str]], None]) → bool
save_layers(self: omni.usd._usd.UsdContext, new_root_layer_path: str, layer_identifiers: List[str], on_finish_fn: Callable[[bool, str, List[str]], None] = None) → bool
async save_layers_async(new_root_layer_path: str, layer_identifiers: List[str]) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().save_layers_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

save_layers_with_callback(self: omni.usd._usd.UsdContext, new_root_layer_path: str, layer_identifiers: List[str], on_finish_fn: Callable[[bool, str, List[str]], None]) → bool
save_render_settings_to_current_stage(self: omni.usd._usd.UsdContext) → None
save_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str, List[str]], None] = None) → bool
async save_stage_async() → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().save_stage_with_callback(). Return a (result, error) tuple. Where error string is empty if result is False.

save_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str, List[str]], None]) → bool
async selection_changed_async() → List[str]

Wait for selection to be changed. Return a list of newly selected paths.

set_layer_live(self: omni.usd._usd.UsdContext, arg0: str, arg1: bool) → None
set_pending_edit(self: omni.usd._usd.UsdContext, arg0: bool) → None
set_pickable(self: omni.usd._usd.UsdContext, arg0: str, arg1: bool) → None
set_selection_group(self: omni.usd._usd.UsdContext, groupId: int, path: str) → None
set_selection_group_outline_color(self: omni.usd._usd.UsdContext, groupId: int, color: carb._carb.Float4) → None
set_selection_group_shade_color(self: omni.usd._usd.UsdContext, groupId: int, color: carb._carb.Float4) → None
set_stage_live(self: omni.usd._usd.UsdContext, arg0: omni.usd._usd.StageLiveModeType) → None
subscribe_to_live_mode_update_events(self: omni.usd._usd.UsdContext, fn: Callable[[bool, str, bool], None]) → carb._carb.Subscription

Subscribes to live mode events.

Parameters

  • （Callable[bool (fn) – Callback to be called to receive the updates. The first parameter means if it’s to update all layers. If the first parameter is false, second parameter is given as layer identifier that means it’s to update single layer. The third parameter means live or not-live for all layers or single layer based on the first parameter.

  • str – Callback to be called to receive the updates. The first parameter means if it’s to update all layers. If the first parameter is false, second parameter is given as layer identifier that means it’s to update single layer. The third parameter means live or not-live for all layers or single layer based on the first parameter.

  • bool]) – Callback to be called to receive the updates. The first parameter means if it’s to update all layers. If the first parameter is false, second parameter is given as layer identifier that means it’s to update single layer. The third parameter means live or not-live for all layers or single layer based on the first parameter.

class omni.usd.UsdContextInitialLoadSet

Specifies the initial set of prims to load when opening a UsdStage.

Members:

LOAD_ALL

LOAD_NONE

LOAD_ALL = UsdContextInitialLoadSet.LOAD_ALL
LOAD_NONE = UsdContextInitialLoadSet.LOAD_NONE
property name

handle) -> str

Type

(self

class omni.usd.UsdExtension
async static init_stage_event()
on_shutdown()
on_startup()
class omni.usd.UsdWatcher
destroy()
subscribe_to_change_info_path(path, on_change: Callable) → carb._carb.Subscription
subscribe_to_resync_path(path, on_change: Callable) → carb._carb.Subscription
class omni.usd.Value_On_Layer(value)

An enumeration.

No_Value = 0
ON_CURRENT_LAYER = 0
ON_STRONGER_LAYER = 1
ON_WEAKER_LAYER = 2
omni.usd.active_authoring_layer_context(usd_context) → pxr.Usd.EditContext

Gets the edit context for edit target if it’s in non-auto authoring mode, or edit context for default edit layer if it’s in auto authoring mode.

omni.usd.add_hydra_engine(name: str, context: omni.usd._usd.UsdContext) → None
omni.usd.attach_all_hydra_engines(context: omni.usd._usd.UsdContext) → None
omni.usd.attr_has_timesample_on_key(attr: pxr.Usd.Attribute, time_code: pxr.Usd.TimeCode)
omni.usd.can_be_copied(prim)
omni.usd.check_ancestral(prim)
omni.usd.clear_attr_val_at_time(attr: pxr.Usd.Attribute, time_code=Usd.TimeCode.Default(), auto_target_layer: bool = True)
omni.usd.copy_timesamples_from_weaker_layer(stage, attr: pxr.Usd.Attribute)
omni.usd.create_context(name: str = '') → omni.usd._usd.UsdContext
omni.usd.create_material_input(prim, name, value, vtype, def_value=None, min_value=None, max_value=None, display_name=None, display_group=None)
omni.usd.destroy_context(name: str = '') → bool
omni.usd.duplicate_prim(stage: pxr.Usd.Stage, prim_path: Union[str, pxr.Sdf.Path], path_to: Union[str, pxr.Sdf.Path], duplicate_layers: bool = True)

Duplicate prim. This will duplicate prim specs in all sublayers with the same prim path.

Parameters

  • stage (Usd.Stage) – Stage handle.

  • prim_path (Union[str, Sdf.Path]) – Prim path.

  • path_to (Union[str, Sdf.Path]) – Copy to path.

  • duplicate_layers (bool) – True if it’s to duplicate this prim in all layers. False if it’s to duplicate this prim in current edit target only.

Returns

True if successful, or false otherwise.

omni.usd.find_path_in_nodes(node, set_fn)
omni.usd.find_spec_on_session_or_its_sublayers(stage: pxr.Usd.Stage, path: pxr.Sdf.Path)
omni.usd.get_all_locked_specs(usd_context) → List[str]
omni.usd.get_all_sublayers(stage: pxr.Usd.Stage) → List[str]

Gets all sublayers rooted from root layer.

omni.usd.get_attribute_effective_defaultvalue_layer_info(stage, attr: pxr.Usd.Attribute)
omni.usd.get_attribute_effective_timesample_layer_info(stage, attr: pxr.Usd.Attribute)
omni.usd.get_authored_prim(prim)
omni.usd.get_composed_payloads_from_prim(prim: pxr.Usd.Prim) → List[Tuple[pxr.Sdf.Payload, pxr.Sdf.Layer]]

Gets composed payload list from prim.

Parameters

prim (Usd.Prim) – Handle of Usd.Prim.

Returns

List of payload items. Each item is a tuple that includes payload handle, and the layer it’s from.

omni.usd.get_composed_references_from_prim(prim: pxr.Usd.Prim) → List[Tuple[pxr.Sdf.Reference, pxr.Sdf.Layer]]

Gets composed reference list from prim.

Parameters

prim (Usd.Prim) – Handle of Usd.Prim.

Returns

List of reference items. Each item is a tuple that includes reference handle, and the layer it’s from.

omni.usd.get_context(name: str = '') → omni.usd._usd.UsdContext
omni.usd.get_dirty_layers(stage: str, include_root_layer=True)
omni.usd.get_edit_target_identifier(stage: pxr.Usd.Stage) → str

Gets the layer identifier of current edit target.

Parameters

stage (Usd.Stage) – Stage handle

Returns

Layer identifier or empty string if edit target is not set.

omni.usd.get_frame_time(time_code, fps)
omni.usd.get_frame_time_code(time, fps)
omni.usd.get_introducing_layer(prim: pxr.Usd.Prim) → Tuple[pxr.Sdf.Layer, pxr.Sdf.Path]

This function will find the introducing layer and prim path of this prim. An introducting layer is where the prim is firstly defined.

Parameters

prim (Usd.Prim) – Prim handle

Returns

Introducing layer and its introducing prim path.

Return type

Tuple[Sdf.Layer, Sdf.Path]

omni.usd.get_local_transform_SRT(prim, time=Usd.TimeCode.Default())
omni.usd.get_local_transform_matrix(prim: pxr.Usd.Prim, time_code: pxr.Usd.TimeCode = Usd.TimeCode.Default())
omni.usd.get_prim_at_path(path: pxr.Sdf.Path, usd_context_name: str = '') → pxr.Usd.Prim
omni.usd.get_prop_at_path(path: pxr.Sdf.Path, usd_context_name: str = '') → pxr.Usd.Property
omni.usd.get_sdf_layer(prim)
omni.usd.get_shader_from_material(prim, get_prim=False)
omni.usd.get_stage_next_free_path(stage: pxr.Usd.Stage, path: Union[str, pxr.Sdf.Path], prepend_default_prim: bool)
async omni.usd.get_subidentifier_from_material(prim: pxr.Usd.Prim, on_complete_fn: Optional[Callable] = None)
async omni.usd.get_subidentifier_from_mdl(mdl_file: str, on_complete_fn: Optional[Callable] = None)
omni.usd.get_timesamples_count_in_authoring_layer(stage, attr_path: pxr.Sdf.Path)
omni.usd.get_url_from_prim(prim)

Returns url of Prim when authored reference or None

omni.usd.get_watcher()
omni.usd.get_world_transform_matrix(prim: pxr.Usd.Prim, time_code: pxr.Usd.TimeCode = Usd.TimeCode.Default())
omni.usd.handle_exception(func)

Decorator to print exception in async functions

omni.usd.is_child_type(prim, type)
omni.usd.is_hidden_type(prim)
omni.usd.is_layer_globally_muted(usd_context, layer_identifier: str) → bool

Checkes if layer is globally muted or not in this usd context. Global muteness is a customize concept in Kit that’s not from USD. It’s used for complement the USD muteness, that works for two purposes: 1. It’s stage bound. So a layer is globally muted in this stage will not influence others. 2. It’s persistent. Right now, it’s saved inside the custom data of root layer.

After stage load, it will be read to initialize the muteness of layers. Also, global muteness only takes effective when it’s in global state mode. See omni.usd.UsdContext.set_layer_muteness_scope about how to switch muteness scope. When it’s not in global state mode, authoring global muteness will not incluence layer’s muteness in stage.

omni.usd.is_layer_locked(usd_context, layer_identifier: str) → bool

Checkes if layer is locked or not in this usd context. Layer lock is a customized concept in Kit that’s not from USD. It’s used to complement the concept of file permission. Unlike the writable permission on file system, lock is bound to stage. So a layer may be locked in this stage, but not for other stages. Lock status is persistent across sessions, and saved as a flag inside the custom data of root layer.

omni.usd.is_layer_writable(layer_identifier: str) → bool

Checks if layer is writable on file system.

omni.usd.is_path_valid(path: pxr.Sdf.Path)
omni.usd.is_prim_material_supported(prim)
omni.usd.is_spec_locked(usd_context, spec_path: Union[str, pxr.Sdf.Path]) → List[bool]
omni.usd.is_usd_readable_filetype(filepath: str)
omni.usd.is_usd_writable_filetype(filepath: str) → bool
omni.usd.lock_specs(usd_context, spec_paths: Union[str, pxr.Sdf.Path, List[Union[str, pxr.Sdf.Path]]], hierarchy=False) → List[str]
omni.usd.merge_layers(arg0: str, arg1: str, arg2: bool) → None
omni.usd.merge_prim_spec(dst_layer_identifier: str, src_layer_identifier: str, prim_spec_path: str, dst_is_stronger_than_src: bool = True, target_prim_path: str = '') → None

Merge prim specs between layers.

omni.usd.on_layers_saved_result(result: bool, err_msg: str, saved_layers: List[str], future: _asyncio.Future)
omni.usd.on_stage_result(result: bool, err_msg: str, future: _asyncio.Future)
omni.usd.readable_usd_dotted_file_exts()
omni.usd.readable_usd_file_exts()
omni.usd.readable_usd_file_exts_str()
omni.usd.readable_usd_files_desc()
omni.usd.readable_usd_re()
omni.usd.release_all_hydra_engines(context: omni.usd._usd.UsdContext = None) → None
async omni.usd.reload_layer_async(layer_identifier: str)

Reload specific layer, which will discard all the unsaved changes. For Omniverse Layer, it will also receive all updates from Omniverse.

Parameters

layer_identifier (str) – Layer identifier.

omni.usd.remove_property(prim_path: pxr.Sdf.Path, property_name: pxr.Sdf.Path)
omni.usd.resolve_paths(src_layer_identifier: str, dst_layer_identifier: str, store_relative_path: bool = True, relative_to_src_layer: bool = False) → None

Resolve external paths in dst layer against base layer specified by src_layer_identifier.

omni.usd.resolve_prim_path_references(layer: str, old_prim_path: str, new_prim_path: str) → None

Resolve all prim path reference to use new path. This is mainly used to remapping prim path reference after structure change of original prim.

Parameters

  • layer (Sdf.Layer) – Layer to resolve.

  • old_prim_path (str) – Old prim path.

  • new_prim_path (str) – New prim path that all old prim path references will be replaced to.

omni.usd.set_attr_val(attr: pxr.Usd.Attribute, val: Any, time_code=Usd.TimeCode.Default(), auto_target_layer: bool = True)

set_prop_val is misnamed. It should be set_attr_val. But had to keep it for backward comp

omni.usd.set_edit_target_by_identifier(stage: pxr.Usd.Stage, layer_identifier: str)

Sets the edit target of stage by layer identifier.

Parameters

  • stage (Usd.Stage) – Stage handle

  • layer_identifier (str) – Layer identifier

Returns

True if success, false if layer cannot be found, or layer is not in the layer statck of stage.

omni.usd.set_prop_val(prop: pxr.Usd.Property, val: Any, time_code=Usd.TimeCode.Default(), auto_target_layer: bool = True)
omni.usd.stitch_prim_specs(stage: pxr.Usd.Stage, prim_path: Union[str, pxr.Sdf.Path], target_layer: pxr.Sdf.Layer, target_prim_path: Optional[str] = None, include_references_or_payloads=False)

Sitches prim specs specified by path scattered in all sublayers and all its children to target layer.

Parameters

  • stage (Usd.Stage) – Stage handle.

  • prim_path (str) – Prim path to be stitched.

  • target_layer (Sdf.Layer) – Target layer to save the stitching results.

  • target_prim_path (str) – Target prim path. If it’s empty or none, it will be the prim_path.

  • include_references_or_payloads – If prim is defined inside references or payloads, and this is True, it will also stitch the defs from references or payloads, too.

omni.usd.unlock_all_specs(usd_context)
omni.usd.unlock_specs(usd_context, spec_paths: Union[str, List[str]], hierarchy=False) → List[str]
omni.usd.writable_usd_dotted_file_exts()
omni.usd.writable_usd_file_exts()
omni.usd.writable_usd_file_exts_str()
omni.usd.writable_usd_files_desc()
omni.usd.writable_usd_re()

omni.usd.audio module reference

This module contains bindings for the omni::usd::audio module. This provides functionality for playing and managing sound prims in USD scenes.

Sound files may be in RIFF/WAV, Ogg, or FLAC format. Data in the sound files may use 8, 16, 24, or 32 bit integer samples, or 32 bit floating point samples. Channel counts may be from 1 to 64 If more channels of data are provided than the audio device can play, some channels will be blended together automatically.

class omni.usd.audio.AssetLoadStatus

Members:

IN_PROGRESS

DONE

FAILED

NOT_REGISTERED

DONE = AssetLoadStatus.DONE
FAILED = AssetLoadStatus.FAILED
IN_PROGRESS = AssetLoadStatus.IN_PROGRESS
NOT_REGISTERED = AssetLoadStatus.NOT_REGISTERED
property name

handle) -> str

Type

(self

class omni.usd.audio.EventType

Members:

METADATA_CHANGE

LISTENER_LIST_CHANGE

ACTIVE_LISTENER_CHANGE

ACTIVE_LISTENER_CHANGE = EventType.ACTIVE_LISTENER_CHANGE
LISTENER_LIST_CHANGE = EventType.LISTENER_LIST_CHANGE
METADATA_CHANGE = EventType.METADATA_CHANGE
property name

handle) -> str

Type

(self

class omni.usd.audio.FeatureDefault

Members:

ON

OFF

FORCE_ON

FORCE_OFF

FORCE_OFF = FeatureDefault.FORCE_OFF
FORCE_ON = FeatureDefault.FORCE_ON
OFF = FeatureDefault.OFF
ON = FeatureDefault.ON
property name

handle) -> str

Type

(self

class omni.usd.audio.IStageAudio

This module contains bindings for the omni::usd::audio module. This provides functionality for playing and managing sound prims in USD scenes.

Sound files may be in RIFF/WAV, Ogg, or FLAC format. Data in the sound files may use 8, 16, 24, or 32 bit integer samples, or 32 bit floating point samples. Channel counts may be from 1 to 64 If more channels of data are provided than the audio device can play, some channels will be blended together automatically.

property INVALID_STREAMER_ID
create_capture_streamer()

Creates a new capture streamer. This streamer object may be used multiple times to capture audio for a stage. Once a capture has been stopped on it, this streamer can be reused for another capture without issue. It must be destroyed with destroy_capture_streamer() when it is no longer needed.

Parameters

mgr – the audio manager to create the new streamer on. This may not be None.

Returns

The handle to a new capture streamer if it is successfully created. When this handle is no longer needed, it must be destroyed with destroy_capture_streamer().

INVALID_STREAMER_ID if the new capture streamer could not be created.

destroy_capture_streamer(id)

Destroys a capture streamer.

Note that if the capture streamer is still running, this will asynchronously stop the capture streamer, so the file may not be finished being written by the time this call returns. If you need to ensure that capture has finished, call stop_capture() then call wait_for_capture() on that streamer before calling this function.

Parameters

  • mgr – the audio manager to destroy the streamer for. This may not be None.

  • id – the streamer to be destroyed. If this streamer is currently running a capture, it will be stopped first. Note that currently stopping one streamer will stop all installed streamers. All but the removed one will be restarted afterward. This will have the side effect of overwriting each other streamer’s file though. This can be avoided by stopping all streamers simultaneously first with stop_captures().

Returs:

no return value.

draw_waveform(prim, width, height, flags=34, channel=0, background=[0, 0, 0, 1.0], colors=[])

This will draw an RGBA image of the waveform of the sound asset in use by a Sound prim.

Parameters

  • prim – The prim which has the sound asset that will be rendered. Note that the mediaOffsetStart and mediaOffsetEnd properties of the prim are used to choose the region of the sound that is drawn. The asset for this prim must have been loaded or the call will fail.

  • width – The width, in pixels, of the output image.

  • height – The width, in pixels, of the output image.

  • flags –

    Flags that alter the style of the rendered image. This must be a combination of carb.audio.AUDIO_IMAGE_FLAG*.

    • AUDIO_IMAGE_FLAG_USE_LINES: The sound samples in the output image will be connected with lines, rather than just being individual points.

    • AUDIO_IMAGE_FLAG_NOISE_COLOR: Each sound sample is given a random color and the colors parameter is ignored.

    • AUDIO_IMAGE_FLAG_MULTI_CHANNEL: Each channel is drawn on top of the previous channel. The channel parameter is not used when this flag is set.

    • AUDIO_IMAGE_FLAG_ALPHA_BLEND: Each pixel drawn is alpha blended into the output image. This is only useful if the colors specified don’t have an alpha component of 1.0.

    • AUDIO_IMAGE_FLAG_SPLIT_CHANNELS: Each channel is rendered separately, organized vertically. This cannot be used in combination with AUDIO_IMAGE_FLAG_MULTI_CHANNEL; the rendering style chosen in this case is undefined. The channel parameter is not used when this flag is set.

  • channel – Which audio channel will be rendered. This is only used if AUDIO_IMAGE_FLAG_MULTI_CHANNEL and AUDIO_IMAGE_FLAG_SPLIT_CHANNELS are not set.

  • background – A normalized RGBA color to use as the background of the image.

  • colors – Normalized RGBA colors to use for each channel. If AUDIO_IMAGE_FLAG_MULTI_CHANNEL or AUDIO_IMAGE_FLAG_SPLIT_CHANNELS are used, each index into this list is the color of that audio channel. When those flags are not set, index 0 into this list is always used to render the selected channel. If a color is not specified, a default color is used instead.

Returns

A raw RGBA image with the rendered waveform. If the prim was not a sound prim or its asset had not been loaded yet, an empty list will be returned.

get_active_listener()

Get the active listener prim in the scene.

Parameters

arguments. (No) –

Returns

The active listener is returned, if an active listener prim is bound.

None is returned if no active listener prim is bound, which means the active camera is being used as the active listener.

get_concurrent_voices()

Get the minimum number of sounds in a scene that can be played concurrently.

Parameters

arguments. (No) –

Returns

The minimum number of sounds in a scene that can be played concurrently.

get_distance_delay_default()

Get the default value for whether distance delayed audio is enable for the current USD Stage.

Parameters

arguments. (No) –

Returns

The default value for whether distance delayed audio is enable for the current USD Stage.

get_doppler_default()

Get the default value for whether doppler calculations are enabled for the current USD Stage.

Parameters

arguments. (No) –

Returns

The default value for whether doppler calculations are enabled for the current USD Stage.

get_doppler_limit()

Gets the Limit on the maximum Doppler pitch shift that can be applied to a playing voice.

Parameters

arguments. (No) –

Returns

The Limit on the maximum Doppler pitch shift that can be applied to a playing voice.

get_doppler_scale()

Gets the scaler that can exaggerate or lessen the Doppler effect.

Parameters

arguments. (No) –

Returns

The scaler that can exaggerate or lessen the Doppler effect.

get_interaural_delay_default()

Get the default value for whether interaural delay is enabled for the current USD Stage.

Parameters

arguments. (No) –

Returns

The default value for whether interaural delay is enabled for the current USD Stage.

get_listener_by_index(index)

Retrieves a single listener prim currently in the stage.

Parameters

index – The zero based index of the listener to retrieve the SDF path for. This should be strictly less than the most recent return value of _get_listener_count().

Returns

The requested indexed listener prim in the stage if the index is valid.

None is returned if the given index was out of bounds of the number of listeners in the stage.

get_listener_count()

Retrieves the total number of listener prims currently in the stage.

Parameters

arguments. (No) –

Returns

The total number of listener prims currently in the stage. Note that this may change at any time due to user or script action so it is best to call this immediately before enumerating listeners.

get_metadata_change_stream()

Retrieve the event stream for metadata changes.

Parameters

mgr – The stage audio manager instance that this function acts upon. This must not be None.

Returns

An IEventStream which is pushed when metadata is changed.

None if the event stream could not be created for some reason.

get_nonspatial_time_scale()

Gets the timescale modifier for all non-spatial voices.

Parameters

arguments. (No) –

Returns

The timescale modifier for all non-spatial voices.

get_sound_asset_status(prim)

Queries whether the asset of an individual sound has been fully loaded.

Once the asset of a sound has been fully loaded, it should be possible to play with play_sound().

NOTE: this function is deprecated and will be replaced with a sound

asset loaded callback.

Parameters

The path to sound prim to retrieve the status of. (path) –

Returns

AssetLoadStatus.IN_PROGRESS if the asset is in the process of loading. AssetLoadStatus.DONE if the asset has finished loading and is ready for immediate playback. AssetLoadStatus.FAILED if the audio manager has not loaded. AssetLoadStatus.FAILED if the asset has failed to load. AssetLoadStatus.NOT_REGISTERED if the sound prim is not of type Sound or the path corresponds to a prim that doesn’t exist.

get_sound_count()

Retrieves the total number of registered sound objects in the USD stage.

Returns

The total number of sound prims in the current USD stage.

get_sound_length(prim, length_type=SoundLengthType.PLAY_LENGTH)

Retrieves length of a sound in seconds (if known).

This calculates the length of a USD stage sound in seconds. This will be the lesser of the difference between the sound’s start and end times (if an end time is set on the prim) or the length of the actual sound asset itself (if not looping). In either case, this will be the amount of time that the sound would be expected to play for if it were triggered. For sounds that are set to loop, the returned time will include all scheduled loop iterations. For sounds that are set to loop infinitely, this will be INFINITY.

Parameters

  • prim – The USD prim to query the length of. This must be of type AudioSchemaSound.

  • length_type – How the length of the sound is measured.

  • values are (Valid) –

    • SoundLengthType.PLAY_LENGTH: The length of time the sound is estimated to play for in the stage once it’s triggered. This will be the lesser of the difference between the sound’s start and end times (if an end time is set on the prim) or the length of the actual sound itself, multiplied by loop count. Note that timeScale is taken into account when calculating the play time of an asset. For sounds that are set to loop infinitely, this will be a very large number (on the scale of 100 days).

    • SoundLengthType.SOUND_LENGTH: The length of the sound. This doesn’t include the sound’s start time, end time or loop count. This is calculated using mediaOffsetStart and mediaOffsetEnd if those are set; otherwise, this just returns the sound asset’s length.

    • SoundLengthType.ASSET_LENGTH: The length of the underlying sound asset, ignoring any USD parameters.

Returns

The play length of the sound in seconds if the asset is loaded and the length can be calculated.

0.0 if the sound asset is not available yet or the length could not be properly calculated.

get_spatial_time_scale()

This gets the timescale modifier for all spatial voices.

Parameters

arguments. (No) –

Returns

The timescale modifier for all spatial voices.

get_speed_of_sound()

Gets the speed of sound in the medium surrounding the listener. This is measured in meters per second.

Parameters

arguments. (No) –

Returns

The speed of sound in the medium surrounding the listener.

has_audio()

Test if audio is working. If the audio manager has failed to load or has been explicitly disabled, this function will return False. This function will otherwise return True.

Returns

True if audio is in a working state. False if audio is in a disabled state.

is_sound_playing(prim)

Queries whether a sound object is currently playing.

This queries whether a sound is currently playing. If this fails, that may mean that the sound ended naturally on its own or it was explicitly stopped. Note that this may continue to return true for a short period after a sound has been stopped with stop_sound() or stop_all_sounds(). This period may be up to 20 milliseconds in extreme cases but will usually not exceed 10 milliseconds.

This only checks the most recently playing instance of a sound, if multiple simultaneous sounds have been spawned with playSound().

Parameters

prim – The USD prim to query the playing state for. This must be of type AudioSchemaSound.

Returns

true if the sound object is currently playing.

false if the sound has either finished playing or has not been played yet.

mgr = None
play_sound(prim)

Immediately plays the requested USD stage sound if it is loaded.

This plays a single non-looping instance of a USD stage sound immediately. The sound must have already been loaded. If the sound resource was missing or couldn’t be loaded, this call will simply be ignored. This will return immediately after scheduling the sound to play. It will never block for the duration of the sound playback. This sound may be prematurely stopped with stop_sound().

The loopCount parameter of the prim parameter is ignored in this call. This functionality will be added in a future revision.

Sound prims that are scheduled to play in an animation should not also be played with playSound(), since it may prevent them from playing when they are scheduled to play. This will be fixed in a future revision.

Parameters

prim – The USD prim to play. This must be of type AudioSchemaSound.

Returns

No return value.

set_active_listener(prim)

Change the active Listener prim in the scene.

Note that updating the active Listener’s uniform attributes, such as orientationFromView, will reset the active listener back to the active camera.

Parameters

prim – The prim to set as the active listener. This can be None to use the active camera as the active listener.

Returns

True if the prim at @p path was set as the active prim. False if the prim at @p path was not registered with hydra. This can occur if hydra has not informed the audio manager about its existence yet.

set_capture_filename(id, filename)

Sets the filename that a capture streamer will write to.

Parameters

  • mgr – the audio manager that owns the streamer id. This may not be None.

  • id – the streamer to set the filename for. This handle will have been returned from a previous call to create_capture_streamer(). This may not be INVALID_STREAMER_ID.

  • filename – the name and path of the file to write the streamer’s data to once its capture is started. If the filename is set here, a None filename may be passed into start_capture().

Returns

no return value.

set_concurrent_voices(value=64)

The minimum number of sounds in a scene that can be played concurrently.

In a scene where concurrentVoices is set to N and N + 1 sounds are played concurrently, Omniverse Kit will choose to not play the N+1 th sound to the audio device and just track it as a ‘virtual’ voice. The voices chosen to become ‘virtual’ will be the lowest priority or silent. A ‘virtual’ voice should begin playing again once there is an empty voice to play on.

Parameters

value – The new value for the number of concurrent voices.

Returns

No return value.

set_device(deviceName)

Switches to use a new device for for audio output.

This sets the device that the audio manager will use for its output. If the requested device cannot be used for any reason, the default output device will be used instead. The device may change the final output format. If a streamer is attached to the previous output, its stream will be closed before opening a new stream on the new device. Even if the new device name matches the current device’s name, the device will still be changed and any stream reset.

If multiple devices attached to the system have the same name, the one that is chosen may be undefined. This can be a common issue with certain devices showing up in the system as simply “Speakers”. Using the device’s GUID instead will allow a specific device to be used instead, even its name exactly matches that of another device.

Parameters

deviceName – The name or GUID of the device to set as active. This must exactly match the name or GUID of one of the devices attached to the system at the time. If the given name or GUID doesn’t match one of the connected devices, the default device will be used instead. This may be set to nullptr or an empty string to use the system’s default device. This device name or identifier may be retrieved from the IAudioDeviceEnum interface.

Returns

No return value.

set_distance_delay_default(value=FeatureDefault.OFF)

Set the default value for whether distance delayed audio is enable for the current USD Stage.

This will append the USD Stage metadata to add this new scene setting.

Parameters

value –

The value to set this as. This must be one of the following values:

  • FeatureDefault.ON: Sounds with enableDistanceDelay set to “default” will have distance delay effects applied.

  • FeatureDefault.OFF: Sounds with enableDistanceDelay set to “default” will not have distance delay effects applied. This is the default because distance delay can have a very confusing effect if worldUnitScale hasn’t been set correctly.

  • FeatureDefault.FORCE_ON: all Sounds will have distance delay effects applied. This setting is intended to let users test what effect distance delay is having on their scene without requiring all Sounds to have their enableDistanceDelay property set to “default”.

  • FeatureDefault.FORCE_OFF: all Sounds will have distance delay effects disabled. This setting is intended to let users test what effect distance delay having on their scene without requiring all Sounds to have their enableDistanceDelay property set to “default”.

Returns

No return value.

set_doppler_default(value=FeatureDefault.OFF)

Set the default value for whether doppler calculations are enabled for the current USD Stage.

This will append the USD Stage metadata to add this new scene setting.

Parameters

value –

The value to set this as. This must be one of the following values:

  • FeatureDefault.ON: Sounds with enableDoppler set to “default” will have Doppler effects applied.

  • FeatureDefault.OFF: Sounds with enableDoppler set to “default” will not have Doppler effects applied. This is the default because Doppler effect’s implementation is still experimental. The default will be switched to FeatureDefault.ON when the feature is stabilized.

  • FeatureDefault.FORCE_ON: all Sounds will have Doppler effects applied. This setting is intended to let users test what effect the Doppler effect is having on their scene without requiring all Sounds to have their enableDoppler property set to “default”.

  • FeatureDefault.FORCE_OFF: all Sounds will have Doppler effects disabled. This setting is intended to let users test what effect the Doppler effect having on their scene without requiring all Sounds to have their enableDoppler property set to “default”.

Returns

No return value.

set_doppler_limit(value=2.0)

Sets a Limit on the maximum Doppler pitch shift that can be applied to a playing voice. Since Omniverse Kit does not handle supersonic spatial audio, a maximum frequency shift must be set for prims that move toward the listener at or faster than the speed of sound. This is mostly useful for handling edge cases such as teleporting an object far away while it’s playing a sound.

Parameters

value – The new value for the doppler limit.

Returns

No return value.

set_doppler_scale(value=1.0)

Sets a scaler that can exaggerate or lessen the Doppler effect. Setting this above 1.0 will exaggerate the Doppler effect. Setting this below 1.0 will lessen the Doppler effect. Negative values and zero are not allowed. Doppler effects alter the pitch of a sound based on its relative velocity to the listener.

Parameters

value – The new value for the doppler scale.

Returns

No return value.

set_interaural_delay_default(value=FeatureDefault.OFF)

Set the default value for whether interaural delay is enabled for the current USD Stage.

This will append the USD Stage metadata to add this new scene setting.

Parameters

value –

The value to set. This must be one of the following values:

  • FeatureDefault.ON: Sounds with enableInterauralDelay set to “default” will have interaural delay effects applied. This is the default.

  • FeatureDefault.OFF: Sounds with enableInterauralDelay set to “default” will not have interaural delay effects applied.

  • FeatureDefault.FORCE_ON: all Sounds will have interaural delay effects applied. This setting is intended to let users test what effect interaural delay is having on their scene without requiring all Sounds to have their enableInterauralDelay property set to “default”.

  • FeatureDefault.FORCE_OFF: all Sounds will have distance delay effects disabled. This setting is intended to let users test what effect interaural delay having on their scene without requiring all Sounds to have their enableInterauralDelay property set to “default”.

Returns

No return value.

set_nonspatial_time_scale(value=1.0)

Sets the timescale modifier for all non-spatial voices. Each prim multiplies its timeScale attribute by this value. For example, setting this to 0.5 will play all non-spatial sounds at half speed and setting this to 2.0 will play all non-spatial sounds at double speed. Altering the playback speed of a sound will affect the pitch of the sound. The limits of this setting under Omniverse Kit are [1/1024, 1024].

Parameters

value – The new value for the non-spatial timescale.

Returns

No return value.

set_spatial_time_scale(value=1.0)

This sets the timescale modifier for all spatial voices. Each prim multiplies its timeScale attribute by this value. For example, setting this to 0.5 will play all spatial sounds at half speed and setting this to 2.0 will play all non-spatial sounds at double speed. This affects delay times for the distance delay effect. Altering the playback speed of a sound will affect the pitch of the sound. The limits of this setting under Omniverse Kit are [1/1024, 1024]. This feature is intended to allow time-dilation to be performed with the sound effects in the scene without affecting non-spatial elements like the background music.

Parameters

value – The new value for the spatial timescale.

Returns

No return value.

set_speed_of_sound(value=340.0)

Sets the speed of sound in the medium surrounding the listener (typically air). This is measured in meters per second. This would typically be adjusted when doing an underwater scene. The speed of sound in dry air at sea level is approximately 340.0m/s.

Parameters

value – The new value for the speed of sound.

Returns

No return value.

spawn_voice(prim)

Immediately plays the requested USD stage sound as a new carb.audio.Voice if it is loaded.

This begins playing the requested sound as a new carb.audio.Voice. The sound must have already been loaded or None will be returned. The spawned voice plays the sound asynchronously for the lifetime of the voice. This is intended for cases where the behavior of playSound() is too limiting.

stopAllSounds() and stopSound() do not affect the playing voices spawned from this call.

Unlike playSound(), the loopCount parameter of the prim is used, so the voice must be explicitly stopped if the voice is infinitely looping.

Unlike playSound(), these voice handles are managed separately from the voice handles of the timeline, so spawning a voice from a sound that will play on the timeline shouldn’t affect that sound’s timeline playback. Stopping the timeline will also not stop these playing voices.

Parameters

path – The path to sound prim to spawn a voice from.

Returns

This returns the new voice that was spawned. This voice’s settings are only a snapshot of the sound prim that they were based off. Updates to these parameters will have to be performed on the returned voice through the IAudioPlayback interface.

this returns nullptr if a new voice could not be spawned.

start_capture(id, filename)

Starts the capture on a single streamer.

Parameters

  • mgr – the audio manager that owns the streamer id. This may not be None.

  • id – the handle of the streamer to start. This handle will have been returned from a previous call to create_capture_streamer(). This may not be INVALID_STREAMER_ID.

  • filename – the name and path of the filename to write the streamer’s data to once its capture is started. If a filename was set with a previous call to set_capture_filename() on the same streamer, this may be None to use that filename. If a non-None and non-empty filename is given here, it will always override any filename previously set on the streamer.

Returns

True if the streamer is successfully started. Note that starting a streamer currently has the side effect of stopping and restarting all other streamers that are currently running a capture. This will result in each streamer’s output file being overwritten. If multiple streamers need to be started simultaneously, start_captures() should be used instead.

False if the streamer could not be started.

start_captures(ids)

Starts multiple streamers simultaneously. This attempts to start one or more streamers simultaneously. If successful, all streamers are guaranteed to be started in sync with each other such that their first written audio frame matches. If this method is used to start multiple streamers, the stop_captures() function must also be used to stop those same streamers simultaneously. If another streamer starts or stops independently, it will cause all streamers to be closed then reopened which will overwrite each of their files.

Parameters

  • mgr – the audio manager that owns the streamer handles in ids. This may not be None.

  • ids – the list of streamers to start a capture on. Any entries that are set to INVALID_STREAMER_ID in this list will be ignored. Each valid entry must have had its filename set with set_capture_filename() first otherwise it will be skipped. Any streamer that is already running a capture will be skipped, but a side effect of this operation will be that its stream will be closed and reopened thereby overwriting its file. this may not be None.

Returns

True if at least one streamer is successfully started.

False if no streamers could be started or all streamers were skipped for one of the reasons listed under streamers.

stop_all_sounds()

Stops all currently playing USD stage sounds.

This stops all currently playing stage sounds. Any sounds that have been queued for playback will be stopped. UI sounds will not be affected. This is intended to be used to reset the sound playback system when an animation sequence is stopped. This will be automatically called internally whenever the animation sequence is stopped or it loops.

Returns

No return value.

stop_capture(id)

Stops the capture on a single streamer.

This will asynchronously stop the capture streamer, so the file may not be finished being written by the time this call returns. If you need to ensure that capture has finished, call wait_for_capture().

Parameters

  • mgr – the audio manager that owns the streamer id. This may not be None.

  • id – the handle to the streamer to stop. This will have been returned from a previous call to create_capture_streamer(). If a capture is not running on this streamer, it will be ignored. This may not be INVALID_STREAMER_ID.

Returns

True if the streamer is successfully stopped.

False if the streamer handle was invalid or a capture was not running on it.

stop_captures(ids)

Stops the capture on multiple streamers simultaneously.

This will asynchronously stop the capture streamer, so the file may not be finished being written by the time this call returns. If you need to ensure that capture has finished, call wait_for_capture().

Parameters

  • mgr – the audio manager that owns the streamer handles in ids. This may not be None.

  • ids – the list of streamers to stop the capture on. Any INVALID_STREAMER_ID entries will be ignored. Each valid entry must be currently running a capture otherwise it will be skipped. This may not be None.

Returns

True if at least one streamer is successfully stopped.

False if no streamers could be stopped.

stop_sound(prim)

Immediately schedules the stop of the playback of a sound.

This stops the playback of an active sound. If the sound was not playing or had already naturally stopped on its own, this call is ignored. Note that is_sound_playing() may continue to return true for a short period after a sound has been stopped for a period of up to 20 milliseconds in extreme cases but will usually not exceed 10 milliseconds.

This only stops the most recently played instance of a sound, if multiple overlapping instances of a sound were played with playSound().

Parameters

prim – The USD prim to stop. This must be of type AudioSchemaSound.

Returns

No return value.

subscribe_to_asset_load(prim, callback)

Bind a callback for when assets are loaded.

This will fire the callback when the sound’s asset is loaded or immediately if the asset was already loaded. The callback will only fire once.

Parameters

  • prim – The sound prim to bind a callback to.

  • callback – The callback to fire once a load has occurred.

Returns

true if the callback was bound successfully. true if the callback was executed immediately. false if the prim path passed corresponds to a prim that’s not of type Sound. false if an unexpected error prevents the callback from occurring.

wait_for_capture(id, timeout_milliseconds)

Wait until the capture streamer has been disconnected.

Because stop_capture() does not stop the audio system or otherwise block to ensure that the streamer is disconnected, you must call wait_for_capture() to verify that a capture streamer has actually finished. This is mainly useful if you need to verify that a file written by a streamer has finished being written.

Parameters

  • id – the handle to the streamer to wait for. This will have been returned from a previous call to create_capture_streamer(). If a capture is not running on this streamer, it will be ignored. This may not be INVALID_STREAMER_ID.

  • timeout_milliseconds – The maximum number of milliseconds to wait for the streamer to close.

Returns

True if the capture streamer has disconnected.

False if the call timed out before the streamer could disconnect.

class omni.usd.audio.SoundLengthType

Members:

PLAY_LENGTH

SOUND_LENGTH

ASSET_LENGTH

ASSET_LENGTH = SoundLengthType.ASSET_LENGTH
PLAY_LENGTH = SoundLengthType.PLAY_LENGTH
SOUND_LENGTH = SoundLengthType.SOUND_LENGTH
property name

handle) -> str

Type

(self

omni.usd.audio.get_stage_audio_interface() → omni.usd.audio.IStageAudio

helper method to retrieve a cached version of the IStageAudio interface.

Returns

The omni.usd.audio.IStageAudio interface.

omni.usd.audio.test_hydra_plugin() → bool

Test whether the Hydra audio plugin is accessible. This is intended to allow the tests to check whether the Hydra audio plugin is still working.

Parameters

arguments. (No) –

Returns

True if the plugin is accessible. False otherwise.