# 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/
    ├── source/
    │   ├── bubble_pop.mp3          # Primary bubble pop sound
    │   ├── bubble_pop_alt.mp3      # Alternative bubble pop sound
    │   └── ambient_background.mp3  # Fallback background music
    ├── menu/
    │   ├── menu_default.mp3        # Default theme menu music
    │   ├── menu_spring.mp3         # Spring theme menu music
    │   ├── menu_summer.mp3         # Summer theme menu music
    │   ├── menu_autumn.mp3         # Autumn theme menu music
    │   └── menu_winter.mp3         # Winter theme menu music
    ├── ingame/
    │   ├── ingame_default_001.mp3  # Default theme ingame music
    │   ├── ingame_spring_001.mp3   # Spring theme ingame music
    │   ├── ingame_summer_001.mp3   # Summer theme ingame music
    │   ├── ingame_autumn_001.mp3   # Autumn theme ingame music
    │   ├── ingame_winter_001.mp3   # Winter theme ingame music (track 1)
    │   └── ingame_winter_002.mp3   # Winter theme ingame music (track 2)
    └── compressed/
        ├── bubble_pop.wav          # Compressed bubble pop sound
        ├── bubble_pop_alt.wav      # Compressed alternative pop sound
        └── ambient_background.mp3  # Compressed background music
```

## 🎵 Required Audio Files

### Sound Effects (MP3 format)

| File Name | Purpose | Duration | Description |
|-----------|---------|----------|-------------|
| `source/bubble_pop.mp3` | Primary bubble pop sound | 0.1-0.3s | Satisfying pop sound when bubbles are tapped |
| `source/bubble_pop_alt.mp3` | Alternative pop sound | 0.1-0.3s | Variation for audio diversity |
| `source/ambient_background.mp3` | Fallback background | 2-5 minutes | Legacy background music file |

### Theme-Based Menu Music (MP3 format)

| File Name | Purpose | Duration | Description |
|-----------|---------|----------|-------------|
| `menu/menu_default.mp3` | Default theme menu | 2-5 minutes | Menu music for default/fSociety theme |
| `menu/menu_spring.mp3` | Spring theme menu | 2-5 minutes | Light, fresh menu music for spring |
| `menu/menu_summer.mp3` | Summer theme menu | 2-5 minutes | Warm, bright menu music for summer |
| `menu/menu_autumn.mp3` | Autumn theme menu | 2-5 minutes | Cozy, warm menu music for autumn |
| `menu/menu_winter.mp3` | Winter theme menu | 2-5 minutes | Cool, serene menu music for winter |

### Theme-Based Ingame Music (MP3 format)

| File Name | Purpose | Duration | Description |
|-----------|---------|----------|-------------|
| `ingame/ingame_default_001.mp3` | Default theme gameplay | 3-8 minutes | Gameplay music for default theme |
| `ingame/ingame_spring_001.mp3` | Spring theme gameplay | 3-8 minutes | Fresh, energetic gameplay music |
| `ingame/ingame_summer_001.mp3` | Summer theme gameplay | 3-8 minutes | Upbeat, sunny gameplay music |
| `ingame/ingame_autumn_001.mp3` | Autumn theme gameplay | 3-8 minutes | Contemplative autumn gameplay music |
| `ingame/ingame_winter_001.mp3` | Winter theme gameplay (track 1) | 3-8 minutes | Calm winter gameplay music |
| `ingame/ingame_winter_002.mp3` | Winter theme gameplay (track 2) | 3-8 minutes | Alternative winter gameplay music |

## 📋 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. Audio System Features

The AudioManager now supports:

#### Theme-Based Music System
- **Menu Music**: Automatically selects music based on current seasonal theme
- **Ingame Music**: Random selection from theme-appropriate tracks during gameplay
- **Context Switching**: Different music for menu vs. gameplay contexts

#### Smart Music Management
```dart
// Theme-aware menu music
await AudioManager().playMenuMusic();

// Theme-aware ingame music with random selection
await AudioManager().playIngameMusic();

// Legacy compatibility method
await AudioManager().playBackgroundMusic(); // Falls back to menu music
```

#### Multiple Track Support
The system supports multiple tracks per theme for variety:
```dart
// Example: Winter theme has 2 ingame tracks
static const Map<String, List<String>> _ingameMusicTracks = {
  'winter': ['ingame/ingame_winter_001.mp3', 'ingame/ingame_winter_002.mp3'],
  'spring': ['ingame/ingame_spring_001.mp3'],
  // ... other themes
};
```

#### Automatic Integration
- **Main Menu**: Starts theme-appropriate menu music
- **Game Screen**: Switches to theme-appropriate ingame music
- **Settings**: Updates music when theme is changed
- **Stats Screen**: Returns to menu music

### 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

## 🎯 Recent Enhancements (v1.0.4+)

### ✅ Implemented Features
- **Theme-Based Music System**: Menu and ingame music automatically adapt to seasonal themes
- **Random Track Selection**: Multiple ingame tracks per theme with random selection
- **Context-Aware Audio**: Different music for menu vs. gameplay contexts
- **Smart Music Switching**: Music changes when themes are selected in settings
- **Multi-Track Support**: System supports multiple tracks per theme (winter has 2 tracks)

### 🔄 Future Enhancements
- Multiple bubble pop sound variations per theme
- Dynamic music layers based on gameplay intensity
- Music fade-in/fade-out transitions
- Per-theme volume balancing
- Music crossfading during theme changes
- Seasonal sound effects to match themes

## 🎨 Theme Audio Design Guidelines

### Spring Theme
- **Menu Music**: Light, fresh, awakening sounds
- **Ingame Music**: Gentle, optimistic, growing energy
- **Mood**: Renewal, hope, gentle energy

### Summer Theme
- **Menu Music**: Warm, bright, uplifting
- **Ingame Music**: Energetic but not overwhelming
- **Mood**: Joy, vitality, warmth

### Autumn Theme
- **Menu Music**: Cozy, contemplative, warm
- **Ingame Music**: Reflective, comfortable, grounding
- **Mood**: Reflection, coziness, preparation

### Winter Theme
- **Menu Music**: Serene, crisp, peaceful
- **Ingame Music**: Calm, focused, crystalline clarity
- **Mood**: Tranquility, focus, inner peace

---

**Note**: The theme-based music system is now fully implemented. Replace the placeholder audio files with theme-appropriate music to complete the immersive ZenTap experience.