audio.py

Audio System for LunaEngine - OpenAL backend with Pygame fallback

This module provides a unified audio interface with the following features:
- OpenAL backend with Pygame fallback for compatibility
- Sound loading and management by name
- Automatic channel allocation or explicit channel selection
- Smooth volume/pitch transitions
- Stereo panning support
- Resource pooling and management

Author: [Your Name]
Version: 1.0.0

class AudioError

Description

Exception raised for audio-related errors.

Methods

No methods defined.

class AudioState

Description

Audio playback states.

Attributes
STOPPED: Any = 'stopped'
PLAYING: Any = 'playing'
PAUSED: Any = 'paused'
FADING_IN: Any = 'fading_in'
FADING_OUT: Any = 'fading_out'
Methods

No methods defined.

class AudioEvent

Description

Audio events.

Attributes
PLAYBACK_STARTED: Any = 'playback_started'
PLAYBACK_STOPPED: Any = 'playback_stopped'
PLAYBACK_PAUSED: Any = 'playback_paused'
PLAYBACK_RESUMED: Any = 'playback_resumed'
PLAYBACK_COMPLETED: Any = 'playback_completed'
FADE_COMPLETE: Any = 'fade_complete'
LOOP: Any = 'loop'
Methods

No methods defined.

class SoundInfo

Description

Information about a loaded sound.

Attributes:
   name (str): Name of the sound
   filepath (str): Path to the audio file
   duration (float): Duration in seconds
   channels (int): Number of audio channels
   sample_rate (int): Sample rate in Hz
   loaded_time (float): When the sound was loaded

Methods
def __init__(self: Any, name: str, filepath: str, duration: float = 0.0, channels: int = 2, sample_rate: int = 44100) -> Any
No documentation
def __repr__(self: Any) -> str
No documentation

class AudioChannel

Description

Audio channel for playback control.

Each channel can play one sound at a time with individual volume,
pitch, and pan controls.

Args:
   channel_id (int): Unique identifier for this channel
   audio_system: Reference to the parent audio system

Methods
def __init__(self: Any, channel_id: int, audio_system: 'AudioSystem') -> Any
No documentation
def play(self: Any, sound_name: str, loop: bool = False) -> bool
Play a sound on this channel.

Args:
   sound_name (str): Name of the sound to play
   loop (bool): Whether to loop the sound
   
Returns:
   bool: True if playback started successfully
def set_volume(self: Any, volume: float, duration: float = 0.0) -> Any
Set channel volume with optional fade.

Args:
   volume (float): Target volume (0.0 to 1.0)
   duration (float): Fade duration in seconds
def _start_volume_transition(self: Any, target_volume: float, duration: float) -> Any
Start smooth volume transition.
def _transition_volume(self: Any, start: float, end: float, duration: float) -> Any
Smoothly transition volume.
def set_pitch(self: Any, pitch: float, duration: float = 0.0) -> Any
Set playback pitch.

Args:
   pitch (float): Pitch multiplier (0.1 to 4.0)
   duration (float): Transition duration in seconds (OpenAL only)
def set_pan(self: Any, pan: float) -> Any
Set stereo panning.

Args:
   pan (float): -1.0 (left) to 1.0 (right)
def _update_pygame_volume(self: Any) -> Any
Update pygame channel volume with panning.
def pause(self: Any) -> Any
Pause playback.
def resume(self: Any) -> Any
Resume playback.
def stop(self: Any) -> Any
Stop playback.
def is_playing(self: Any) -> bool
Check if channel is playing.
def is_paused(self: Any) -> bool
Check if channel is paused.
def get_playback_position(self: Any) -> float
Get current playback position in seconds.
def cleanup(self: Any) -> Any
Clean up channel resources.

class AudioSystem

Description

Main audio system with sound management and channel allocation.

Features:
- Load sounds by name and store for reuse
- Automatic channel allocation or explicit channel selection
- Resource management and cleanup
- OpenAL backend with Pygame fallback

Args:
   num_channels (int): Maximum number of concurrent audio channels
   use_openal (bool): Whether to use OpenAL backend

Methods
def __init__(self: Any, num_channels: int = 16, use_openal: bool = None) -> Any
No documentation
def _init_openal(self: Any) -> Any
Initialize OpenAL backend.
def _init_pygame(self: Any) -> Any
Initialize Pygame mixer backend.
def load_sound(self: Any, name: str, filepath: str) -> bool
Load a sound file and store it by name.

Args:
   name (str): Name to assign to the sound
   filepath (str): Path to the audio file
   
Returns:
   bool: True if sound was loaded successfully

Raises:
   FileNotFoundError: If the sound file doesn't exist
   AudioError: If sound loading fails
def _estimate_duration(self: Any, filepath: str) -> float
Estimate audio file duration.
def get_sound_info(self: Any, name: str) -> Optional[SoundInfo]
Get information about a loaded sound.
def get_sound_pygame(self: Any, name: str) -> Optional[pygame.mixer.Sound]
Get Pygame Sound object for a loaded sound.
def play(self: Any, sound_name: str, channel: Optional[int] = None, volume: float = None, pitch: float = 1.0, pan: float = 0.0, loop: bool = False) -> Optional[AudioChannel]
Play a sound by name.

Args:
   sound_name (str): Name of the sound to play
   channel (int, optional): Specific channel to use. If None,
                           uses first available channel
   volume (float, optional): Volume (0.0-1.0). Uses SFX volume if None
   pitch (float): Pitch multiplier
   pan (float): Stereo pan (-1.0 to 1.0)
   loop (bool): Whether to loop the sound
   
Returns:
   Optional[AudioChannel]: Channel playing the sound, or None if failed
def play_music(self: Any, sound_name: str, volume: float = None, pitch: float = 1.0, loop: bool = True, fade_in: float = 0.0) -> Optional[AudioChannel]
Play background music (uses channel 0).

Args:
   sound_name (str): Name of the music sound
   volume (float, optional): Volume. Uses music volume if None
   pitch (float): Pitch multiplier
   loop (bool): Whether to loop
   fade_in (float): Fade-in duration in seconds
   
Returns:
   Optional[AudioChannel]: Music channel, or None if failed
def stop_all(self: Any) -> Any
Stop all audio playback.
def pause_all(self: Any) -> Any
Pause all audio playback.
def resume_all(self: Any) -> Any
Resume all paused audio.
def set_master_volume(self: Any, volume: float) -> Any
Set master volume for all audio.
def set_music_volume(self: Any, volume: float) -> Any
Set music volume.
def set_sfx_volume(self: Any, volume: float) -> Any
Set sound effects volume.
def get_channel_info(self: Any) -> List[Dict]
Get information about all channels.
def unload_sound(self: Any, name: str, force: bool = False) -> bool
Unload a sound from memory.

Args:
   name (str): Name of the sound to unload
   force (bool): Force unload even if sound is in use
   
Returns:
   bool: True if sound was unloaded
def unload_unused_sounds(self: Any, max_age: float = 300.0) -> Any
Unload sounds that haven't been used for a while.

Args:
   max_age (float): Maximum age in seconds
def update(self: Any) -> Any
Update audio system (call periodically).
def cleanup(self: Any) -> Any
Clean up all audio resources.
Back to Core Module