zentap/SOUND.md

ZenTap Sound Implementation Guide

This document explains how to add audio files to the ZenTap game and integrate them with the existing audio system.

📁 File Structure

All audio files should be placed in the assets/audio/ directory:

assets/
└── audio/
    ├── bubble_pop.wav          # Primary bubble pop sound
    ├── bubble_pop_alt.wav      # Alternative bubble pop sound
    ├── ambient_background.mp3  # Main background music
    ├── zen_mode_background.mp3 # Zen mode ambient music
    └── ui_click.wav           # UI button click sound (optional)

🎵 Required Audio Files

Sound Effects (WAV format recommended)

File Name	Purpose	Duration	Description
bubble_pop.wav	Primary bubble pop sound	0.1-0.3s	Satisfying pop sound when bubbles are tapped
bubble_pop_alt.wav	Alternative pop sound	0.1-0.3s	Variation for audio diversity (optional)
ui_click.wav	UI interaction	0.05-0.1s	Button press feedback (optional)

Background Music (MP3 format recommended)

File Name	Purpose	Duration	Description
ambient_background.mp3	Play mode background	2-5 minutes	Calm, looping ambient music for gameplay
zen_mode_background.mp3	Zen mode background	2-5 minutes	Even more relaxing track for zen mode

📋 Audio Specifications

Sound Effects

• Format: WAV (uncompressed)
• Sample Rate: 44.1 kHz
• Bit Depth: 16-bit
• Channels: Mono or Stereo
• Volume: Normalized to -6dB peak
• Length: Short and punchy (0.1-0.3 seconds)

Background Music

• Format: MP3 (compressed)
• Bitrate: 128-192 kbps
• Sample Rate: 44.1 kHz
• Channels: Stereo
• Length: 2-5 minutes with seamless loop points
• Volume: Normalized to -12dB peak (quieter than SFX)

🔧 Integration Steps

1. Add Audio Files

Place your audio files in the assets/audio/ directory with the exact filenames listed above.

2. Update pubspec.yaml

The pubspec.yaml file already includes the audio assets:

flutter:
  assets:
    - assets/audio/

3. Update AudioManager

Modify lib/game/audio/audio_manager.dart to load the actual files:

// Replace the placeholder methods with actual file loading:

Future<void> initialize() async {
  try {
    // Load background music
    await _backgroundPlayer.setAsset('assets/audio/ambient_background.mp3');
    await _backgroundPlayer.setLoopMode(LoopMode.one);
  } catch (e) {
    print('Audio initialization failed: $e');
  }
}

Future<void> playBubblePop() async {
  if (!_soundEnabled) return;
  
  try {
    // Load and play bubble pop sound
    await _effectPlayer.setAsset('assets/audio/bubble_pop.wav');
    await _effectPlayer.play();
    
    // Add haptic feedback
    if (_hapticEnabled) {
      await _playHapticFeedback();
    }
  } catch (e) {
    print('Failed to play bubble pop sound: $e');
  }
}

Future<void> playBackgroundMusic() async {
  if (!_musicEnabled) return;
  
  try {
    // Switch music based on zen mode
    String musicFile = isZenMode 
        ? 'assets/audio/zen_mode_background.mp3'
        : 'assets/audio/ambient_background.mp3';
        
    await _backgroundPlayer.setAsset(musicFile);
    await _backgroundPlayer.play();
  } catch (e) {
    print('Failed to play background music: $e');
  }
}

4. Test Audio Integration

After adding files and updating the code:

flutter pub get
flutter run

🎨 Audio Design Guidelines

Bubble Pop Sounds

• Style: Soft, satisfying "pop" or "bubble burst"
• Frequency: Mid-range frequencies (500Hz-2kHz)
• Attack: Quick attack, smooth decay
• References: Soap bubble popping, cork popping (softened)

Background Music

• Genre: Ambient, meditative, new age
• Tempo: Slow (60-80 BPM)
• Instruments: Soft pads, bells, nature sounds, gentle piano
• Mood: Calming, peaceful, stress-relieving
• References: Spa music, meditation apps, yoga soundtracks

🔍 Troubleshooting

Common Issues

1. File Not Found Errors

   • Ensure files are placed in assets/audio/ exactly as named
   • Run flutter pub get after adding files
   • Check that pubspec.yaml includes the assets section

2. Audio Not Playing

   • Verify device volume is up
   • Check if audio is muted in game settings
   • Test with simple WAV files first

3. Performance Issues

   • Keep sound effects under 500KB
   • Use compressed MP3 for background music
   • Avoid too many simultaneous audio streams

Testing Commands

# Clean and rebuild
flutter clean
flutter pub get
flutter run

# Check for audio file issues
flutter analyze

📱 Platform Considerations

• Android: All formats supported
• iOS: Ensure MP3 and WAV compatibility
• Web: Use MP3 for broader browser support
• Desktop: Full format support

🎯 Future Enhancements

• Multiple bubble pop sound variations
• Dynamic music layers based on gameplay
• Sound effect randomization for variety
• Volume sliders for SFX and music separately
• Sound preference persistence

---

Note: Current implementation uses system sounds as placeholders. Follow this guide to replace them with custom audio files for the complete ZenTap experience.