feat: Integrate Howler.js for audio playback and remove native audio elements

HOWLER_INTEGRATION.md

@@ -0,0 +1,83 @@
+# Howler.js Integration
+
+## Overview
+Successfully integrated [Howler.js](https://www.npmjs.com/package/howler) v2.2.4 for audio playback, replacing the native HTML5 `<audio>` element.
+
+## Changes Made
+
+### 1. **index.html**
+- Added Howler.js CDN script: `https://cdnjs.cloudflare.com/ajax/libs/howler/2.2.4/howler.min.js`
+- Removed the `<audio id="audio">` element (no longer needed)
+
+### 2. **audio.js** (Complete Rewrite)
+Replaced HTML5 Audio API with Howler.js:
+
+#### Key Features:
+- **Sound Management**: Uses `Howl` instances for audio playback
+- **Progress Tracking**: Custom interval-based progress tracking (100ms updates)
+- **Volume Persistence**: Saves volume to localStorage
+- **Sync Support**: Maintains time synchronization with server using playback rate adjustment
+- **Mobile Support**: Includes audio unlock handlers for iOS/Android browsers
+- **Event Handling**: Proper event handlers for load, play, pause, end, and errors
+
+#### Exported Functions:
+- `getSound()` - Returns current Howl instance
+- `loadTrack(url)` - Creates and loads a new track
+- `initAudioUI()` - Initializes Howler settings and volume controls
+- `applySync(startAt, serverNow)` - Syncs playback with server timing
+- `stopAudioPlayback()` - Stops and cleans up audio
+
+### 3. **handlers.js**
+Updated to use new Howler API:
+- Removed `$audio` import
+- Added `loadTrack` and `getSound` imports
+- `handlePlayTrack()`: Uses `loadTrack()` instead of setting `audio.src`
+- `handleControl()`: Uses `sound.pause()`, `sound.play()`, `sound.seek()`, `sound.rate()`
+
+### 4. **dom.js**
+- Removed `export const $audio = el('audio')` (no longer exists in DOM)
+
+### 5. **ui.js**
+- Removed `$audio` import
+- Removed volume slider initialization (now handled in `audio.js`)
+
+## Benefits of Howler.js
+
+1. **Better Browser Compatibility**: Handles audio quirks across different browsers/devices
+2. **Improved Mobile Support**: Better handling of autoplay restrictions on iOS/Android
+3. **Built-in Error Handling**: Automatic retry and fallback mechanisms
+4. **Sprite Support**: Ready for future audio sprite features if needed
+5. **Format Flexibility**: Automatic format selection and fallback
+6. **Memory Management**: Better resource cleanup and management
+7. **Unified API**: Consistent API across all browsers
+
+## Testing Recommendations
+
+1. **Desktop Browsers**: Test on Chrome, Firefox, Safari, Edge
+2. **Mobile Devices**: Test on iOS Safari and Android Chrome (autoplay restrictions)
+3. **Playback Controls**: Verify play, pause, seek, volume work correctly
+4. **Synchronization**: Test multi-client sync with server timing
+5. **Network Conditions**: Test buffering behavior with slow connections
+6. **Tab Switching**: Verify audio behavior when switching tabs
+
+## Configuration Options
+
+The Howler instance is configured with:
+- `html5: true` - Uses HTML5 Audio for streaming (better for large files)
+- `preload: true` - Preloads audio for smooth playback
+- `format: [...]` - Explicitly specifies audio format (detected from filename)
+- Volume persistence via localStorage
+- Automatic format detection based on file extension
+
+### Format Detection
+Since the audio URLs use tokens (e.g., `/audio/t/abc123`) without file extensions, the format is extracted from the track's `file` property and explicitly passed to Howler.js using the `format` configuration option. This ensures proper codec selection for `.opus`, `.mp3`, `.ogg`, `.wav`, `.m4a`, and other formats.
+
+## Future Enhancements
+
+Potential improvements using Howler.js features:
+- Audio sprites for sound effects
+- 3D spatial audio positioning
+- Multiple simultaneous tracks
+- Crossfading between tracks
+- Advanced audio effects
+- Better offline/cache support