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:

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

// Zombie hit
audioSystem.playCombatSound('zombieHit');

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

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

3. Play Animal Sound:

// Sheep at position (requires proximity check)
audioSystem.playAnimalSound('sheep', { x: 500, y: 300 });

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

4. Change Ambient:

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

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

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

5. Update Proximity Sounds:

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

// When Zombie Statistician writes
audioSystem.playChalkboard();

7. Get Typewriter Blip:

// Get blip for character
const blip = audioSystem.getTypewriterBlip('gronk');
blip.play();

---

🛠️ INSTALLATION & SETUP

1. Install Dependencies:

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

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:

cd tools
python audio_optimizer.py

Converts: All .wav files → .ogg

4. Integrate in GameScene:

// 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 ⚡🛹💜