[BREAKING] Remove HTMLAudioElement fallback from sound system

[willeastcott]

Summary

The engine used to ship a parallel HTMLAudioElement-based implementation of its sound system for browsers without Web Audio API support, gated by hasAudioContext(). Every browser the engine targets (Chrome 10+, Firefox 25+, Safari 6+, Edge 12+) has had Web Audio for years, so the fallback was dead code that only ever covered IE — which the engine no longer supports.

This PR removes the fallback and all the branching / duplicated prototype definitions that existed to support it.

Changes

• Deleted src/platform/sound/capabilities.js (existed solely to gate the fallback).
• SoundInstance: flattened the constructor to the Web Audio branch and removed the ~230-line Object.assign(SoundInstance.prototype, …) override block (duplicate play/pause/resume/stop/setExternalNodes/clearExternalNodes/getExternalNodes/_createSource/_onLoadedMetadata/_onTimeUpdate/_onManagerDestroy) and the redefined volume / pitch / sound / currentTime accessors.
• SoundInstance3d: removed the fallOff JS distance-function fallback and the redefined position / maxDistance / refDistance / rollOffFactor / distanceModel accessors.
• AudioHandler: removed the IE detection IIFE and the new Audio() + canplaythrough branch in _createSound; now uses Web Audio only.
• Sound: removed the public audio property; constructor now accepts only an AudioBuffer.
• SoundComponentSystem.context: no longer emits the "Audio context is not supported" warning — it just returns this.manager.context, which already returns null if no AudioContext/webkitAudioContext is available.

webkitAudioContext handling in SoundManager is intentionally left alone.

Net: +80 / -523 lines across 6 files.

Public API changes (breaking)

Sound.audio is removed.

Before

// A Sound could wrap an HTMLAudioElement if Web Audio wasn't available
const sound = new pc.Sound(audioElement);
sound.audio; // HTMLAudioElement

After

// Sound wraps an AudioBuffer only
const sound = new pc.Sound(audioBuffer);
sound.buffer; // AudioBuffer

SoundComponentSystem#context no longer logs a warning or returns null on the theoretical "no Web Audio" browser. It now returns the underlying SoundManager.context, which was already null in the edge case where neither AudioContext nor webkitAudioContext exist. Behaviour is effectively unchanged on every supported browser.

Test plan

• npm run lint — clean
• npm run build:types — succeeds; verified Sound.audio, HTMLAudioElement, and hasAudioContext no longer appear in build/playcanvas.d.ts
• npm test — 1640 passing, 0 failing
• Manual smoke: run the sound-* examples and confirm 2D / 3D playback still works

[Copilot]

Pull request overview

This PR removes the legacy HTMLAudioElement-based sound fallback path and simplifies the engine’s sound stack to rely solely on Web Audio, aligning implementation with the project’s supported browser set.

Changes:

• Removed hasAudioContext() capability gating (and deleted src/platform/sound/capabilities.js).
• Flattened SoundInstance / SoundInstance3d to Web Audio-only implementations by deleting the fallback prototype overrides and distance falloff JS emulation.
• Updated AudioHandler, Sound, and SoundComponentSystem to remove HTMLAudioElement support and associated branching.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/platform/sound/sound.js	Sound now wraps an AudioBuffer only; removed audio property and simplified duration.
src/platform/sound/instance3d.js	Removed non-WebAudio 3D falloff/path and capability checks; simplified imports.
src/platform/sound/instance.js	Removed non-WebAudio fallback implementation and capability gating; constructor and lifecycle now assume Web Audio.
src/platform/sound/capabilities.js	Deleted Web Audio capability helper (no longer used).
src/framework/handlers/audio.js	Removed IE/HTMLAudioElement loading branch; always decodes into AudioBuffer.
src/framework/components/sound/system.js	context accessor no longer warns/branches on capability; returns manager.context.

Comments suppressed due to low confidence (2)

src/platform/sound/sound.js:15

• Sound is now constructed with a required AudioBuffer, but the buffer field is still documented as AudioBuffer|undefined. If buffer is no longer optional, consider updating the field JSDoc to AudioBuffer to keep generated typings and docs consistent with the new API.

    /**
     * Contains the decoded audio data.
     *
     * @type {AudioBuffer|undefined}
     */
    buffer;

src/platform/sound/instance.js:90

• The source field is initialized to null, but the JSDoc annotates it as {AudioBufferSourceNode} (non-null). This likely flows into generated typings; update the type to include null (or make the field non-nullable by initializing it to an actual node).

    /**
     * Gets the source that plays the sound resource. Source is only available after calling play.
     *
     * @type {AudioBufferSourceNode}
     */
    source = null;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mvaligursky]

Nice!