# Sound Effects Implementation

## Overview
This document describes the sound effects system implemented in the SDL C++ Tetris project, ported from the JavaScript version.

## Sound Effects Implemented

### 1. Line Clear Sounds
- **Basic Line Clear**: `clear_line.wav` - Plays for all line clears (1-4 lines)
- **Voice Feedback**: Plays after the basic sound with a slight delay

### 2. Voice Lines by Line Count

#### Single Line Clear
- No specific voice lines (only basic clear sound plays)

#### Double Line Clear (2 lines)
- `nice_combo.mp3` - "Nice combo"
- `you_fire.mp3` - "You're on fire"  
- `well_played.mp3` - "Well played"
- `keep_that_ryhtm.mp3` - "Keep that rhythm" (note: typo preserved from original)

#### Triple Line Clear (3 lines)
- `great_move.mp3` - "Great move"
- `smooth_clear.mp3` - "Smooth clear"
- `impressive.mp3` - "Impressive"
- `triple_strike.mp3` - "Triple strike"

#### Tetris (4 lines)
- `amazing.mp3` - "Amazing"
- `you_re_unstoppable.mp3` - "You're unstoppable"
- `boom_tetris.mp3` - "Boom! Tetris!"
- `wonderful.mp3` - "Wonderful"

### 3. Level Up Sound
- `lets_go.mp3` - "Let's go" - Plays when the player advances to a new level

## Implementation Details

### Core Classes
1. **SoundEffect**: Handles individual sound file loading and playback
   - Supports both WAV and MP3 formats
   - Uses SDL3 audio streams for playback
   - Volume control per sound effect

2. **SoundEffectManager**: Manages all sound effects
   - Singleton pattern for global access
   - Random selection from sound groups
   - Master volume and enable/disable controls

### Audio Pipeline
1. **Loading**: Sound files are loaded during game initialization
   - WAV files use SDL's native loading
   - MP3 files use Windows Media Foundation (Windows only)
   - All audio is converted to 16-bit stereo 44.1kHz

2. **Playback**: Uses SDL3 audio streams
   - Each sound effect can be played independently
   - Volume mixing with master volume control
   - Non-blocking playback for game responsiveness

### Integration with Game Logic
- **Line Clear Callback**: Game class triggers sound effects when lines are cleared
- **Level Up Callback**: Triggered when player advances levels
- **Random Selection**: Multiple voice lines for same event are randomly selected

### Controls
- **M Key**: Toggle background music on/off
- **S Key**: Toggle sound effects on/off
- Settings popup shows current status of both music and sound effects

### JavaScript Compatibility
The implementation matches the JavaScript version exactly:
- Same sound files used
- Same triggering conditions (line counts, level ups)
- Same random selection behavior for voice lines
- Same volume levels and mixing

## Audio Files Structure
```
assets/music/
├── clear_line.wav              # Basic line clear sound
├── nice_combo.mp3              # Double line voice
├── you_fire.mp3                # Double line voice
├── well_played.mp3             # Double line voice
├── keep_that_ryhtm.mp3         # Double line voice (typo preserved)
├── great_move.mp3              # Triple line voice
├── smooth_clear.mp3            # Triple line voice
├── impressive.mp3              # Triple line voice
├── triple_strike.mp3           # Triple line voice
├── amazing.mp3                 # Tetris voice
├── you_re_unstoppable.mp3      # Tetris voice
├── boom_tetris.mp3             # Tetris voice
├── wonderful.mp3               # Tetris voice
└── lets_go.mp3                 # Level up sound
```

## Technical Notes

### Platform Support
- **Windows**: Full MP3 support via Windows Media Foundation
- **Other platforms**: WAV support only (MP3 requires additional libraries)

### Performance
- All sounds are pre-loaded during initialization
- Minimal CPU overhead during gameplay
- SDL3 handles audio mixing and buffering

### Memory Usage
- Sound effects are kept in memory for instant playback
- Total memory usage approximately 50-100MB for all effects
- Memory is freed on application shutdown

## Future Enhancements
- Add sound effects for piece placement/movement
- Implement positional audio for stereo effects
- Add configurable volume levels per sound type
- Support for additional audio formats (OGG, FLAC)