Overview#

The omni.audioplayer extension provides a basic audio playback API for previewing sound assets. It wraps the C++ omni::audio::IAudioPlayer interface, allowing users to play, pause, stop, and inspect sound assets through a simple Python or C++ interface. This extension is specifically designed for asset previewing and is not meant for integrated USD stage or UI sound playback.

Concepts#

At its core, omni.audioplayer exposes an AudioPlayer class along with a set of public APIs such as create_audio_player, play_sound, pause_sound, and methods to inspect sound state (e.g., get_play_cursor and get_sound_length). The extension includes support for loading sound files from disk and from memory, with additional parameters to handle raw PCM data using flags (FLAG_RAW_DATA and FLAG_FORCE_RELOAD) and the RawPcmFormat enum to specify the sample data format. CallbackType is used to monitor key events such as when an asset has loaded or when playback has ended.

Functionality#

The extension allows you to load sound assets asynchronously and manage a single-voice playback per AudioPlayer instance. Users can render audio waveforms to memory buffers or file outputs, offering a visual summary of sound assets. In addition, the API provides control over playback functions such as play, pause, unpause, stop, and adjusting the play cursor, making it practical for previewing audio content.

Relationships#

This extension depends on several core packages including carb.audio and omni.kit.audiodeviceenum, as well as omni.client for data source support. These dependencies ensure that audio handling integrates with the broader Omniverse Kit SDK capabilities, while delegating advanced audio tasks to carb.audio.

Considerations#

Designed solely for asset preview purposes, omni.audioplayer is not intended for live audio playback in a USD stage or integration with Kit UI sounds. For those cases, consider using the omni.usd.audio or omni.kit.uiaudio interfaces respectively. The extension supports common sound file formats such as RIFF/WAV, Ogg, MP3 (playback only), Opus, and FLAC and handles various sample formats and channel configurations.