From 0ddec7e4211010ece8f5dc7fd4f96db480b95bb7 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 28 Oct 2022 16:07:30 -0400
Subject: [PATCH] docs: Add notes about Emscripten audio quirks.
Fixes #6385.
---
docs/README-emscripten.md | 41 +++++++++++++++++++++++++++++++++++++--
1 file changed, 39 insertions(+), 2 deletions(-)
diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md
index 7e9880b0879d..5f8c277863f3 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.