Usage Examples

Basic Audio Player Operations

import omni.audioplayer
import time

# Create an audio player instance
player = omni.audioplayer.create_audio_player()

# Load a sound file (this happens asynchronously)
player.load_sound("/path/to/your/sound.wav")

# Play the sound from the beginning
player.play_sound("/path/to/your/sound.wav")

# Wait a bit for the sound to start playing
time.sleep(1)

# Pause the sound
player.pause_sound()

# Check the current play position
position = player.get_play_cursor()
print(f"Current position: {position:.2f} seconds")

# Check total sound length
length = player.get_sound_length()
print(f"Total sound length: {length:.2f} seconds")

# Resume playing from the paused position
player.unpause_sound()

# Wait for some playback time
time.sleep(1)

# Seek to a specific position (in seconds)
player.set_play_cursor(10.0)

# Stop playback completely
player.stop_sound()

Event Handling for Audio Playback

import omni.audioplayer
from carb.eventdispatcher import get_eventdispatcher
import time

# Create an audio player
player = omni.audioplayer.create_audio_player()

# Define a callback function to handle audio events
def event_loaded(event):
    print("Sound has been loaded successfully:", event["success"])

def event_ended(_):
    print("Sound has finished playing")

# Subscribe to events from the player's event stream
sub1 = get_eventdispatcher().observe_event(
    event_name=omni.audioplayer.GLOBAL_EVENT_LOADED,
    on_event=event_loaded,
    filter=player.get_event_key()
)
sub2 = get_eventdispatcher().observe_event(
    event_name=omni.audioplayer.GLOBAL_EVENT_ENDED,
    on_event=event_ended,
    filter=player.get_event_key()
)

# Load and play a sound
player.play_sound("/path/to/your/sound.wav")

# Wait for the sound to complete or for specific events
time.sleep(5)

# Stop the sound, which will generate an ENDED event
player.stop_sound()

# Clean up the subscription when done
sub1 = None
sub2 = None

Playing Audio from Memory

import omni.audioplayer
import time

# Create an audio player
player = omni.audioplayer.create_audio_player()

# Create a simple silent audio buffer for demonstration
# This represents 1 second of silence in 16-bit stereo at 48kHz
raw_audio_data = b'\x00\x00\x00\x00' * 48000  # 4 bytes per frame (16-bit stereo)

# Method 1: Play audio data without headers (raw PCM)
player.play_sound_in_memory(
    name="raw_audio",
    bytes=raw_audio_data,
    frame_rate=48000,       # 48 kHz sample rate
    channels=2,             # Stereo audio
    format=omni.audioplayer.RawPcmFormat.PCM_16,  # 16-bit PCM
    startTime=0.0,          # Start at the beginning
    flags=omni.audioplayer.FLAG_RAW_DATA  # Flag indicating this is raw PCM data
)

# Method 2: Use preprocessed WAV file data in memory (if you had valid WAV data)
# Note: This is a simplified WAV header followed by silence - for demonstration only
wav_header = (
    b'RIFF\x24\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x02\x00'
    b'\x44\xAC\x00\x00\x10\xB1\x02\x00\x04\x00\x10\x00data\xa0\x0f\x00\x00'
)
player.play_sound_in_memory(
    name="wav_audio",
    bytes=wav_header + b'\x00\x00\x00\x00' * 1000,  # Small amount of silence
    frame_rate=44100,      # Will be ignored as WAV header contains this info
    channels=2,            # Will be ignored as WAV header contains this info
    format=omni.audioplayer.RawPcmFormat.PCM_16,  # Will be ignored for WAV
    startTime=0.0,
    flags=0                # No flags needed for WAV file data
)

Drawing Audio Waveforms

import omni.audioplayer
import time
import math
import carb

# Create an audio player
player = omni.audioplayer.create_audio_player()

# Generate a simple sine wave for demonstration (1 second at 48kHz)
sample_rate = 48000
duration = 1  # seconds
frequency = 480  # A4 note
raw_samples = bytearray()

# Create 1 second of sine wave
for i in range(sample_rate * duration):
    value = math.sin(2 * math.pi * frequency * i / sample_rate)
    # Convert to 16-bit PCM
    sample = int(value * 32767)
    # Add to our sample buffer (little endian)
    raw_samples.extend(sample.to_bytes(2, byteorder='little', signed=True))

# Load our sine wave into the audio player
player.load_sound_in_memory(
    "sine_wave", 
    bytes(raw_samples), 
    sample_rate, 
    1,  # Mono
    omni.audioplayer.RawPcmFormat.PCM_16, 
    omni.audioplayer.FLAG_RAW_DATA
)

# Wait for the sound to load
time.sleep(1)

# Define waveform dimensions and colors
width, height = 800, 200
foreground_color = [1.0, 1.0, 1.0, 1.0]  # White
background_color = [0.0, 0.0, 0.0, 1.0]  # Black

# Get a valid temporary directory for saving files
temp_dir = carb.tokens.get_tokens_interface().resolve("${temp}")

# Draw waveform to a file
output_path = f"{temp_dir}/waveform.png"
player.draw_waveform_to_file(
    output_path, 
    width, 
    height, 
    foreground_color, 
    background_color
)
print(f"Waveform saved to: {output_path}")