Elmar Kresse
18d14b097d
All checks were successful
Build and Push Docker Image / docker (push) Successful in 9s
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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
|