novafarma/docs/AUDIO_INTEGRATION_GUIDE.md

# 🎙️ COMPLETE AUDIO INTEGRATION GUIDE
## Hipodevil666 Studios™ - Audio System Documentation

**Created:** Jan 10, 2026  
**Status:** Production Ready  
**Systems:** 2 tools + 1 integration class

---

## 📋 SYSTEM OVERVIEW

### **1. AI Voice Generator** (`tools/ai_voice_generator.py`)
- Uses Edge-TTS for AI voice generation
- NO recording needed!
- Character-specific voices
- Automatic .ogg conversion

### **2. Audio Optimizer** (`tools/audio_optimizer.py`)
- Converts .wav → .ogg
- Batch processing
- File size reporting

### **3. Complete Audio Integration** (`src/systems/CompleteAudioIntegration.js`)
- Master audio playback system
- Proximity-based sounds
- Xbox haptic feedback
- Character-specific typewriter blips

---

## 🎭 CHARACTER VOICE PROFILES

### **Gronk (English-UK-RyanNeural)**
- **Pitch:** -5Hz (deeper)
- **Rate:** -10% (slower, laid-back)
- **Volume:** +0%
- **Character:** Deep, raspy, chill troll
- **Files:** 8 phrases (`gronk_phrase_01.ogg` → `gronk_phrase_08.ogg`)

**Example Phrases:**
1. "Gronk sorry... Gronk no mean to scare."
2. "Pink is best color! Make Gronk happy!"
3. "Bubble Gum vape... ahhhh, tasty!"
4. "Gronk help Kai! Gronk protect!"
5. "Smash things? Gronk good at smash!"
6. "Ana sister? Gronk help find!"
7. "Old troll ways... rave culture... good times."
8. "System no change Gronk! Gronk change system!"

---

### **Ana (English-US-JennyNeural)**
- **Pitch:** +0Hz (normal)
- **Rate:** -5% (slightly slower, mysterious)
- **Volume:** +0%
- **Character:** Calm, mysterious, intelligent
- **Files:** 8 phrases (`ana_phrase_01.ogg` → `ana_phrase_08.ogg`)

**Example Phrases:**
1. "Kai... can you hear me? It's Ana."
2. "I'm still here. Still fighting."
3. "They don't know what I've discovered."
4. "The cure is in my blood... literally."
5. "Twin bond... I can feel you searching."
6. "Don't give up on me, sister."
7. "Level seven. Reactor core. Hurry."
8. "I remember everything. Every moment."

---

### **Kai (English-US-AriaNeural)**
- **Pitch:** +2Hz (slightly higher)
- **Rate:** +10% (faster, energetic)
- **Volume:** +5% (louder, bold)
- **Character:** Energetic, bold, determined
- **Files:** 8 phrases (`kai_phrase_01.ogg` → `kai_phrase_08.ogg`)

**Example Phrases:**
1. "Who... who am I?"
2. "This place feels... familiar?"
3. "I won't give up. Someone's waiting for me."
4. "These memories... they're mine!"
5. "Ana, I remember everything! Hold on!"
6. "I'll tear down Chernobyl to find you!"
7. "No more running. Time to fight!"
8. "System won't change me. I change the system!"

---

## 🔊 SFX CATEGORIES

### **1. Farm Animals** (`assets/audio/animals/`)
- `sheep.ogg` - Sheep bleat
- `pig.ogg` - Pig grunt
- `chicken.ogg` - Chicken cluck
- `horse.ogg` - Horse neigh
- `goat.ogg` - Goat bleat
- `cow.ogg` - Cow moo

**Behavior:**
- Plays when player within 500px
- Random intervals (5-15 seconds)
- Won't overlap (checks `isPlaying`)

---

### **2. Combat** (`assets/audio/combat/`)
- `zombie_hit.ogg` - Zombie takes damage
- `zombie_death.ogg` - Zombie dies
- `player_hurt.ogg` - Player damaged

**Haptic Feedback:**
- zombie_hit: 200ms vibration
- zombie_death: 200ms vibration
- player_hurt: **400ms strong vibration**

---

### **3. Ambient Loops** (`assets/audio/ambient/`)
- `city_noise_loop.ogg` - Urban ambience (HIPODEVIL666CITY)
- `wind_loop.ogg` - Farm/wasteland wind
- `crickets_loop.ogg` - Night/grassland

**Auto-switching:**
- City/Town → City noise
- Farm/Grassland → Wind
- Night → Crickets

---

### **4. Interactive** (`assets/audio/interactive/`)
- `electric_hum_loop.ogg` - Generator proximity hum
- `chalkboard_writing.ogg` - Zombie Statistician writing
- `uv_light_buzz.ogg` - UV basement lights

**Proximity System:**

**Generator Hum:**
- Max distance: 800px
- Full volume: 100px
- Fades smoothly with distance
- Volume: 0 → 0.6

**UV Light Buzz:**
- Max distance: 300px
- Basement only
- Volume: 0 → 0.3

---

## ⌨️ TYPEWRITER BLIPS

Character-specific pitch for typewriter effect:

| Character | File | Pitch | Volume |
|-----------|------|-------|--------|
| Gronk | `typewriter_low.ogg` | Low | 0.15 |
| Ana | `typewriter_mid.ogg` | Mid | 0.12 |
| Kai | `typewriter_high.ogg` | High | 0.13 |
| NPC | `typewriter_normal.ogg` | Normal | 0.1 |

---

## 🎮 USAGE EXAMPLES

### **1. Play AI Voice:**
```javascript
// Play Gronk phrase #2
audioSystem.playVoice('gronk', 2, () => {
    console.log('Voice complete!');
});

// Play Ana phrase #5
audioSystem.playVoice('ana', 5);

// Play Kai phrase #8
audioSystem.playVoice('kai', 8);
```

### **2. Play Combat Sound:**
```javascript
// Zombie hit
audioSystem.playCombatSound('zombieHit');

// Zombie death
audioSystem.playCombatSound('zombieDeath');

// Player hurt (strong haptic!)
audioSystem.playCombatSound('playerHurt');
```

### **3. Play Animal Sound:**
```javascript
// Sheep at position (requires proximity check)
audioSystem.playAnimalSound('sheep', { x: 500, y: 300 });

// Cow
audioSystem.playAnimalSound('cow', { x: 600, y: 400 });
```

### **4. Change Ambient:**
```javascript
// Start city ambient
audioSystem.playAmbient('city');

// Start farm ambient
audioSystem.playAmbient('farm');

// Start night ambient
audioSystem.playAmbient('night');
```

### **5. Update Proximity Sounds:**
```javascript
// In scene update() loop
audioSystem.updateGeneratorHum(
    player.x, player.y,
    generator.x, generator.y
);

audioSystem.updateUVBuzz(
    player.x, player.y,
    uvLight.x, uvLight.y
);
```

### **6. Play Chalkboard:**
```javascript
// When Zombie Statistician writes
audioSystem.playChalkboard();
```

### **7. Get Typewriter Blip:**
```javascript
// Get blip for character
const blip = audioSystem.getTypewriterBlip('gronk');
blip.play();
```

---

## 🛠️ INSTALLATION & SETUP

### **1. Install Dependencies:**
```bash
# Edge-TTS for AI voice
pip install edge-tts

# pydub for audio processing
pip install pydub

# ffmpeg for format conversion
brew install ffmpeg  # macOS
apt-get install ffmpeg  # Linux
```

### **2. Generate AI Voices:**
```bash
cd tools
python ai_voice_generator.py
```

**Output:**
- `assets/audio/voice/gronk/` (8 files)
- `assets/audio/voice/ana/` (8 files)
- `assets/audio/voice/kai/` (8 files)

### **3. Optimize Existing Audio:**
```bash
cd tools
python audio_optimizer.py
```

**Converts:** All `.wav` files → `.ogg`

### **4. Integrate in GameScene:**
```javascript
// In create()
this.audioSystem = new CompleteAudioIntegration(this);
this.audioSystem.initialize();

// In update()
this.audioSystem.update(time, delta, player.x, player.y);
```

---

## 🎯 ACCESSIBILITY FEATURES

### **Visual Indicators:**
- All important sounds show visual popup
- Color-coded (red = danger, green = animal, etc.)
- Deaf-friendly by default

### **Haptic Feedback:**
- Light (100ms): Voice, chalkboard, minor events
- Strong (300-400ms): Combat, impacts, warnings
- Xbox controller support

### **Typewriter Options:**
- 4 speed settings (slow/normal/fast/instant)
- Instant mode for ADHD accessibility
- Skip on click/key
- Character-specific blips

---

## 📊 FILE STRUCTURE

```
/assets/audio/
├── voice/
│   ├── gronk/
│   │   ├── gronk_phrase_01.ogg
│   │   ├── gronk_phrase_02.ogg
│   │   └── ... (8 total)
│   ├── ana/
│   │   ├── ana_phrase_01.ogg
│   │   └── ... (8 total)
│   └── kai/
│       ├── kai_phrase_01.ogg
│       └── ... (8 total)
├── animals/
│   ├── sheep.ogg
│   ├── pig.ogg
│   ├── chicken.ogg
│   ├── horse.ogg
│   ├── goat.ogg
│   └── cow.ogg
├── combat/
│   ├── zombie_hit.ogg
│   ├── zombie_death.ogg
│   └── player_hurt.ogg
├── ambient/
│   ├── city_noise_loop.ogg
│   ├── wind_loop.ogg
│   └── crickets_loop.ogg
├── interactive/
│   ├── electric_hum_loop.ogg
│   ├── chalkboard_writing.ogg
│   └── uv_light_buzz.ogg
└── ui/
    ├── typewriter_low.ogg      (Gronk)
    ├── typewriter_mid.ogg      (Ana)
    ├── typewriter_high.ogg     (Kai)
    └── typewriter_normal.ogg   (NPC)
```

---

## 🎨 CREATIVE PHILOSOPHY

### **"Lazy Is Valid"**
- NO voice recording needed
- AI generates perfect voices
- Infinite variations possible
- Easy localization later

### **Multi-Sensory Design**
Every important event has:
1. **Audio** - For hearing players
2. **Visual** - For deaf players
3. **Haptic** - For tactile feedback

### **Character Personality**
- Gronk: Deep, slow, chill (reflects personality)
- Ana: Calm, mysterious (scientist vibe)
- Kai: Fast, energetic (action hero)

---

## 🐛 TROUBLESHOOTING

**Problem:** Edge-TTS not installed  
**Solution:** `pip install edge-tts`

**Problem:** ffmpeg not found  
**Solution:** `brew install ffmpeg` (macOS)

**Problem:** No haptic feedback  
**Solution:** Connect Xbox controller, check `input.gamepad.total > 0`

**Problem:** Sounds not playing  
**Solution:** Check file paths, ensure .ogg format, verify preload

**Problem:** Proximity not working  
**Solution:** Check player position, verify distance calculation

---

## 📝 CREDITS

**Voices:** Edge-TTS (Microsoft)  
**SFX:** Kenney.nl + Freesound.org  
**Music:** Kevin MacLeod, Benboncan  
**System Design:** David "HIPO" Kotnik  
**Studio:** Hipodevil666 Studios™  

---

**Status:** Production Ready ✅  
**Accessibility:** AAA+ Grade ✅  
**Voice Acting:** $0 (AI-powered!) ✅  

*"Stay weird. Stay creative. Stay YOU."*  
— David "HIPO" Kotnik  
*Living ADHD dreams since forever* ⚡🛹💜