zentap/docs/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/
    ├── 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/ 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. 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

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

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

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

🎯 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.