# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Browser Web Audio backend for PyScript (`audiodev` PCM devices)."""
try:
import asyncio
except ImportError: # pragma: no cover
try:
import uasyncio as asyncio
except ImportError:
asyncio = None
import sys
import time
try:
from array import array
except ImportError: # pragma: no cover
array = None
from audiodev import AudioFormat, PCMInput, PCMOutput, check_latency
from audiodev.bytequeue import ByteQueue
try:
from js import AudioContext, Object, navigator
from pyscript.ffi import create_proxy
except ImportError: # pragma: no cover - non-browser import for tooling
AudioContext = None
Object = None
navigator = None
create_proxy = None
try:
from js import Function as _JSFunction
except ImportError: # pragma: no cover - non-browser import for tooling
_JSFunction = None
try:
from pyodide.ffi import to_js as _to_js
except ImportError:
try:
from pyscript.ffi import to_js as _to_js
except ImportError: # pragma: no cover - non-browser import for tooling
_to_js = None
def _sleep_ms(milliseconds):
if hasattr(time, "sleep_ms"):
time.sleep_ms(milliseconds)
else:
time.sleep(milliseconds / 1000)
async def _asleep_ms(milliseconds):
if hasattr(asyncio, "sleep_ms"):
await asyncio.sleep_ms(milliseconds)
else:
await asyncio.sleep(milliseconds / 1000)
def _require_browser():
if AudioContext is None or create_proxy is None:
raise ImportError("web_audio requires PyScript / browser JS interop")
def _pcm16_to_f32(buf, channels):
"""Convert little-endian signed 16-bit interleaved PCM to float samples.
Returns one flat interleaved list, each sample divided by 32768. This is
the reference the browser path in `_fill_audio_buffer` must match.
"""
return [sample / 32768.0 for sample in _pcm16_samples(buf)]
def _pcm16_samples(buf):
"""Signed 16-bit samples of *buf* in one bulk decode (no per-sample slicing)."""
view = memoryview(buf)
count = len(view) // 2
raw = bytes(view[: count * 2])
if array is not None:
samples = array("h", raw)
if _BIG_ENDIAN:
samples.byteswap()
return samples
samples = [] # pragma: no cover - no array module
for i in range(count):
sample = int.from_bytes(raw[i * 2 : i * 2 + 2], "little")
if sample >= 0x8000:
sample -= 0x10000
samples.append(sample)
return samples
_BIG_ENDIAN = getattr(sys, "byteorder", "little") == "big"
# Fills an AudioBuffer from little-endian PCM16 bytes in one call: decode,
# divide by 32768 and de-interleave all happen in JS. A DataView reads at any
# byte offset, so the bytes need not be 2-aligned.
_FILL_JS = """
const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
const frames = Math.floor(u8.byteLength / (2 * channels));
for (let c = 0; c < channels; c++) {
const f = new Float32Array(frames);
for (let i = 0, o = c * 2; i < frames; i++, o += 2 * channels) {
f[i] = dv.getInt16(o, true) / 32768;
}
audioBuffer.copyToChannel(f, c);
}
return frames;
"""
_fill_js = None
_fill_js_failed = False
def _fill_js_function():
global _fill_js, _fill_js_failed
if _fill_js is None and not _fill_js_failed:
try:
_fill_js = _JSFunction.new("audioBuffer", "u8", "channels", _FILL_JS)
except Exception:
_fill_js_failed = True
return _fill_js
def _fill_audio_buffer(audio_buffer, buf, channels):
"""Write interleaved PCM16 *buf* into *audio_buffer*, one channel each.
In the browser this is one JS call over the whole buffer. Where that is
not possible (no ``to_js``, or an FFI that cannot hand JS a typed array)
it falls back to converting in Python, with the same result.
"""
global _fill_js_failed
view = memoryview(buf)
if _JSFunction is not None and _to_js is not None and not _fill_js_failed:
fill = _fill_js_function()
if fill is not None:
try:
fill(audio_buffer, _to_js(view), channels)
return
except Exception:
_fill_js_failed = True
floats = _pcm16_to_f32(view, channels)
frames = len(floats) // channels
for channel in range(channels):
channel_data = audio_buffer.getChannelData(channel)
for i in range(frames):
channel_data[i] = floats[i * channels + channel]
def _f32_to_pcm16(channel_data):
"""Convert a float32 channel (JS typed array / sequence) to PCM16 bytes."""
length = len(channel_data)
out = bytearray(length * 2)
for i in range(length):
sample = float(channel_data[i])
if sample > 1.0:
sample = 1.0
elif sample < -1.0:
sample = -1.0
value = int(sample * 32767.0)
out[i * 2 : i * 2 + 2] = value.to_bytes(2, "little", signed=True)
return bytes(out)
def _await_js(value):
"""Resolve a JS Promise synchronously (used from ``open()``)."""
if hasattr(value, "then") and not hasattr(value, "getTracks"):
done = {"result": None, "error": None, "finished": False}
def _ok(result):
done["result"] = result
done["finished"] = True
def _err(error):
done["error"] = error
done["finished"] = True
value.then(create_proxy(_ok), create_proxy(_err))
while not done["finished"]:
_sleep_ms(4)
if done["error"] is not None:
raise OSError(str(done["error"]))
return done["result"]
return value
def _new_audio_context(sample_rate):
"""Create an AudioContext; MicroPython JS FFI rejects keyword args to ``.new``."""
if Object is not None:
opts = Object.new()
opts.sampleRate = int(sample_rate)
return AudioContext.new(opts)
return AudioContext.new()
def _media_audio_constraints():
if Object is not None:
constraints = Object.new()
constraints.audio = True
return constraints
return {"audio": True}
def _try_resume_context(ctx, timeout_ms=80):
"""Best-effort AudioContext.resume(); never block forever (autoplay policy)."""
if ctx is None or str(ctx.state) != "suspended":
return str(getattr(ctx, "state", ""))
try:
pending = ctx.resume()
except Exception:
return str(ctx.state)
if not (hasattr(pending, "then") and create_proxy is not None):
return str(ctx.state)
done = {"finished": False}
def _ok(_result=None):
done["finished"] = True
def _err(_error=None):
done["finished"] = True
try:
pending.then(create_proxy(_ok), create_proxy(_err))
except Exception:
return str(ctx.state)
start = time.time()
while not done["finished"] and (time.time() - start) * 1000.0 < timeout_ms:
_sleep_ms(4)
return str(ctx.state)
_GESTURE_ARMED = False
def _arm_resume_on_gesture(ctx):
"""Resume a suspended context on the next pointer/key event (autoplay unlock)."""
global _GESTURE_ARMED
if ctx is None or create_proxy is None or _GESTURE_ARMED:
return
try:
from js import document
except Exception:
return
def _on(_ev=None):
try:
ctx.resume()
except Exception:
pass
proxy = create_proxy(_on)
opts = None
if Object is not None:
opts = Object.new()
opts.once = True
try:
if opts is not None:
document.addEventListener("pointerdown", proxy, opts)
document.addEventListener("keydown", proxy, opts)
else:
document.addEventListener("pointerdown", proxy)
document.addEventListener("keydown", proxy)
_GESTURE_ARMED = True
except Exception:
pass
[docs]
class WebPCMOutput(PCMOutput):
"""Queued PCM playback via AudioContext + AudioBufferSourceNode."""
def __init__(self, fmt, *, poll_ms=4):
if fmt.bits != 16 or not fmt.signed or fmt.byteorder != "little":
raise ValueError("web_audio playback requires signed 16-bit little-endian PCM")
super().__init__(fmt)
self.poll_ms = int(poll_ms)
self._ctx = None
self._next_time = 0.0
self._sources = []
def _open(self):
_require_browser()
if self._ctx is not None:
return
self._ctx = _new_audio_context(self.format.rate)
state = _try_resume_context(self._ctx)
if state == "suspended":
_arm_resume_on_gesture(self._ctx)
print("web_audio: AudioContext suspended — click/tap the page to hear audio")
self._next_time = float(self._ctx.currentTime)
[docs]
def locked(self):
"""True while the browser keeps the context suspended.
`AudioOut` holds a sample until this turns False, so nothing is
queued onto a clock that is not running. A click or key press
resumes the context (armed in ``open()``).
"""
return self._ctx is not None and str(self._ctx.state) == "suspended"
def _write(self, buf):
frames = len(buf) // self.format.frame_size
if frames <= 0:
return 0
audio_buffer = self._ctx.createBuffer(
self.format.channels,
frames,
self.format.rate,
)
_fill_audio_buffer(audio_buffer, buf, self.format.channels)
source = self._ctx.createBufferSource()
source.buffer = audio_buffer
source.connect(self._ctx.destination)
start_at = self._next_time
now = float(self._ctx.currentTime)
if start_at < now:
start_at = now
source.start(start_at)
self._next_time = start_at + frames / float(self.format.rate)
self._sources.append(source)
return len(buf)
async def _awrite(self, buf):
await _asleep_ms(0)
return self._write(buf)
def _drain(self):
# Autoplay policy can leave the context suspended; currentTime then
# never advances and a naive wait would spin forever on WASM.
if str(self._ctx.state) != "running":
_try_resume_context(self._ctx)
_arm_resume_on_gesture(self._ctx)
if str(self._ctx.state) != "running":
# Keep scheduled buffers alive for wall-clock duration so a later
# user gesture can resume and play them before close().
remaining = max(0.0, self._next_time - float(self._ctx.currentTime))
if remaining > 0:
_sleep_ms(int(remaining * 1000.0) + 100)
return
remaining = self._next_time - float(self._ctx.currentTime)
if remaining <= 0:
return
deadline = time.time() + remaining + 0.5
while float(self._ctx.currentTime) < self._next_time:
if str(self._ctx.state) != "running" or time.time() > deadline:
break
_sleep_ms(self.poll_ms)
async def _adrain(self):
if str(self._ctx.state) != "running":
_try_resume_context(self._ctx)
_arm_resume_on_gesture(self._ctx)
if str(self._ctx.state) != "running":
remaining = max(0.0, self._next_time - float(self._ctx.currentTime))
if remaining > 0:
await _asleep_ms(int(remaining * 1000.0) + 100)
return
remaining = self._next_time - float(self._ctx.currentTime)
if remaining <= 0:
return
deadline = time.time() + remaining + 0.5
while float(self._ctx.currentTime) < self._next_time:
if str(self._ctx.state) != "running" or time.time() > deadline:
break
await _asleep_ms(self.poll_ms)
def _close(self):
for source in self._sources:
try:
source.stop()
except Exception:
pass
self._sources = []
if self._ctx is not None:
try:
self._ctx.close()
except Exception:
pass
self._ctx = None
[docs]
def pcm_out(format=None, *, latency=None, poll_ms=4):
"""Create a Web Audio-backed `PCMOutput` (PyScript).
``latency`` is accepted for portability and validated, but every profile
behaves the same here: playback schedules each buffer onto the
``AudioContext`` timeline as it arrives, so there is no queue or coalescing
window to shorten. Web Audio is already at the "low" profile.
"""
check_latency(latency)
fmt = format or AudioFormat(24000, 1, 16)
return WebPCMOutput(fmt, poll_ms=poll_ms)
[docs]
def pcm_in(format=None, *, latency=None, poll_ms=4, queue_ms=500, samples=None):
"""Create a Web Audio-backed `PCMInput` via getUserMedia (PyScript).
``samples`` is the ``ScriptProcessorNode`` block size, which the browser
rounds to a power of two. The ``"low"`` profile asks for a smaller block.
"""
check_latency(latency)
if samples is None:
samples = 512 if latency == "low" else 2048
fmt = format or AudioFormat(24000, 1, 16)
return WebPCMInput(
fmt,
poll_ms=poll_ms,
queue_ms=queue_ms,
samples=samples,
)