diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md index 7e9880b08..5f8c27786 100644 --- a/docs/README-emscripten.md +++ b/docs/README-emscripten.md @@ -1,5 +1,42 @@ -Emscripten -================================================================================ +# Emscripten + +(This documentation is not very robust; we will update and expand this later.) + +## A quick note about audio + +Modern web browsers will not permit web pages to produce sound before the +user has interacted with them; this is for several reasons, not the least +of which being that no one likes when a random browser tab suddenly starts +making noise and the user has to scramble to figure out which and silence +it. + +To solve this, most browsers will refuse to let a web app use the audio +subsystem at all before the user has interacted with (clicked on) the page +in a meaningful way. SDL-based apps also have to deal with this problem; if +the user hasn't interacted with the page, SDL_OpenAudioDevice will fail. + +There are two reasonable ways to deal with this: if you are writing some +sort of media player thing, where the user expects there to be a volume +control when you mouseover the canvas, just default that control to a muted +state; if the user clicks on the control to unmute it, on this first click, +open the audio device. This allows the media to play at start, the user can +reasonably opt-in to listening, and you never get access denied to the audio +device. + +Many games do not have this sort of UI, and are more rigid about starting +audio along with everything else at the start of the process. For these, your +best bet is to write a little Javascript that puts up a "Click here to play!" +UI, and upon the user clicking, remove that UI and then call the Emscripten +app's main() function. As far as the application knows, the audio device was +available to be opened as soon as the program started, and since this magic +happens in a little Javascript, you don't have to change your C/C++ code at +all to make it happen. + +Please see the discussion at https://github.com/libsdl-org/SDL/issues/6385 +for some Javascript code to steal for this approach. + + +## Building SDL/emscripten SDL currently requires at least Emscripten 2.0.32 to build. Newer versions are likely to work, as well.