# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Optional host backend selection. Backends never import this module."""
import sys
import backends
def host_kind():
try:
import _wasm_bridge # noqa: F401
return "wasm"
except ImportError:
pass
try:
get_ipython() # noqa: F821
return "jupyter"
except Exception:
return "desktop"
def _uwin32_available():
if sys.platform != "win32":
return False
try:
import uwin32 # noqa: F401
return True
except Exception:
return False
def _module_available(name):
try:
__import__(name)
return True
except Exception:
return False
def _is_micropython():
return getattr(getattr(sys, "implementation", None), "name", "") == "micropython"
def _wasm_probe():
return _is_micropython() and _module_available("_wasm_bridge")
def _web_probe():
return not _is_micropython() and sys.platform == "emscripten"
def _pygame_probe():
return not _is_micropython() and _module_available("pygame")
def _alsa_cards():
try:
from audiodev import alsa_audio
return alsa_audio.has_cards()
except Exception:
return False
def _alsa_probe():
if not sys.platform.startswith("linux") or _wasm_probe() or _web_probe():
return False
return _alsa_cards()
# The transports in the box, in the order they are tried. A spec names a module
# that provides ``pcm_out`` and ``pcm_in``.
for _name, _spec, _probe in (
("wasm_audio", "audiodev.wasm_audio", _wasm_probe),
("web_audio", "audiodev.web_audio", _web_probe),
("win_audio", "audiodev.win_audio", lambda: _uwin32_available()),
("sdl2_audio", "audiodev.sdl2_audio", lambda: _module_available("usdl2")),
("pygame_audio", "audiodev.pygame_audio", _pygame_probe),
("alsa_audio", "audiodev.alsa_audio", _alsa_probe),
):
backends.register("audio", _name, _spec, probe=_probe, _builtin=True)
[docs]
def select_backend():
"""Return the name of the first usable output backend.
Search order: ``OMNIPYTHON_AUDIO`` if set, then the backends a
board config asked for with ``require`` (see `backends`), then the ones in the box
in the documented probe order: wasm, Web Audio, Windows, SDL2, pygame, then
ALSA on a Linux machine with a sound card and neither SDL2 nor pygame.
"""
for name, _spec, _builtin in backends.candidates("audio", backends._env("OMNIPYTHON_AUDIO")):
return name
raise ImportError(
"no usable audio transport: install pygame-ce, install/provide usdl2, "
"or explicitly wrap an SDL, WASAPI, ALSA, Web Audio, I2S, wasm, or emulated transport"
)
def _impl(name, direction):
spec = backends.spec("audio", name)
if spec is None:
raise ValueError("unknown audiodev backend: %s" % name)
return getattr(backends.load(spec), direction)
[docs]
def pcm_out(format=None, **kwargs):
"""Construct a raw `PCMOutput <audiodev.PCMOutput>` via `select_backend`.
Push bytes at it with ``write()``. This is what a consumer that already
has PCM wants -- a Connect speaker, a USB audio pump -- and it needs no
audiodsp, because no sample graph is ever pulled.
"""
return _impl(select_backend(), "pcm_out")(format, **kwargs)
[docs]
def pcm_in(format=None, **kwargs):
"""Construct a raw `PCMInput <audiodev.PCMInput>` via `select_backend`."""
return _impl(select_backend(), "pcm_in")(format, **kwargs)
[docs]
def audio_out(format=None, **kwargs):
"""Construct an `AudioOut <audiodev.sample_out.AudioOut>` sample player.
``play(sample)`` over a CircuitPython-shaped audiosample. This is what a
board's ``audio_out`` role returns, and the name means the same thing
here as it does there -- see ``pcm_out`` for the raw sink.
``chunk_ms``/``lookahead_chunks``/``max_catchup_chunks`` go to the
`AudioOut` pump; everything else goes to the transport factory.
``latency="low"`` also shrinks the pump's chunk to 20ms (a 40ms schedule
with the default 2-chunk lookahead) -- the transport profile alone cannot
lower note-to-sound latency below what the pump keeps rendered ahead.
"""
from audiodev.sample_out import AudioOut
pump_kwargs = {}
for key in ("chunk_ms", "lookahead_chunks", "max_catchup_chunks"):
if key in kwargs:
pump_kwargs[key] = kwargs.pop(key)
if kwargs.get("latency") == "low":
pump_kwargs.setdefault("chunk_ms", 10)
if sys.platform == "win32":
# WASAPI shared mode plus soft timers can stall the pump for
# tens of ms; a 2-chunk (20ms) cushion starved audibly (a click
# at nearly every note - measured 68 buffer-empty events in 12s
# of the drum machine). Six chunks (60ms) measured 2, at a
# note-to-sound cost that stays acceptable for live pads.
pump_kwargs.setdefault("lookahead_chunks", 6)
elif host_kind() == "wasm":
# A browser is the same shape and for the same reason. The 10ms
# tick this profile asks for is not what a page delivers: the
# gallery's piano, measured buffer by buffer out of the page's
# own AudioContext, gets one every 23ms and sometimes 90. A
# 2-chunk cushion is 20ms, so the sink is dry before the next
# tick BY CONSTRUCTION -- measured as ~10 gaps a second, 2-6% of
# the stream replaced by silence, which is a continuous granular
# crackle under the note. Six chunks is 60ms, past the median tick and past all
# but the worst.
pump_kwargs.setdefault("lookahead_chunks", 6)
return AudioOut(pcm_out(format, **kwargs), **pump_kwargs)