SDL: docs: Add notes about Emscripten audio quirks.

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/ | 41 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/docs/ b/docs/
index 7e9880b0879d..5f8c277863f3 100644
--- a/docs/
+++ b/docs/
@@ -1,5 +1,42 @@
+# 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
+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
+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
+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.