openal.py

OpenAL Audio Backend for LunaEngine - Optimized for 2D games

This module provides OpenAL-based audio with the following features:
- Efficient buffer management and pooling
- Support for WAV, OGG, MP3 formats (via Pygame)
- Smooth volume/pitch transitions
- Stereo panning support
- Thread-safe operations

class OpenALError

Description

Exception raised for OpenAL related errors.

Methods

No methods defined.

class OpenALAudioEvent

Description

Audio events for OpenAL system.

Attributes
COMPLETE: Any = 'complete'
STOP: Any = 'stop'
PAUSE: Any = 'pause'
RESUME: Any = 'resume'
Methods

No methods defined.

class OpenALBuffer

Description

OpenAL audio buffer with memory pooling.

Manages audio data in OpenAL buffers with caching for frequently used sounds.

Attributes:
   buffer_id (int): OpenAL buffer ID
   duration (float): Buffer duration in seconds
   size (int): Buffer size in bytes
   format (int): OpenAL format constant
   frequency (int): Sample rate in Hz
   last_used (float): Last access time for LRU cleanup

Attributes
_buffer_pool: Dict[str, 'OpenALBuffer'] = {}
Methods
def __init__(self: Any, buffer_id: int) -> Any
No documentation
def get_or_create(cls: Any, filepath: str) -> Optional['OpenALBuffer']
Get buffer from pool or create new one.

Args:
   filepath (str): Path to audio file
   
Returns:
   Optional[OpenALBuffer]: Buffer object or None if failed
def _update_buffer_info(self: Any) -> Any
Update buffer information from OpenAL.
def _load_audio_file(buffer_id: ALuint, filepath: str) -> bool
Load audio file into OpenAL buffer.

Args:
   buffer_id: OpenAL buffer ID
   filepath (str): Path to audio file
   
Returns:
   bool: True if successful
def _load_wav_file(buffer_id: ALuint, filepath: str) -> bool
Load WAV file using Python's wave module.
def _load_with_pygame(buffer_id: ALuint, filepath: str) -> bool
Load audio file using PyGame mixer.
def cleanup_unused(cls: Any, max_age: float = 300.0) -> Any
Clean up buffers not used for a while.
def get_duration(self: Any) -> float
Get buffer duration in seconds.

class OpenALSource

Description

OpenAL audio source for 2D games.

Provides playback control with smooth transitions and stereo panning.

Attributes:
   source_id (int): OpenAL source ID
   buffer (OpenALBuffer): Current audio buffer
   volume (float): Current volume (0.0-1.0)
   pitch (float): Current pitch multiplier
   pan (float): Stereo pan (-1.0 to 1.0)
   looping (bool): Whether source is looping

Methods
def __init__(self: Any, source_id: int) -> Any
No documentation
def set_buffer(self: Any, buffer: OpenALBuffer) -> Any
Set buffer for this source.
def set_volume(self: Any, volume: float, duration: float = 0.0) -> Any
Set volume with optional smooth transition.
def _fade_volume(self: Any, start: float, end: float, duration: float) -> Any
Fade volume over time (simplified implementation).
def set_pitch(self: Any, pitch: float, duration: float = 0.0) -> Any
Set pitch with optional transition.
def set_pan(self: Any, pan: float) -> Any
Set stereo panning.
def play(self: Any, loop: bool = False) -> Any
Start playback.
def pause(self: Any) -> Any
Pause playback.
def resume(self: Any) -> Any
Resume playback.
def stop(self: Any) -> Any
Stop playback.
def rewind(self: Any) -> Any
Rewind to beginning.
def is_playing(self: Any) -> bool
Check if source is playing.
def is_paused(self: Any) -> bool
Check if source is paused.
def get_playback_position(self: Any) -> float
Get current playback position in seconds.

class OpenALAudioSystem

Description

Main OpenAL audio system for 2D games.

Manages audio sources, buffers, and provides playback functionality.

Attributes:
   device: OpenAL device
   context: OpenAL context
   sources (List[OpenALSource]): Available audio sources
   max_sources (int): Maximum number of concurrent sources
   initialized (bool): Whether system is initialized

Methods
def __init__(self: Any, max_sources: int = 32) -> Any
No documentation
def initialize(self: Any) -> bool
Initialize OpenAL system.
def get_free_source(self: Any) -> Optional[OpenALSource]
Get a free audio source.
def load_sound(self: Any, filepath: str) -> Optional[OpenALBuffer]
Load sound file.
def play_sound(self: Any, filepath: str, volume: float = 1.0, pitch: float = 1.0, pan: float = 0.0, loop: bool = False) -> Optional[OpenALSource]
Play a sound effect.
def stop_all(self: Any) -> Any
Stop all sounds.
def update(self: Any) -> Any
Update audio system (clean up unused buffers).
def cleanup(self: Any) -> Any
Clean up all audio resources.

class OpenALAudioVisualizer

Description

Audio visualizer that works with OpenAL audio system.

Provides methods to capture and analyze audio data from OpenAL sources.

Methods
def __init__(self: Any, audio_system: OpenALAudioSystem) -> Any
Initialize audio visualizer.

Args:
   audio_system (OpenALAudioSystem): OpenAL audio system to visualize.
def _initialize_buffers(self: Any) -> Any
Initialize data buffers.
def capture_audio_data(self: Any, source: Optional[OpenALSource] = None) -> List[float]
Capture audio data from a source or all playing sources.

Args:
   source (Optional[OpenALSource]): Specific source to capture from.
   
Returns:
   List[float]: Normalized audio data.
def perform_fft_analysis(self: Any, audio_data: List[float]) -> List[float]
Perform FFT analysis on audio data.

Args:
   audio_data (List[float]): Time-domain audio data.
   
Returns:
   List[float]: Frequency-domain data.
def get_peak_level(self: Any) -> float
Get current peak audio level.

Returns:
   float: Peak level (0-1).
def get_rms_level(self: Any) -> float
Get RMS (root mean square) audio level.

Returns:
   float: RMS level (0-1).
def _get_simulated_data(self: Any) -> List[float]
Generate simulated audio data for demonstration.

Returns:
   List[float]: Simulated audio data.

Global Functions

def get_audio_system() -> OpenALAudioSystem

Get global audio system instance.

def initialize_audio(max_sources: int = 32) -> bool

Initialize global audio system.

def cleanup_audio() -> Any

Clean up global audio system.

Back to Backend Module