omni.usd module

omni.usd module reference

class omni.usd.AudioManager

Bases: pybind11_builtins.pybind11_object

class omni.usd.Dict(*args, **kwds)

Bases: dict, typing.MutableMapping

class omni.usd.Enum(value)

Bases: object

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.Extension(self: omni.ext._extensions.IExt) → None

Bases: omni.ext._extensions.IExt

on_shutdown()

class omni.usd.Layers

Bases: pybind11_builtins.pybind11_object

get_dirty_sublayers(self: omni.usd._usd.Layers) → List[str]

get_layer_lock_user_name(self: omni.usd._usd.Layers, arg0: str) → str

get_used_sublayers(self: omni.usd._usd.Layers) → List[str]

is_layer_globally_muted(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

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

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_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.

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.

class omni.usd.List(*args, **kwds)

Bases: list, typing.MutableSequence

class omni.usd.PrimCaching(usd_type, stage, on_changed=None)

Bases: object

destroy()

get_cache_state()

get_stage()

set_cache_state(state)

class omni.usd.Selection

Bases: pybind11_builtins.pybind11_object

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

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(self: omni.usd._usd.StageEventType, arg0: int) → None

Bases: pybind11_builtins.pybind11_object

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

UISTYLE_CHANGED

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

UISTYLE_CHANGED = StageEventType.UISTYLE_CHANGED

property name

handle) -> str

Type

(self

class omni.usd.StageLiveModeType(self: omni.usd._usd.StageLiveModeType, arg0: int) → None

Bases: pybind11_builtins.pybind11_object

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.StageState(self: omni.usd._usd.StageState, arg0: int) → None

Bases: pybind11_builtins.pybind11_object

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(self: omni.usd._usd.SublayerChangeType, arg0: int) → None

Bases: pybind11_builtins.pybind11_object

Members:

ADD

REMOVE

OFFSET

ADD = SublayerChangeType.ADD

OFFSET = SublayerChangeType.OFFSET

REMOVE = SublayerChangeType.REMOVE

property name

handle) -> str

Type

(self

class omni.usd.TransformHelper

Bases: object

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.Tuple(*args, **kwds)

Bases: tuple

Tuple type; Tuple[X, Y] is the cross-product type of X and Y.

Example: Tuple[T1, T2] is a tuple of two elements corresponding to type variables T1 and T2. Tuple[int, float, str] is a tuple of an int, a float and a string.

To specify a variable-length tuple of homogeneous type, use Tuple[T, …].

class omni.usd.UsdContext

Bases: pybind11_builtins.pybind11_object

add_to_pending_creating_mdl_paths(self: omni.usd._usd.UsdContext, path: str = '', recreate: bool = False) → 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

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_layers(self: omni.usd._usd.UsdContext) → omni::usd::Layers

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)

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_stage_event_async() → Tuple[omni.usd._usd.StageEventType, Dict[Any, Any]]

Wait for next stage event of omni.usd.

open_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None] = None) → bool

async open_stage_async(url: str) → 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]) → bool

reopen_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None] = None) → bool

async reopen_stage_async() → 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]) → bool

save_as_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, 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], None]) → bool

save_layers(self: omni.usd._usd.UsdContext, new_root_layer_path: str, layer_identifiers: List[str], on_finish_fn: Callable[[bool, 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], None]) → bool

save_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, 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], 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) → bool

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, str, 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.

sync_hydra_rprims(self: omni.usd._usd.UsdContext) → None

class omni.usd.UsdWatcher

Bases: object

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)

Bases: enum.Enum

An enumeration.

No_Value = 0

ON_CURRENT_LAYER = 0

ON_STRONGER_LAYER = 1

ON_WEAKER_LAYER = 2

omni.usd.add_hydra_engine(name: str, context: omni::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.copy_timesamples_from_weaker_layer(stage, attr: pxr.Usd.Attribute)

omni.usd.create_context(name: str = '') → omni::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.find_path_in_nodes(node, set_fn)

omni.usd.get_all_sublayers(stage)

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_context(name: str = '') → omni::usd::UsdContext

omni.usd.get_dirty_layers(stage, include_root_layer=True)

omni.usd.get_frame_time(time_code, fps)

omni.usd.get_frame_time_code(time, fps)

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) → pxr.Usd.Prim

omni.usd.get_prop_at_path(path: pxr.Sdf.Path) → pxr.Usd.Property

omni.usd.get_sdf_layer(prim)

omni.usd.get_shader_from_material(prim, get_prim=False)

async omni.usd.get_subidentifier_from_material(prim: pxr.Usd.Prim, on_complete_fn: 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

TODO: The alternative way would be better, but we want to use traceback.format_exc for better error message.

result = await asyncio.gather(*[func(*args)], return_exceptions=True)

omni.usd.is_child_type(prim, type)

omni.usd.is_hidden_type(prim)

omni.usd.is_layer_writable(layer_identifier)

omni.usd.is_path_valid(path: pxr.Sdf.Path)

omni.usd.is_prim_material_supported(prim)

omni.usd.layer_traverse(results, stage, parent_layer_identifier, layer, layer_identifier, current_subtree_stack)

omni.usd.on_stage_result(result: bool, err_msg: str, future: _asyncio.Future)

class omni.usd.partial

Bases: object

partial(func, *args, **keywords) - new function with partial application of the given arguments and keywords.

args

tuple of arguments to future partial calls

func

function object to use in future partial calls

keywords

dictionary of keyword arguments to future partial calls

omni.usd.remove_property(prim_path: pxr.Sdf.Path, property_name: pxr.Sdf.Path)

omni.usd.set_prop_val(prop: pxr.Usd.Property, val: Any, time_code=Usd.TimeCode.Default())

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(self: omni.usd.audio._audio.AssetLoadStatus, arg0: int) → None

Bases: pybind11_builtins.pybind11_object

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.FeatureDefault(self: omni.usd.audio._audio.FeatureDefault, arg0: int) → None

Bases: pybind11_builtins.pybind11_object

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

Bases: object

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.

Constructor for the IStageAudio interface instance. This will raise an Exception if it was unable to obtain an instance of the USD context interface.

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

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.

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_concurrent_voices(value)

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)

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)

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)

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)

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)

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)

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)

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)

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.

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_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.

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.