emscripten-core · juj · Nov 5, 2025 · Nov 3, 2025 · Nov 3, 2025 · Nov 3, 2025
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -39,6 +39,11 @@ See docs/process.md for more on how version tagging works.
   are used via `--use-port=emdawnwebgpu`. See 4.0.10 release notes for details.
 - A new `CROSS_ORIGIN` setting was added in order to work around issues hosting
   emscripten programs across different origins (#25581)
+- The binary data encoding for `SINGLE_FILE` mode was changed from base64 to
+  directly embed binary data into UTF-8 string. Users who use the `SINGLE_FILE`
+  mode along with a custom HTML file should declare the files to have UTF-8
+  encoding. See `src/settings.js` docs on `SINGLE_FILE`. Use the option
+  `-sSINGLE_FILE_BINARY_ENCODE=0` to fall back to base64 encoding. (#25599)
 
 4.0.17 - 10/17/25
 -----------------

diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst
@@ -2837,6 +2837,9 @@ child-src directive to allow blob:. If you aren't using Content Security
 Policy, or your CSP header doesn't include either script-src or child-src,
 then you can safely ignore this warning.
 
+Note that SINGLE_FILE with binary encoding requires the HTML/JS files to be
+served with UTF-8 encoding. See the details on SINGLE_FILE_BINARY_ENCODE.
+
 Default value: false
 
 .. _single_file_binary_encode:
@@ -2851,6 +2854,20 @@ issues with the binary encoding. (and please let us know of any such issues)
 If no issues arise, this option will permanently become the default in the
 future.
 
+NOTE: Binary encoding requires that the HTML/JS files are served with UTF-8
+encoding, and will not work with the default legacy Windows-1252 encoding
+that browsers might use on Windows. To enable UTF-8 encoding in a
+hand-crafted index.html file, apply any of:
+1. Add `<meta charset="utf-8">` inside the <head> section of HTML, or
+2. Add `<meta http-equiv="content-type" content="text/html; charset=UTF-8" />`` inside <head>, or
+3. Add `<meta http-equiv="content-type" content="application/json; charset=utf-8" />` inside <head>
+(if using -o foo.js with SINGLE_FILE mode to build HTML+JS), or
+4. pass the header `Content-Type: text/html; charset=utf-8` and/or header
+`Content-Type: application/javascript; charset=utf-8` when serving the
+relevant files that contain binary encoded content.
+If none of these are possible, disable binary encoding with
+-sSINGLE_FILE_BINARY_ENCODE=0 to fall back to base64 encoding.
+
 Default value: true
 
 .. _auto_js_libraries:

diff --git a/src/settings.js b/src/settings.js
@@ -1852,6 +1852,9 @@ var WASMFS = false;
 // child-src directive to allow blob:. If you aren't using Content Security
 // Policy, or your CSP header doesn't include either script-src or child-src,
 // then you can safely ignore this warning.
+//
+// Note that SINGLE_FILE with binary encoding requires the HTML/JS files to be
+// served with UTF-8 encoding. See the details on SINGLE_FILE_BINARY_ENCODE.
 // [link]
 var SINGLE_FILE = false;
 
@@ -1861,6 +1864,20 @@ var SINGLE_FILE = false;
 // issues with the binary encoding. (and please let us know of any such issues)
 // If no issues arise, this option will permanently become the default in the
 // future.
+//
+// NOTE: Binary encoding requires that the HTML/JS files are served with UTF-8
+// encoding, and will not work with the default legacy Windows-1252 encoding
+// that browsers might use on Windows. To enable UTF-8 encoding in a
+// hand-crafted index.html file, apply any of:
+// 1. Add `<meta charset="utf-8">` inside the <head> section of HTML, or
+// 2. Add `<meta http-equiv="content-type" content="text/html; charset=UTF-8" />`` inside <head>, or
+// 3. Add `<meta http-equiv="content-type" content="application/json; charset=utf-8" />` inside <head>
+// (if using -o foo.js with SINGLE_FILE mode to build HTML+JS), or
+// 4. pass the header `Content-Type: text/html; charset=utf-8` and/or header
+// `Content-Type: application/javascript; charset=utf-8` when serving the
+// relevant files that contain binary encoded content.
+// If none of these are possible, disable binary encoding with
+// -sSINGLE_FILE_BINARY_ENCODE=0 to fall back to base64 encoding.
 // [link]
 var SINGLE_FILE_BINARY_ENCODE = true;
 

diff --git a/test/test_other.py b/test/test_other.py
@@ -17,6 +17,7 @@
 import select
 import shlex
 import shutil
+import struct
 import subprocess
 import sys
 import tarfile
@@ -89,6 +90,7 @@
 
 from tools import building, cache, response_file, shared, utils, webassembly
 from tools.building import get_building_env
+from tools.link import binary_encode
 from tools.settings import settings
 from tools.shared import (
   CLANG_CC,
@@ -106,7 +108,15 @@
   config,
 )
 from tools.system_libs import DETERMINISTIC_PREFIX
-from tools.utils import MACOS, WINDOWS, delete_file, read_binary, read_file, write_file
+from tools.utils import (
+  MACOS,
+  WINDOWS,
+  delete_file,
+  read_binary,
+  read_file,
+  write_binary,
+  write_file,
+)
 
 emmake = utils.bat_suffix(path_from_root('emmake'))
 emconfig = utils.bat_suffix(path_from_root('em-config'))
@@ -15158,3 +15168,16 @@ def test_linkable_relocatable(self):
     # These setting is due for removal:
     # https://github.com/emscripten-core/emscripten/issues/25262
     self.do_run_in_out_file_test('hello_world.c', cflags=['-Wno-deprecated', '-sLINKABLE', '-sRELOCATABLE'])
+
+  # Tests encoding of all byte pairs for binary encoding in SINGLE_FILE mode.
+  def test_binary_encode(self):
+    # Encode values 0 .. 65535 into test data
+    test_data = bytearray(struct.pack('<' + 'H' * 65536, *range(65536)))
+    write_binary('data.tmp', test_data)
+    binary_encoded = binary_encode('data.tmp')
+    test_js = '''var u16 = new Uint16Array(binaryDecode(src).buffer);
+for(var i = 0; i < 65536; ++i)
+  if (u16[i] != i) throw i;
+console.log('OK');'''
+    write_file('test.js', read_file(path_from_root('src/binaryDecode.js')) + '\nvar src = ' + binary_encoded + ';\n' + test_js)
+    self.assertContained('OK', self.run_js('test.js'))