Audio (sound, music) on the web, sound API improvements (arbitrary channels, float frequency etc.)

michalis · May 15, 2026, 7:18am

We have implemented audio playback on the web. Underneath we use WebAudio API but you don’t really need to know anything about it — just use Castle Game Engine sound API and components and everything will work on the web.

Try these examples (links below lead to ready builds — they should work out-of-the-box in your browser):

Platformer game (Source code)
Play Sounds (Source code)

Be sure to test edge-cases, like tweaking pitch/volume at runtime and stopping sound prematurely:)
3D Sound Demo (Source code)

Note to the last example: “mouse look” is not correct yet, the mouse cursor is visible and it can be offscreen. That’s a TODO I plan to address next.

We have documented some important notes about WebAudio here, a short recap:

Audio playback will be in a suspended state when loading the page in modern web browsers. Audio starts in response to user interaction with a page, like clicking any button. You can solve it also by putting your web application inside an iframe with allow="autoplay", which is done e.g. by wrapper generated for HTML games on itch.io.
OggVorbis and other formats support relies on the sound decoding support on the browser side. The exception is WAV format support, which we decode on the engine side.

We also did a few improvements around the sound formats API, which benefits all platforms by improving our cross-platform API.

The old TSoundDataFormat enum (with 4 values: mono 8-bit, stereo 8-bit, mono 16-bit, stereo 16-bit) is now gone. It was needlessly limiting us to 4 arbitrary combinations of channels/format.
We expose new property TCastleSound.Channels, as Cardinal. This can express sound files with more than 2 channels, like Quadraphonic. Already playable by some backends, like FMOD and new WebAudio. Our OpenAL could also play them in the future, see extensions to provide surround sound buffer formats.
We have an internal sound sample format (not exposed by public API), which describes just formats we decode on the engine side right now. It’s right now just pcm 8-bit (unsigned) or pcm 16-bit (signed) but can be easily extended. Moreover, it is now only used when we decode on the engine side — because some backends (FMOD and WebAudio) are capable of decompressing + playing without passing through our engine, so are not limited to these formats. E.g. FMOD can also use float sound data.
Sound frequency in TCastleSound.Frequency type changed from Cardinal to Single. This again matches better full FMOD and WebAudio backends capabilities. Prefer to express it as TSoundFrequency type, in case in the future we need to upgrade this to Double.
We tested and documented that some backends (again FMOD and WebAudio) support more sound formats (like mp3 and flac).