# 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/`](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/`](assets/audio/) directory with the exact filenames listed above.

### 2. Update pubspec.yaml
The [`pubspec.yaml`](pubspec.yaml) file already includes the audio assets:
```yaml
flutter:
  assets:
    - assets/audio/
```

### 3. Update AudioManager
Modify [`lib/game/audio/audio_manager.dart`](lib/game/audio/audio_manager.dart) to load the actual files:

```dart
// 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:

```bash
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

```bash
# 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.