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:

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:

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

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

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

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

Stop Animals (Leave Farm):

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

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

Zombie Death:

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

Player Hurt:

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

Integration Example:

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

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

Farm Wind:

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

Night Crickets:

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

Stop All Ambient:

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

Auto-switching Example:

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

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

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

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

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 🎙️⚡