Browser Compatibility
Waveform Playlist uses modern web APIs including Web Audio API, AudioWorklets, and OffscreenCanvas. Understanding browser support and known issues helps you build robust applications.Web Audio API Support
The library requires Web Audio API for audio playback and effects:- Chrome/Edge: Full support (Chrome 35+, Edge 79+)
- Firefox: Full support (Firefox 25+)
- Safari: Full support (Safari 14.1+, iOS Safari 14.5+)
- Opera: Full support (Opera 22+)
No polyfills are required for modern browsers (released after 2020).
AudioContext Initialization
All browsers require user interaction before playing audio:play(), but you may see console warnings if AudioContext is suspended.
Firefox Compatibility
AudioListener Issue
Firefox’sAudioListener implementation differs from Chrome/Safari, causing errors when using native AudioContext:
Context class which wraps standardized-audio-context:
Why standardized-audio-context?
Why standardized-audio-context?
The standardized-audio-context package normalizes browser differences in Web Audio API implementations. Tone.js uses it internally, so using Tone’s
Context class ensures compatibility.Affected APIs:AudioListener(Firefox)AudioWorkletNode(Firefox parameter handling)- Various
AudioParamimplementations
AudioWorkletNode Firefox Issue
Firefox throws errors when creatingAudioWorkletNode with native AudioContext:
Context:
Firefox Testing
Always test audio features in Firefox:Safari Compatibility
Safari AudioContext Latency
Safari has ~2 second latency when callingTone.start() redundantly:
Tone.start() once after user interaction:
TonePlayout.init().
Safari OffscreenCanvas Support
OffscreenCanvas is fully supported in Safari 16.4+ (March 2023):- Desktop Safari: 16.4+
- iOS Safari: 16.4+
Safari AudioWorklet Support
AudioWorklets are fully supported in Safari 14.1+ (April 2021):- Desktop Safari: 14.1+
- iOS Safari: 14.5+
AudioWorklet Browser Support
AudioWorklets are required for recording and advanced audio processing:- Chrome: 66+ (April 2018)
- Edge: 79+ (January 2020)
- Firefox: 76+ (May 2020)
- Safari: 14.1+ (April 2021)
- iOS Safari: 14.5+ (April 2021)
Feature Detection
OffscreenCanvas Browser Support
OffscreenCanvas enables web worker rendering for spectrograms:- Chrome: 69+ (September 2018)
- Edge: 79+ (January 2020)
- Firefox: 105+ (September 2022)
- Safari: 16.4+ (March 2023)
- iOS Safari: 16.4+ (March 2023)
Graceful Degradation
The library falls back to main-thread rendering when OffscreenCanvas is unavailable:WebAssembly (Future)
The library does not currently use WebAssembly, but may in the future for:- Audio codec decoding (FLAC, Opus)
- High-performance DSP (pitch detection, beat detection)
- Spectrogram generation
- Chrome: 57+ (March 2017)
- Edge: 16+ (September 2017)
- Firefox: 52+ (March 2017)
- Safari: 11+ (September 2017)
Mobile Considerations
iOS Safari
- AudioContext: Requires user interaction to resume
- Memory limits: 2GB on iPhone 12, 4GB on iPhone 13 Pro
- Background audio: Stops when tab is backgrounded (no workaround)
- OffscreenCanvas: Requires iOS 16.4+ (March 2023)
Android Chrome
- AudioContext: Same user interaction requirement
- Memory limits: Varies by device (2-8GB)
- Background audio: Continues in background (use Media Session API)
- Performance: ~50% slower than desktop for spectrogram generation
Testing Across Browsers
Use Playwright for automated cross-browser testing:Known Browser Bugs
Chrome: Ghost Ticks (Tone.js #1419)
After stop/start cycles,Clock._lastUpdate is stale, causing ghost ticks that trigger schedule callbacks at past positions.
Workaround: Advance _lastUpdate after transport.start():
TonePlayout.play().
Upstream: Tone.js #1419
Firefox: AudioListener Parameter Error
Described above. Use Tone.jsContext instead of native AudioContext.
Upstream: Tone.js #681
Safari: Tone.start() Latency
Described above. CallTone.start() only once.
Workaround: Implemented in library’s TonePlayout.init().
Browser Support Matrix
| Feature | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|
| Web Audio API | ✅ 35+ | ✅ 25+ | ✅ 14.1+ | ✅ 79+ |
| AudioWorklet | ✅ 66+ | ✅ 76+ | ✅ 14.1+ | ✅ 79+ |
| OffscreenCanvas | ✅ 69+ | ✅ 105+ | ✅ 16.4+ | ✅ 79+ |
| MediaRecorder | ✅ 49+ | ✅ 25+ | ✅ 14.1+ | ✅ 79+ |
| AudioContext.suspend | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| playbackRate (pitch) | ✅ Yes | ✅ Yes | ✅ 15+ | ✅ Yes |
Recommended Minimum Versions
For full feature support:- Chrome: 105+ (all features including OffscreenCanvas in workers)
- Firefox: 105+ (OffscreenCanvas support added)
- Safari: 16.4+ (OffscreenCanvas support added)
- Edge: 105+ (follows Chromium)
- Chrome: 66+
- Firefox: 76+
- Safari: 14.1+
- Edge: 79+
User Agent Detection
Avoid user agent sniffing. Use feature detection instead:Reporting Browser Issues
When filing issues:- Specify browser version: Chrome 120.0.6099.129 (not just “Chrome”)
- Include OS: macOS 14.1, Windows 11, iOS 17.2, etc.
- Test in other browsers: Is it browser-specific or a library bug?
- Check console: Include full error messages and stack traces
- Minimal reproduction: Provide CodeSandbox or GitHub repo
Future Compatibility
Upcoming Web Audio API features:- AudioContext.setSinkId(): Output device selection (Chrome 110+)
- AudioWorklet in SharedWorker: Share audio processing across tabs
- WebCodecs: Hardware-accelerated audio encoding/decoding