Audio System

The Popcorning Guinea Pig engine provides a comprehensive audio system for playing sounds and music in your games through the ISoundPlayer service.

Overview

The audio system is built around the ISoundPlayer interface, which provides methods for loading and playing audio files. The implementation uses platform-specific audio libraries to ensure optimal performance across different operating systems.

ISoundPlayer Interface

public interface ISoundPlayer
{
    void PlaySound(string soundPath);
    void PlayMusic(string musicPath, bool loop = true);
    void StopMusic();
    void SetMusicVolume(float volume);
    void SetSoundVolume(float volume);
}

Getting the Audio Service

Access the audio system through dependency injection in your game class:

public class MyGame : Game
{
    private readonly ISoundPlayer _soundPlayer;
    
    public MyGame()
    {
        _soundPlayer = GetService<ISoundPlayer>();
    }
}

Playing Sounds

Sound Effects

Play short sound effects for user interactions, game events, and feedback:

// Play a button click sound
_soundPlayer.PlaySound("assets/sounds/button-click.wav");

// Play an explosion sound
_soundPlayer.PlaySound("assets/sounds/explosion.mp3");

Background Music

Play looping background music for your game:

// Start playing background music
_soundPlayer.PlayMusic("assets/music/background.ogg", true);

// Stop the current music
_soundPlayer.StopMusic();

Volume Control

Control the volume of sounds and music independently:

// Set music volume (0.0 to 1.0)
_soundPlayer.SetMusicVolume(0.7f);

// Set sound effects volume (0.0 to 1.0)
_soundPlayer.SetSoundVolume(0.8f);

Supported Audio Formats

The engine supports common audio formats:

• WAV - Uncompressed audio, good for short sound effects
• MP3 - Compressed audio, good for music
• OGG - Open source compressed format, good balance of quality and size
• FLAC - Lossless compression for high-quality audio

Best Practices

File Organization

Organize your audio files in the assets directory:

assets/
├── sounds/          # Short sound effects
│   ├── ui/         # UI interaction sounds
│   ├── sfx/        # Game sound effects
│   └── voice/      # Voice clips
└── music/          # Background music and themes
    ├── menu/       # Menu music
    ├── gameplay/   # In-game music
    └── ambient/    # Ambient sounds

Performance Tips

1. Use appropriate formats: WAV for short sounds, OGG/MP3 for music
2. Preload frequently used sounds: Load sounds at startup to avoid hitches
3. Limit simultaneous sounds: Too many concurrent sounds can impact performance
4. Consider file sizes: Compress music files to reduce memory usage

Volume Guidelines

• Music: Keep background music at 50-70% volume to allow sound effects to be heard
• Sound Effects: UI sounds should be subtle (60-80%), game effects can be louder
• User Control: Always provide volume controls in your game settings

Example Implementation

Here's a complete example of using the audio system in a game:

public class MyGame : Game
{
    private readonly ISoundPlayer _soundPlayer;
    
    public MyGame()
    {
        _soundPlayer = GetService<ISoundPlayer>();
        
        // Set initial volumes
        _soundPlayer.SetMusicVolume(0.6f);
        _soundPlayer.SetSoundVolume(0.8f);
        
        // Start background music
        _soundPlayer.PlayMusic("assets/music/menu-theme.ogg");
    }
    
    private void OnButtonClicked()
    {
        _soundPlayer.PlaySound("assets/sounds/ui/button-click.wav");
    }
    
    private void OnGameStart()
    {
        _soundPlayer.StopMusic();
        _soundPlayer.PlayMusic("assets/music/gameplay-theme.ogg");
    }
    
    private void OnPlayerHit()
    {
        _soundPlayer.PlaySound("assets/sounds/sfx/hit.wav");
    }
}

Integration with Settings

The audio system works seamlessly with the Settings Service to persist user preferences:

public class AudioSettings
{
    public float MusicVolume { get; set; } = 0.7f;
    public float SoundVolume { get; set; } = 0.8f;
    public bool MusicEnabled { get; set; } = true;
    public bool SoundEnabled { get; set; } = true;
}

// Apply settings
public void ApplyAudioSettings(AudioSettings settings)
{
    _soundPlayer.SetMusicVolume(settings.MusicEnabled ? settings.MusicVolume : 0f);
    _soundPlayer.SetSoundVolume(settings.SoundEnabled ? settings.SoundVolume : 0f);
}

Troubleshooting

Common Issues

• No sound playing: Check file paths and ensure audio files exist
• Audio cutting out: Verify file formats are supported
• Performance issues: Reduce number of simultaneous sounds
• Volume not working: Ensure volume values are between 0.0 and 1.0

Platform-Specific Notes

• Windows: Uses DirectSound for optimal performance
• Linux: Uses ALSA/PulseAudio depending on system configuration
• macOS: Uses Core Audio for native integration

The audio system provides a simple yet powerful way to add immersive sound to your Popcorning Guinea Pig games.