omni.usd module

Introduction

Extension omni.usd serves to load and initialize Pixar USD library. It also provides managed UsdContext for easy USD Stage access, and state mangement, which provides both synchronous/asynchronous interfaces in C++ and Python to open/close/attach/save stage, and do state query. It also provides common utitlies and undoable commands for wrapped USD operations. omni.usd is the foundation component for all other extentions that need to access USD.

API Changes

Since Omniverse Kit 104.0, the native interfaces of layers that can be accessed with omni.usd.get_context().get_layers() will be deprecated and move to extenion omni.kit.usd.layers for clear responsibility and ABI consideration. For compatability consideration, all python APIs except ones about links and locks (which are experimental before, you need to refer omni.kit.usd.layers if you really use it and migrate all your code to that) are kept so it will not break any python extentions, and you will receive warnings for each access to those APIs. Also, those events subscription APIs prefixed with subscribe_xxx will not do any real work but kept as stubs. You need to migrate your code to use new interfaces. Moreover, all c++ APIs are removed since this release because they are ABI unsafe. Please refer to the doc of extension omni.kit.usd.layers for more details.

omni.usd module reference

class omni.usd.AudioManager

class omni.usd.LayerEditMode

AUTO_AUTHORING = 1

NORMAL = 0

SPEC_LINKING = 2

class omni.usd.Layers(usd_context)

destroy()

get_default_edit_layer_identifier()

get_dirty_sublayers()

get_layer_edit_mode()

get_layer_lock_user_name(layer_identifier)

get_layer_name(layer_identifier: bool)

get_used_sublayers()

is_auto_authoring_layer(layer_identifier: str)

is_layer_globally_muted(layer_identifier: str)

is_layer_locally_muted(layer_identifier: str)

is_layer_locked(layer_identifier: str)

is_layer_locked_by_other(layer_identifier: str)

is_layer_muteness_global()

is_layer_savable(layer_identifier: str)

is_layer_writable(layer_identifier: str)

merge_layers(target_layer_identifier: str, src_layer_identifier: str, dst_is_stronger_than_src: bool)

merge_prim_spec(target_layer_identifier: str, src_layer_identifier: str, prim_path: str, dst_is_stronger_than_src: bool)

set_default_edit_layer_identifier(layer_identifier: str)

set_layer_edit_mode(edit_mode: omni.usd._impl.layer_legacy.LayerEditMode)

set_layer_lock_state(layer_identifier: str, locked: bool)

set_layer_muteness_scope(global_scope: bool)

subscribe_to_default_edit_layer_events(**kwargs)

subscribe_to_layer_edit_mode_events(**kwargs)

subscribe_to_layer_metadata_events(**kwargs)

subscribe_to_layer_muteness_events(**kwargs)

subscribe_to_layer_muteness_scope_events(**kwargs)

subscribe_to_lock_events(**kwargs)

subscribe_to_prim_spec_events(**kwargs)

subscribe_to_sublayer_events(**kwargs)

class omni.usd.PickingMode

Members:

NONE

RESET_AND_SELECT

MERGE_SELECTION

INVERT_SELECTION

TRACK

INVERT_SELECTION = <PickingMode.INVERT_SELECTION: 3>

MERGE_SELECTION = <PickingMode.MERGE_SELECTION: 2>

NONE = <PickingMode.NONE: 0>

RESET_AND_SELECT = <PickingMode.RESET_AND_SELECT: 1>

TRACK = <PickingMode.TRACK: 5>

property name

property value

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

OPENING

OPENED

OPEN_FAILED

CLOSING

CLOSED

SELECTION_CHANGED

ASSETS_LOADED

ASSETS_LOAD_ABORTED

GIZMO_TRACKING_CHANGED

MDL_PARAM_LOADED

SETTINGS_LOADED

SETTINGS_SAVING

OMNIGRAPH_START_PLAY

OMNIGRAPH_STOP_PLAY

SIMULATION_START_PLAY

SIMULATION_STOP_PLAY

ANIMATION_START_PLAY

ANIMATION_STOP_PLAY

DIRTY_STATE_CHANGED

ASSETS_LOADING

ACTIVE_LIGHT_COUNTS_CHANGED

HIERARCHY_CHANGED

HYDRA_GEOSTREAMING_STARTED

HYDRA_GEOSTREAMING_STOPPED

HYDRA_GEOSTREAMING_STOPPED_NOT_ENOUGH_MEM

HYDRA_GEOSTREAMING_STOPPED_AT_LIMIT

ACTIVE_LIGHT_COUNTS_CHANGED = <StageEventType.ACTIVE_LIGHT_COUNTS_CHANGED: 22>

ANIMATION_START_PLAY = <StageEventType.ANIMATION_START_PLAY: 18>

ANIMATION_STOP_PLAY = <StageEventType.ANIMATION_STOP_PLAY: 19>

ASSETS_LOADED = <StageEventType.ASSETS_LOADED: 8>

ASSETS_LOADING = <StageEventType.ASSETS_LOADING: 21>

ASSETS_LOAD_ABORTED = <StageEventType.ASSETS_LOAD_ABORTED: 9>

CLOSED = <StageEventType.CLOSED: 6>

CLOSING = <StageEventType.CLOSING: 5>

DIRTY_STATE_CHANGED = <StageEventType.DIRTY_STATE_CHANGED: 20>

GIZMO_TRACKING_CHANGED = <StageEventType.GIZMO_TRACKING_CHANGED: 10>

HIERARCHY_CHANGED = <StageEventType.HIERARCHY_CHANGED: 23>

HYDRA_GEOSTREAMING_STARTED = <StageEventType.HYDRA_GEOSTREAMING_STARTED: 24>

HYDRA_GEOSTREAMING_STOPPED = <StageEventType.HYDRA_GEOSTREAMING_STOPPED: 25>

HYDRA_GEOSTREAMING_STOPPED_AT_LIMIT = <StageEventType.HYDRA_GEOSTREAMING_STOPPED_AT_LIMIT: 27>

HYDRA_GEOSTREAMING_STOPPED_NOT_ENOUGH_MEM = <StageEventType.HYDRA_GEOSTREAMING_STOPPED_NOT_ENOUGH_MEM: 26>

MDL_PARAM_LOADED = <StageEventType.MDL_PARAM_LOADED: 11>

OMNIGRAPH_START_PLAY = <StageEventType.OMNIGRAPH_START_PLAY: 14>

OMNIGRAPH_STOP_PLAY = <StageEventType.OMNIGRAPH_STOP_PLAY: 15>

OPENED = <StageEventType.OPENED: 3>

OPENING = <StageEventType.OPENING: 2>

OPEN_FAILED = <StageEventType.OPEN_FAILED: 4>

SAVED = <StageEventType.SAVED: 0>

SAVE_FAILED = <StageEventType.SAVE_FAILED: 1>

SELECTION_CHANGED = <StageEventType.SELECTION_CHANGED: 7>

SETTINGS_LOADED = <StageEventType.SETTINGS_LOADED: 12>

SETTINGS_SAVING = <StageEventType.SETTINGS_SAVING: 13>

SIMULATION_START_PLAY = <StageEventType.SIMULATION_START_PLAY: 16>

SIMULATION_STOP_PLAY = <StageEventType.SIMULATION_STOP_PLAY: 17>

property name

property value

class omni.usd.StageLiveModeType

ALWAYS_ON = 0

TOGGLE_OFF = 2

TOGGLE_ON = 1

class omni.usd.StageRenderingEventType

Rendering Events.

Members:

NEW_FRAME

NEW_FRAME = <StageRenderingEventType.NEW_FRAME: 0>

property name

property value

class omni.usd.StageState

Stage states.

Members:

CLOSED

CLOSING

OPENING

OPENED

CLOSED = <StageState.CLOSED: 0>

CLOSING = <StageState.CLOSING: 3>

OPENED = <StageState.OPENED: 2>

OPENING = <StageState.OPENING: 1>

property name

property value

class omni.usd.SublayerChangeType

ADD = 0

OFFSET = 2

REMOVE = 1

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: Export stage with all prims flattened, and it will include contents from session layer also.

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()

get_name(self: omni.usd._usd.UsdContext) → str

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()

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

get_timeline(self: omni.usd._usd.UsdContext) → omni.timeline._timeline.Timeline

get_timeline_name(self: omni.usd._usd.UsdContext) → str

has_pending_edit(self: omni.usd._usd.UsdContext) → bool

is_layer_live(**kwargs)

is_new_stage(self: omni.usd._usd.UsdContext) → bool

is_omni_stage(self: omni.usd._usd.UsdContext) → bool

is_stage_live()

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(load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → bool

async new_stage_async(load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → 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(fn=None, load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>): Python version of omni.usd.get_context.new_stage() that supports to customize load set of new stage.

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: 0>) → bool

async open_stage_async(url: str, load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>, session_layer_url: typing.Optional[str] = None) → Tuple[bool, str]

Asynchronous version of omni.usd.get_context().open_stage_with_callback().

Parameters

url (str) – Stage URL to open.
load_set (omni.usd.UsdContextInitialLoadSet) – If it’s to open all payloads or none.
session_layer_url (str) – Specified session layer.

Returns

A (success, error) tuple, where error string is empty if success is True.

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: 0>) → bool

open_stage_with_session_layer(self: omni.usd._usd.UsdContext, url: str, session_layer_url: str, on_finish_fn: Callable[[bool, str], None], load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → 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: 0>) → bool

async reopen_stage_async(load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → 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: 0>) → 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(**kwargs)

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(**kwargs)

set_timeline(self: omni.usd._usd.UsdContext, name: str = '') → None

subscribe_to_live_mode_update_events(**kwargs)

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: 0>

LOAD_NONE = <UsdContextInitialLoadSet.LOAD_NONE: 1>

property name

property value

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)

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.can_prim_have_children(stage: pxr.Usd.Stage, new_path: pxr.Sdf.Path, prim: pxr.Usd.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.correct_filename_case(file: str) → str

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, color_space=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 the current edit target only. If you want to collapse all overrides inside all layers of this prim, see omni.usd.stitch_prim_specs for reference.

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, predicate: Optional[Callable[[pxr.Sdf.Spec], bool]] = None)

Finds spec in the session layer or its sublayers.

Parameters

stage (Usd.Stage) – Stage instance.
path (Sdf.Path) – Spec path to find.
predicate (Callable[[Sdf.Spec], bool]) – If it’s provided, the spec to find must pass the predicate.

Returns

Layer that the spec resides in, and the spec handle. Or (None, None) if it cannot be found.

Return type

(Sdf.Layer, Sdf.Spec)

omni.usd.get_all_sublayers(stage, include_session_layers=False, include_only_omni_layers=False, include_anonymous_layers=True) → List[str]: Gets all sublayers ranking from strongest to weakest.

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, fix_slashes: bool = True) → 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, fix_slashes: bool = True) → 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_context_from_stage(stage: pxr.Usd.Stage): Gets corresponding UsdContext of the stage if it’s found.

omni.usd.get_context_from_stage_id(stage_id: int) → 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()) → Tuple[pxr.Gf.Vec3d, pxr.Gf.Vec3d, pxr.Gf.Vec3i, pxr.Gf.Vec3d]: Return a tuple of [scale, rotation, rotation_order, translate] for given prim.

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: Union[str, pxr.Usd.Stage] = '') → pxr.Usd.Prim

omni.usd.get_prim_descendents(root_prim)

omni.usd.get_prop_at_path(path: pxr.Sdf.Path, usd_context_name: Union[str, pxr.Usd.Stage] = '') → 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_ancestor_prim_type(stage: pxr.Usd.Stage, prim_path: pxr.Sdf.Path, prim_type: pxr.Usd.SchemaBase)

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

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_usd_readable_filetype(filepath: str)

omni.usd.is_usd_writable_filetype(filepath: str) → bool

omni.usd.make_path_relative_to_current_edit_target(url_path, stage=None)

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)

omni.usd.remove_property(prim_path: pxr.Sdf.Path, property_name: pxr.Sdf.Path, usd_context_or_stage: Union[str, pxr.Usd.Stage] = '')

omni.usd.resolve_paths(src_layer_identifier: str, dst_layer_identifier: str, store_relative_path: bool = True, relative_to_src_layer: bool = False, copy_sublayer_offsets: 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)

Sets the value of property.

Parameters

prop (Usd.Property) – Property handle.
val (Any) – Value of property.
time_code (Usd.TimeCode) – Time code to set, and it’s Usd.TimeCode.Default() by default.
auto_target_layer (bool) – Default is True. If it’s true, it will be authored into the sesison layer if the prim of the property is defined in the session layer. If it’s not defined in the session layer, it will find the property inside the session layer to check if there are overrides. If overrides are found, the value will be authored into the found layer instead. Otherwise, it will be authored into the current edit target.

omni.usd.shutdown_usd() → None

omni.usd.stitch_prim_specs(stage: pxr.Usd.Stage, prim_path: Union[str, pxr.Sdf.Path], target_layer: pxr.Sdf.Layer, target_prim_path: 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.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: 0>

FAILED = <AssetLoadStatus.FAILED: 2>

IN_PROGRESS = <AssetLoadStatus.IN_PROGRESS: 1>

NOT_REGISTERED = <AssetLoadStatus.NOT_REGISTERED: 3>

property name

property value

class omni.usd.audio.EventType

Members:

METADATA_CHANGE

LISTENER_LIST_CHANGE

ACTIVE_LISTENER_CHANGE

ACTIVE_LISTENER_CHANGE = <EventType.ACTIVE_LISTENER_CHANGE: 3>

LISTENER_LIST_CHANGE = <EventType.LISTENER_LIST_CHANGE: 2>

METADATA_CHANGE = <EventType.METADATA_CHANGE: 1>

property name

property value

class omni.usd.audio.FeatureDefault

Members:

ON

OFF

FORCE_ON

FORCE_OFF

FORCE_OFF = <FeatureDefault.FORCE_OFF: 3>

FORCE_ON = <FeatureDefault.FORCE_ON: 2>

OFF = <FeatureDefault.OFF: 1>

ON = <FeatureDefault.ON: 0>

property name

property value

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.

create_event_stream_for_capture(id)

Creates an event stream that the capture streamer will send data 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.

Returns

An event stream object. Call omni.usd.audio.create_event_listener() to receive callbacks for this object. Although you can directly subscribe to this callback, python is unsuitable for the required data conversion this needs.

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: of. (path The path to sound prim to retrieve the status) –
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.

Sounds that have not had their asset loaded yet (or their asset failed to load) will not show up in the sound count unless they’ve been passed to an IStageAudio function.

get_sound_length(prim, length_type=<SoundLengthType.PLAY_LENGTH: 0>)

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 OmniAudioSchemaOmniSound.
length_type – How the length of the sound is measured.
are (Valid values) –
- 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 OmniAudioSchemaOmniSound.

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 OmniAudioSchemaOmniSound.
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: 1>)

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: 1>)

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: 1>)

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=None)

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 OmniAudioSchemaOmniSound.
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: 2>

PLAY_LENGTH = <SoundLengthType.PLAY_LENGTH: 0>

SOUND_LENGTH = <SoundLengthType.SOUND_LENGTH: 1>

property name

property value

class omni.usd.audio.StreamListener

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.

Changelog