novafarma/docs/HIPO_AUDIO_USAGE.md

# 🎙️ HIPO AUDIO SYSTEM - USAGE GUIDE
## Quick Start & Integration Examples

**Created:** Jan 10, 2026  
**System:** HIPOAudioSystem.js  
**Studio:** Hipodevil666 Studios™

---

## ⚡ QUICK START

### **1. Initialize in GameScene:**

```javascript
import HIPOAudioSystem from './systems/HIPOAudioSystem.js';

class GameScene extends Phaser.Scene {
    preload() {
        // Preload audio assets
        this.hipoAudio = new HIPOAudioSystem(this);
        this.hipoAudio.preloadAssets();
    }
    
    create() {
        // Initialize audio
        this.hipoAudio.initialize();
        
        // Start farm animals (if on farm)
        this.hipoAudio.startFarmAnimalSounds();
        
        // Play ambient for location
        this.hipoAudio.playAmbient('city'); // or 'farm', 'night'
    }
    
    update() {
        // Audio system handles itself!
    }
}
```

---

## 🎭 DIALOGUE SYSTEM

### **Standard Typewriter Dialogue:**

```javascript
// Normal NPC dialogue (uses typewriter)
this.hipoAudio.playDialogue(
    "Welcome to HIPODEVIL666CITY!",
    'npc',  // Character for blip sound
    () => {
        console.log('Dialogue complete!');
    }
);
```

### **AI VOICE Dialogue (Uses Edge-TTS):**

```javascript
// Gronk phrase (AI voice + instant text)
this.hipoAudio.playDialogue(
    "[AI_VOICE:gronk:2] Pink is best color! Make Gronk happy!",
    'gronk'
);

// Ana phrase (AI voice)
this.hipoAudio.playDialogue(
    "[AI_VOICE:ana:5] Twin bond... I can feel you searching.",
    'ana'
);

// Kai phrase (AI voice)
this.hipoAudio.playDialogue(
    "[AI_VOICE:kai:7] No more running. Time to fight!",
    'kai'
);
```

### **Mixed Dialogue Sequence:**

```javascript
// NPC intro (typewriter)
this.hipoAudio.playDialogue(
    "You look new here. Let me introduce you.",
    'npc',
    () => {
        // Gronk enters (AI voice!)
        this.hipoAudio.playDialogue(
            "[AI_VOICE:gronk:1] Gronk sorry... Gronk no mean to scare.",
            'gronk',
            () => {
                // Kai responds (AI voice!)
                this.hipoAudio.playDialogue(
                    "[AI_VOICE:kai:3] I won't give up. Someone's waiting for me.",
                    'kai'
                );
            }
        );
    }
);
```

---

## 📋 AI VOICE PHRASE REFERENCE

### **Gronk (Deep, Gritty Troll):**

| # | Tag | Phrase |
|---|-----|--------|
| 1 | `[AI_VOICE:gronk:1]` | "Gronk sorry... Gronk no mean to scare." |
| 2 | `[AI_VOICE:gronk:2]` | "Pink is best color! Make Gronk happy!" |
| 3 | `[AI_VOICE:gronk:3]` | "Bubble Gum vape... ahhhh, tasty!" |
| 4 | `[AI_VOICE:gronk:4]` | "Gronk help Kai! Gronk protect!" |
| 5 | `[AI_VOICE:gronk:5]` | "Smash things? Gronk good at smash!" |
| 6 | `[AI_VOICE:gronk:6]` | "Ana sister? Gronk help find!" |
| 7 | `[AI_VOICE:gronk:7]` | "Old troll ways... rave culture... good times." |
| 8 | `[AI_VOICE:gronk:8]` | "System no change Gronk! Gronk change system!" |

### **Kai (Energetic, Bold Female):**

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

### **Ana (Mysterious, Calm Female):**

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

---

## 🐄 FARM ANIMAL SOUNDS

### **Start Animals (On Farm):**

```javascript
// Start random animal sounds
this.hipoAudio.startFarmAnimalSounds();
```

### **Stop Animals (Leave Farm):**

```javascript
// Stop all animal timers
this.hipoAudio.stopFarmAnimalSounds();
```

**Available Animals:**
- 🐑 Sheep
- 🐷 Pig
- 🐔 Chicken
- 🐴 Horse
- 🐐 Goat
- 🐄 Cow

**Behavior:**
- Random intervals: 5-15 seconds
- Only plays near Kai (proximity check)
- Won't overlap (checks `isPlaying`)

---

## ⚔️ COMBAT SOUNDS

### **Zombie Hit:**

```javascript
// When zombie takes damage
this.hipoAudio.playCombat('hit');
// → Plays zombie_hit.ogg + 200ms haptic
```

### **Zombie Death:**

```javascript
// When zombie dies
this.hipoAudio.playCombat('death');
// → Plays zombie_death.ogg + 200ms haptic
```

### **Player Hurt:**

```javascript
// When Kai takes damage
this.hipoAudio.playCombat('hurt');
// → Plays player_hurt.ogg + 400ms STRONG haptic
```

**Integration Example:**

```javascript
// In your combat system
zombieTakeDamage(zombie, damage) {
    zombie.health -= damage;
    
    if (zombie.health <= 0) {
        this.hipoAudio.playCombat('death'); // Death sound
        zombie.destroy();
    } else {
        this.hipoAudio.playCombat('hit');   // Hit sound
    }
}

playerTakeDamage(amount) {
    this.player.health -= amount;
    this.hipoAudio.playCombat('hurt');      // STRONG haptic!
}
```

---

## 🌃 AMBIENT SOUNDS

### **Noir City (HIPODEVIL666CITY):**

```javascript
// When entering city
this.hipoAudio.playAmbient('city');
// → Plays noir_city_echo.ogg (loop, echo effect)
```

### **Farm Wind:**

```javascript
// When on farm/grassland
this.hipoAudio.playAmbient('farm');
// → Plays wind_loop.ogg
```

### **Night Crickets:**

```javascript
// When night time
this.hipoAudio.playAmbient('night');
// → Plays crickets_loop.ogg
```

### **Stop All Ambient:**

```javascript
// Silence ambient (e.g., entering building)
this.hipoAudio.stopAmbient();
```

**Auto-switching Example:**

```javascript
// In your biome/time system
changeBiome(newBiome) {
    switch(newBiome) {
        case 'HIPODEVIL666CITY':
            this.hipoAudio.playAmbient('city');
            break;
        case 'farm':
            this.hipoAudio.playAmbient('farm');
            break;
        default:
            this.hipoAudio.stopAmbient();
    }
}

setTimeOfDay(time) {
    if (time === 'night') {
        this.hipoAudio.playAmbient('night');
    }
}
```

---

## ⌨️ CHARACTER TYPEWRITER BLIPS

Each character has unique blip pitch:

- **Gronk:** Low pitch (deep troll)
- **Kai:** High pitch (energetic)
- **Ana:** Mid pitch (calm)
- **NPC:** Normal pitch (generic)

**Automatic in Dialogue:**

```javascript
// Gronk dialogue → Low pitch blips
this.hipoAudio.playDialogue("Gronk text here", 'gronk');

// Kai dialogue → High pitch blips
this.hipoAudio.playDialogue("Kai text here", 'kai');

// Ana dialogue → Mid pitch blips
this.hipoAudio.playDialogue("Ana text here", 'ana');

// NPC dialogue → Normal pitch blips
this.hipoAudio.playDialogue("NPC text here", 'npc');
```

---

## 🎮 HAPTIC FEEDBACK

### **Automatic Haptics:**

| Event | Duration | Strength |
|-------|----------|----------|
| AI Voice | 100ms | Light (0.3/0.5) |
| Zombie Hit | 200ms | Strong (0.7/1.0) |
| Zombie Death | 200ms | Strong (0.7/1.0) |
| Player Hurt | 400ms | VERY STRONG (0.7/1.0) |

### **Manual Haptics:**

```javascript
// Light vibration
this.hipoAudio.vibrateLight();

// Strong vibration (300ms default)
this.hipoAudio.vibrateStrong();

// Custom vibration
this.hipoAudio.vibrate(
    500,  // duration (ms)
    0.5,  // weak motor (0-1)
    1.0   // strong motor (0-1)
);
```

---

## 🎯 COMPLETE DEMO EXAMPLE

```javascript
class DemoScene extends Phaser.Scene {
    create() {
        // Initialize audio
        this.hipoAudio = new HIPOAudioSystem(this);
        this.hipoAudio.initialize();
        
        // Start city ambient
        this.hipoAudio.playAmbient('city');
        
        // Start farm animals
        this.hipoAudio.startFarmAnimalSounds();
        
        // Demo dialogue sequence
        this.startDialogueSequence();
    }
    
    startDialogueSequence() {
        // 1. Kai wakes up (AI voice!)
        this.hipoAudio.playDialogue(
            "[AI_VOICE:kai:1] Who... who am I?",
            'kai',
            () => {
                // 2. Kai explores (typewriter)
                this.time.delayedCall(1000, () => {
                    this.hipoAudio.playDialogue(
                        "Everything feels familiar... but I can't remember.",
                        'kai',
                        () => {
                            // 3. Gronk appears (AI voice!)
                            this.time.delayedCall(1000, () => {
                                this.hipoAudio.playDialogue(
                                    "[AI_VOICE:gronk:1] Gronk sorry... Gronk no mean to scare.",
                                    'gronk',
                                    () => {
                                        // 4. Kai responds (AI voice!)
                                        this.time.delayedCall(1000, () => {
                                            this.hipoAudio.playDialogue(
                                                "[AI_VOICE:kai:3] I won't give up. Someone's waiting for me.",
                                                'kai'
                                            );
                                        });
                                    }
                                );
                            });
                        }
                    );
                });
            }
        );
    }
    
    // Combat example
    onZombieAttack() {
        this.hipoAudio.playCombat('hurt');  // Player damaged!
    }
    
    onPlayerAttackZombie(zombie) {
        if (zombie.health <= 0) {
            this.hipoAudio.playCombat('death');
        } else {
            this.hipoAudio.playCombat('hit');
        }
    }
}
```

---

## 📁 REQUIRED FILE STRUCTURE

```
/assets/audio/
├── voice/
│   ├── gronk/ (8 files: gronk_phrase_01.ogg → gronk_phrase_08.ogg)
│   ├── ana/ (8 files: ana_phrase_01.ogg → ana_phrase_08.ogg)
│   └── kai/ (8 files: kai_phrase_01.ogg → kai_phrase_08.ogg)
├── sfx/
│   ├── farming/
│   │   ├── sheep.ogg
│   │   ├── pig.ogg
│   │   ├── chicken.ogg
│   │   ├── horse.ogg
│   │   ├── goat.ogg
│   │   └── cow.ogg
│   └── combat/
│       ├── zombie_hit.ogg
│       ├── zombie_death.ogg
│       └── player_hurt.ogg
├── ambient/
│   ├── noir_city_echo.ogg (HIPODEVIL666CITY ambient!)
│   ├── wind_loop.ogg
│   └── crickets_loop.ogg
└── ui/
    ├── typewriter_low.ogg (Gronk)
    ├── typewriter_mid.ogg (Ana)
    ├── typewriter_high.ogg (Kai)
    └── typewriter_normal.ogg (NPC)
```

---

## 🚀 GENERATING AI VOICES

```bash
cd tools
python ai_voice_generator.py
```

**Generates all 24 AI voice files automatically!**

---

**System:** Ready for Demo! ✅  
**Accessibility:** AAA+ ✅  
**Cost:** $0 (AI-powered!) ✅  

*"Stay weird. Stay creative. Stay YOU."*  
— HIPO 🎙️⚡