feat: add procedural Pokemon sound effects and audio settings

[justinjeong5]

Summary

Adds authentic, nostalgic Pokémon sound effects and audio controls to PokeTokenBar, enhancing companion interactions, level-ups, evolutions, and shop transactions with zero external audio assets.

All sound effects are procedurally synthesized in memory (44.1kHz Float32 mono PCM buffers via SoundSynthesizer) using exact note frequencies, durations, envelopes, and dual-voice harmonies of classic Pokémon signatures:

• Companion Tap (.tap): Authentic A-button menu selection pop when clicking the menu bar companion sprite (0.08s).
• Rare Candy Level Up (.levelUp): Nostalgic level-up jingle (F5-C5-F5-C5-D#5-E5-F5) when using Rare Candies without triggering an evolution (0.95s).
• Evolution Fanfare (.evolve): Signature 5-note evolution victory fanfare (E5-B5-A5-D#6-E6) with warm bass harmony when evolving into a higher evolutionary stage (1.2s).
• Shop / Healing Sound (.buy): Globally recognized Pokémon Center healing melody ("Ta-ta-ta-ta-taan!", B5-B5-B5-G#5-E6 lead + bass) when buying items or eggs in the Token Shop (1.05s).
• Shiny Chime (.shiny): Gen 2 sparkle chime when hatching a shiny Pokémon or using a Mint in the Bag (0.85s).
• Catch / Hatch Fanfare (.hatch): Iconic "Gotcha! Pokémon was caught!" fanfare (A5-F5-C5-A#5-A#5-A#5-G5-A#5-A5 lead + counterpoint) when hatching an egg or registering a new species (1.4s).

Key Features & Design Decisions

• Zero Committed Audio Files: Strict compliance with repository policies (CONTRIBUTING.md). No audio files (MP3, WAV, OGG) or binary audio assets are added or committed; audio waveforms are purely calculated and rendered in code.
• Battery & CoreAudio Optimization: The audio engine uses on-demand lazy start and an automatic idle pause timer (~2s after playback completes). This prevents continuous CoreAudio I/O polling and preserves battery life (including connected AirPods/Bluetooth headsets).
• Audio Route Change Resilience: Safely listens for AVAudioEngineConfigurationChange notifications to rebuild audio node graphs when plugging in headphones, connecting AirPods, or waking from system sleep.
• Configurable in Settings: New "Sound Effects" section in Settings with an on/off toggle, volume slider (0–100%), and an instant sound preview button.
• Localization: Full localized text for all sound settings across all 7 supported languages (English, Korean, Japanese, Spanish, French, Portuguese, German).
• Clean Architecture & Testing: Audio player decoupled via PokemonAudioPlaying protocol; hardware audio output gated (canPlayHardwareAudio: false in test environments) so headless CI/test suites run silently without CoreAudio device dependencies.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation
• Other:

UI changes

Before	After
Settings had sections for Difficulty, Menu Bar, Floating Pet, Notifications, Update, and Transfer, but no audio controls. Interacting with Pokémon, shop, or bag was silent.	Added a "Sound Effects" section in Settings with an on/off toggle, a volume slider (0%–100%), and a test preview speaker button. Interacting with companions, using items, evolving, and purchasing in the shop plays retro Pokémon sound effects.

Reviewer Testing Guide (How to Try It Locally)

We've provided two easy, non-destructive ways for reviewers to experience the audio effects locally without affecting personal production save data (~/Library/Application Support/PokeTokenBar remains 100% untouched).

Option 1: Standalone Sound Audition Window (5-Second Quick Check)

Reviewers can listen to all 6 synthesized chimes and inspect their waveforms directly in a lightweight GUI window without opening the menu bar app:

swift scripts/preview-sound.swift

• Click each sound effect button to audition the playback, volume, and notes immediately.

---

Option 2: Full In-App Gameplay QA (Isolated Test Environment)

To test how the sound effects feel inside actual app interactions (tap, item usage, level-up, evolution, shop purchases):

./scripts/launch-qa-sound.sh

This launches a debug instance in the macOS menu bar using an isolated temporary state (~/.poketokenbar-qa-sound) pre-configured with Bulbasaur, 10 Rare Candies, 5 Mints, and 50B Tokens.

Test Action	Where	Expected Sound Effect	Behavior / Feedback
1. Companion Tap	[Home Tab] Click Bulbasaur sprite	.tap (A-button pop)	Crisp, subtle menu selection sound (0.08s). Silent when clicking eggs.
2. Rare Candy (Level Up)	[Bag Tab] Click Use on Rare Candy (1 count)	.levelUp (Level-Up jingle)	Plays nostalgic 7-note jingle (F5-C5-F5-C5-D#5-E5-F5) + +100M XP toast.
3. Rare Candy (Evolution)	[Bag Tab] Click Use on Rare Candy a 2nd time	.evolve (Evolution fanfare)	Pushes XP over 208M threshold -> Switches to Home tab -> Flash animation + 5-note victory fanfare (E5-B5-A5-D#6-E6) into Ivysaur!
4. Mint Usage	[Bag Tab] Click Use on Mint	.shiny (Sparkle chime)	Re-rolls nature with Gen 2 sparkle chime and visual sparkle effect.
5. Token Shop Purchase	[Shop Tab] Buy any item or egg	.buy (Center healing melody)	Iconic Pokémon Center healing melody ("Ta-ta-ta-ta-taan!"). Silent if tokens insufficient.
6. Audio Controls	[Settings Tab] Sound Effects Section	.levelUp	Toggle on/off, adjust volume slider (0%–100%), and test via speaker icon button.
7. Instant Egg Hatch	Run ./scripts/launch-qa-sound.sh --egg	.hatch (Catch fanfare)	Launches an egg with full progress -> Instantly hatches Charmander with triumphant "Gotcha! Pokémon was caught!" fanfare.

Checklist

• swift build and swift test pass locally (1,170 tests passed, 0 failures, 13 skipped; logic core line coverage 93.32% >= 75%)
• PR title and description are written in English
• UI changes are described above (before/after — images optional)
• No copyrighted assets, secrets, or private tooling references are committed (see CONTRIBUTING)
• Tests were added or updated for this change (PokemonAudioPlayerTests.swift, UsageStoreSoundSettingsTests.swift, LocalizationSoundTests.swift)

---

🤖 Generated with Antigravity 2.0 (AGY 2.0)