Events Reference#

omni.audioplayer Events#

Warning

All omni.audioplayer events are global, but generally listeners are interested in only a specific player instance. All omni.audioplayer events have an audioPlayerInstance parameter that can be used to filter events for only a specific instance. The AudioPlayer.get_event_key() function can be used to obtain the event filter criteria that can be passed as the filter parameter to the carb.eventdispatcher.IEventDispatcher.observe_event() function.

omni.audioplayer events can be observed in their deferred or immediate forms. The immediate events are dispatched in the callback from the audio engine, whereas the deferred events happen from a worker thread at a later time and not from the context of the audio engine.

The deferred events are recommended in most cases and are considered safer to use.

To use the immediate event name, append _IMMEDIATE to the Python constant.

Since all events exist in a global namespace, factory event descriptors are composed as follows:

omni.audioplayer:<event name>[:immediate]

Where <event name> is the event name listed below and :immediate is optionally appended for the immediate context event.

Loading complete#

Dispatched when the requested audio is finished loading. Load is initiated by omni.audioplayer.AudioPlayer.load_sound(), omni.audioplayer.AudioPlayer.play_sound(), or omni.audioplayer.AudioPlayer.set_play_cursor().

  • Event name: loaded

  • Python constant: omni.audioplayer.GLOBAL_EVENT_LOADED

Parameters:

  • success (bool) - Whether the audio load was successful or not.

  • audioPlayerInstance (uintptr_t) - The unique identifier of the audio player.

Sound ended#

Dispatched when the requested audio has completed playback. This can occur if a previous sound was stopped explicitly with omni.audioplayer.AudioPlayer.stop_sound() or implicitly by calling omni.audioplayer.AudioPlayer.set_play_cursor() or omni.audioplayer.AudioPlayer.play_sound() when another sound is playing.

  • Event name: ended

  • Python constant: omni.audioplayer.GLOBAL_EVENT_ENDED

Parameters:

  • audioPlayerInstance (uintptr_t) - The unique identifier of the audio player.

Converting Legacy Events#

Previously, events were sent through an event stream. Now events are dispatched through the global event dispatcher.

Converting Python#

Old:

import omni.audioplayer
import carb.events

player = omni.audioplayer.create_audio_player()
stream = player.get_event_stream()

self.subscription = stream.create_subscription_to_pop(
    on_event,
    carb.events.DEFAULT_ORDER, # optional
    "My subscription name"
)

New:

import omni.audioplayer
import carb.eventdispatcher

player = omni.audioplayer.create_audio_player()

self.subscription = omni.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My observer name",
    filter=player.get_event_key(), # very important to specify this filter to limit events to `player`
    event_name=omni.audioplayer.GLOBAL_EVENT_LOADED,
    order=carb.eventdispatcher.DEFAULT_ORDER, # optional
    on_event=on_event
)