# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""SDL2 audio backend for `audiodev` (pure Python, queued audio only).
Playback pushes PCM with ``SDL_QueueAudio`` and never installs an audio
callback: SDL's audio thread is not registered with the Python/MicroPython
interpreter, so calling back into it from it is unsafe (it segfaults
under MicroPython and fights the GIL under CPython/LVGL).
Four behaviors keep queued playback smooth, all established by measurement on
WSLg/PulseAudio rather than by preference:
* small writes are coalesced (``coalesce_ms``, 100ms by default) before being
handed to SDL;
* the device stays paused until ``PREBUFFER_MS`` is queued, because starting on
a nearly empty queue and then starving it makes PulseAudio stop asking for
data;
* if the device falls far behind realtime, it is reopened and the unplayed PCM is
re-queued (see ``STALL_WINDOW_MS``);
* that reopen runs on a worker thread, because closing a wedged device blocks for
over a second and the caller is usually driving a UI.
Before simplifying any of this
------------------------------
Each rule below replaced an obvious, simpler version that measurably failed. The
failure is named so it can be re-tested instead of rediscovered:
* Detect stalls by **consumption rate over a window**, never by watching queue
depth. A caller that tops the queue up replaces every consumed period before
the next check sees it, so depth does not fall even when the sink has died.
* Gate the prebuffer on `SDLPCMOutput._hw_queued`, never on
`SDLPCMOutput.queued_size`. Counting bytes still sitting in the
software buffer let the device start on ~40ms of audio, underrun, and wedge
again immediately after every recovery.
* Keep the reopen off the caller's thread, and keep ``RECOVER_SETTLE_MS``
between close and open. A synchronous rebuild stalled the caller's tick for
~1.8s; reopening with no gap handed back the same wedged sink and re-stalled
within seconds, in pairs.
* Size ``_shadow`` to cover everything SDL may still hold. Anything smaller
silently drops audio during recovery.
* Do not let "the device is unpaused" mean playing in
`SDLPCMOutput.is_active` -- it stays unpaused for the life of the
device, so callers would wait forever for playback that already finished.
The ``recycles``, ``lost_bytes`` and ``requeued_bytes`` counters exist to keep
those claims checkable: a healthy long run recycles rarely and loses nothing.
``README.md`` in this directory has the full account, including how to measure a
change before making it.
This module also runs on MicroPython (unix and ``micropython.exe``) and
CircuitPython, so it avoids CPython-only APIs -- notably it consumes buffers with
``buf[:n] = b""`` rather than ``del buf[:n]``, which those interpreters reject at
runtime, not at import. See "Portability" in ``README.md``; verify changes by
running ``examples/audio_out_test.py`` under all three interpreters.
"""
try:
import asyncio
except ImportError: # pragma: no cover
try:
import uasyncio as asyncio
except ImportError:
asyncio = None
import sys
import time
from audiodev import AudioFormat, PCMInput, PCMOutput, check_latency
from audiodev.bytequeue import ByteQueue
import usdl2 as sdl
try:
import threading
except ImportError: # pragma: no cover
threading = None
# SDL device period (``SDL_AudioSpec.samples``) for playback. Queued audio does
# not care about device latency, so this is chosen for stall detection: the
# queue legitimately holds steady for up to one period between SDL's pulls.
DEFAULT_PLAY_SAMPLES = 4096
# Playback cushion held in SDL's queue. Speech synthesis is bursty, so a couple
# of seconds keeps the device fed while the next sentence is still being made.
DEFAULT_PLAY_QUEUE_MS = 2000
# PCM to accumulate in the *software* buffer before handing a piece to SDL.
# Batching keeps a caller's small writes from becoming one SDL_QueueAudio call
# each, but a realtime producer waits this long before its first sound.
DEFAULT_COALESCE_MS = 100
# Playback settings per ``audiodev`` latency profile. Only the values a caller
# left unset are taken from here.
#
# "low" is chosen for note-to-sound delay rather than throughput:
#
# * a 256-sample period is ~11ms at 24kHz instead of ~170ms, so playback starts
# and stops on a musical timescale;
# * a 5ms coalesce window is under one 10ms pump chunk (see
# ``auto.sample_audio_out``), so each chunk reaches SDL as it is rendered;
# * a 25ms prebuffer (~2 periods) primes the device without seeding a
# permanent latency floor.
#
# Measured with the AudioOut pump (backpressure-aware) on WSLg: ~16-32ms of
# queue ahead of a pressed note, zero underruns. The tradeoff is real -- a
# short queue leaves less room to recover from a host sink stall -- so it is
# opt-in, not the default.
# The fourth field is the prebuffer (ms of PCM the device queue must hold
# before a freshly primed device unpauses). It is part of note-to-sound
# latency in a way the others are not: a realtime pump produces exactly what
# the device consumes, so whatever piled up behind the paused device while
# priming can never drain on its own -- it rides ahead of every note for the
# life of the stream (AudioOut's backpressure skip trims it, but a smaller
# prime is latency that never exists in the first place). "low" primes ~2
# periods instead of PREBUFFER_MS.
_PLAY_PROFILES = {
None: (DEFAULT_PLAY_SAMPLES, DEFAULT_PLAY_QUEUE_MS, DEFAULT_COALESCE_MS, None),
"buffered": (DEFAULT_PLAY_SAMPLES, DEFAULT_PLAY_QUEUE_MS, DEFAULT_COALESCE_MS, None),
"low": (256, 250, 5, 25),
}
# Capture profiles. Recording has no prebuffer or coalescing, so only the period
# and queue matter.
_CAPTURE_PROFILES = {
None: (512, 250),
"buffered": (512, 250),
"low": (256, 100),
}
# PCM to accumulate in the *device* queue before unpausing a freshly primed
# device. Lowering this trades startup latency for the risk that the sink stops
# asking for data; it is capped per stream so it can never exceed the caller's
# fill watermark (see ``_prebuffer_bytes``).
PREBUFFER_MS = 500
# Window over which playback progress is measured, and the fraction of realtime
# below which the device counts as wedged.
#
# WSLg's PulseAudio RDP sink degrades after roughly a minute of continuous
# playback: it keeps taking data, but at 5-30% of realtime, while SDL still
# reports the device as playing. It is not specific to this backend (plain
# ``paplay`` of a 150s file stalls the same way while a 60s file completes) and
# closing and reopening the device is the only thing that restores realtime
# playback -- pausing and unpausing the same device does not. Because the sink
# trickles rather than freezing, the test has to be a rate over a window; "no
# progress at all for N ms" almost never becomes true. Remove this recovery once
# hosts can sustain long playback.
#
# Both values are a compromise between false positives and slow recovery, so
# move them only with rate measurements in hand: a shorter window or a higher
# ratio starts firing on healthy playback (period quantization alone can read
# well under realtime over a short span), while a longer window or lower ratio
# leaves audible slow-motion audio before recovery kicks in.
STALL_WINDOW_MS = 1500
STALL_RATIO = 0.5
# Spacing of the progress samples that make up the window.
STALL_SAMPLE_MS = 100
# Skip one window after a reopen so the measurement starts on steady state
# rather than on the device's ramp-up.
RECOVER_GRACE_MS = 1500
# Gap between closing and reopening during recovery. Reopening immediately gets
# the same wedged sink back -- measurably so: those opens return in ~3ms and
# re-wedge within seconds, while opens that follow a settled close take ~1.3s
# (the host building a new sink) and then run normally. The rebuild is off the
# caller's thread, so this delay costs only silence, not responsiveness.
RECOVER_SETTLE_MS = 800
def _android_session():
"""Attach Android media focus/FGS session on first PCM open (lazy).
Non-Android hosts get ``session=None`` (unchanged PCMOutput behavior).
On Android the module must be present; acquire/release stay lazy until
``open()`` / ``write()`` via `SDLPCMOutput`.
"""
if sys.platform != "android":
return None
from audiodev.android_audio import get_session
return get_session()
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 _monotonic_ms():
if hasattr(time, "ticks_ms"):
return time.ticks_ms()
return int(time.time() * 1000)
def _elapsed_ms(since):
if hasattr(time, "ticks_diff"):
return time.ticks_diff(_monotonic_ms(), since)
return _monotonic_ms() - since
def _diff_ms(later, earlier):
if hasattr(time, "ticks_diff"):
return time.ticks_diff(later, earlier)
return later - earlier
def _deadline_ms(milliseconds):
"""A future timestamp comparable with `_elapsed_ms` (ticks-safe)."""
if hasattr(time, "ticks_add"):
return time.ticks_add(_monotonic_ms(), milliseconds)
return _monotonic_ms() + milliseconds
def _sdl_format(fmt):
if fmt.bits == 8:
return sdl.AUDIO_S8 if fmt.signed else sdl.AUDIO_U8
suffix = "LSB" if fmt.byteorder == "little" else "MSB"
name = "AUDIO_%s%d%s" % ("S" if fmt.signed else "U", fmt.bits, suffix)
value = getattr(sdl, name, None)
if value is None:
raise ValueError("SDL does not support %r" % fmt)
return value
[docs]
def list_audio_devices(capture=False):
"""Return SDL playback or capture device names."""
count = sdl.SDL_GetNumAudioDevices(bool(capture))
if count < 0:
raise OSError(sdl.SDL_GetError())
return tuple(sdl.SDL_GetAudioDeviceName(index, bool(capture)) for index in range(count))
[docs]
class SDLPCMOutput(PCMOutput):
"""SDL playback via ``SDL_QueueAudio`` (no audio callback, no mixer).
PCM travels through two buffers: writes land in ``_coalesce`` (software) and
are handed to SDL in ``coalesce_ms`` pieces up to ``_queue_limit`` (hardware).
`queued_size` reports both, so a caller can treat "queued_size() == 0"
as end of playback without knowing which buffer holds what.
Callers must call `service` from their tick. Without it, a partial
write can sit in ``_coalesce`` unqueued and a wedged device is never noticed.
"""
def __init__(
self,
fmt,
*,
device=None,
samples=512,
queue_ms=250,
poll_ms=2,
coalesce_ms=DEFAULT_COALESCE_MS,
prebuffer_ms=None,
session=None,
):
super().__init__(fmt, session=session)
self.device_name = device
self.samples = int(samples)
self.queue_ms = int(queue_ms)
self.poll_ms = int(poll_ms)
self.device = 0
self._bytes_per_second = fmt.rate * fmt.frame_size
self._queue_limit = max(fmt.frame_size, self._bytes_per_second * queue_ms // 1000)
# SDL pulls a whole period at a time, so the queue must comfortably hold
# several of them no matter what ``queue_ms`` a caller asked for.
period_bytes = self.samples * fmt.frame_size
self._queue_limit = max(self._queue_limit, 3 * period_bytes)
self.coalesce_ms = int(coalesce_ms)
self._coalesce_bytes = max(
fmt.frame_size,
self._bytes_per_second * self.coalesce_ms // 1000,
)
# Kept under the caller's fill watermark so a pump that stops writing at
# the watermark cannot leave us paused forever.
_prebuffer_ms = PREBUFFER_MS if prebuffer_ms is None else int(prebuffer_ms)
self._prebuffer_bytes = min(
self._queue_limit // 4,
max(fmt.frame_size, self._bytes_per_second * _prebuffer_ms // 1000),
)
period_ms = 1000 * self.samples // max(1, fmt.rate)
# Long enough that period quantization cannot look like a slow sink: a
# healthy device delivers whole periods, so a short window can read well
# under realtime purely from where the period boundaries fall.
self._stall_window_ms = max(STALL_WINDOW_MS, 6 * period_ms)
self._min_rate = int(self._bytes_per_second * STALL_RATIO)
# Below this the queue may simply be running dry, which says nothing
# about the device.
self._min_depth_bytes = 2 * period_bytes
# Backstop for callers that ignore ``queued_size()`` backpressure: a
# rebuild only needs a couple of seconds of headroom here.
self._max_pending = 4 * self._queue_limit
# Both buffers are chunked. Growing a bytearray needs a contiguous
# block the size of everything pending, and a MicroPython heap shared
# with a UI may not have one. Writes past the backstop wait (bounded);
# past twice the backstop, what doesn't fit is dropped and counted.
self._coalesce = ByteQueue(2 * self._max_pending)
# Must cover every byte SDL can still hold, or a rebuild cannot restore
# the whole unplayed queue.
self._shadow_limit = self._queue_limit + self._coalesce_bytes
self._prime_pause = True
self._lock = threading.Lock() if threading is not None else None
# True while a worker thread is closing/reopening the device.
self._recycling = False
# True while service() is running. A scheduled pump (mp_sched) can call
# service() re-entrantly on this same thread; the guard drops the nested
# call so the two do not both mutate self._samples.
self._servicing = False
# Cumulative bytes handed to SDL. Progress is measured as
# ``_queued_total - queued``, not as a drop in queue depth: a caller that
# tops the queue up replaces each consumed period before the next check
# sees it, so depth alone never falls while playback is healthy.
self._queued_total = 0
# Trailing (timestamp, consumed) samples spanning ``_stall_window_ms``.
self._samples = []
self._grace_until = None
# Copy of the most recently queued PCM (never more than one full queue).
# A recycle discards whatever SDL still held, so the unplayed tail is
# re-queued from here instead of being dropped.
self._shadow = ByteQueue(self._shadow_limit)
self.recycles = 0
self.lost_bytes = 0
self.requeued_bytes = 0
self.channel = None # no mixer; kept for callers that probe for one
self.mode = "queue"
# -- device ---------------------------------------------------------------
def _open(self):
self._open_device()
def _open_device(self):
"""Open the SDL device **paused** and reset progress accounting.
Opening paused is not an optimization: the device must not start on the
first small chunk of a flush (see `_unpause_if_primed`). Progress
state is per-device, so ``_queued_total`` and the rate samples reset here
-- carrying them across a reopen would read as a huge instant stall.
"""
if self.device:
return self
if sdl.SDL_InitSubSystem(sdl.SDL_INIT_AUDIO) != 0:
raise OSError(sdl.SDL_GetError())
spec = sdl.SDL_AudioSpec(
self.format.rate,
_sdl_format(self.format),
self.format.channels,
self.samples,
)
self.device = sdl.SDL_OpenAudioDevice(self.device_name, False, spec, None, 0)
if not self.device:
raise OSError(sdl.SDL_GetError())
# Stay paused until primed; see PREBUFFER_MS.
self._prime_pause = True
self._queued_total = 0
# Do NOT clear self._samples here. On a recycle this runs on the rebuild
# worker thread while the tick thread may be inside _check_stall reading
# that same list -- an unlocked clear there raced it empty and crashed
# the pump. The stall window belongs to the tick thread: _check_stall
# clears it every tick during the post-rebuild grace window instead.
sdl.SDL_PauseAudioDevice(self.device, 1)
return self
def _close_device(self):
"""Tear the SDL device down, leaving the software buffers alone."""
if self.device:
sdl.SDL_PauseAudioDevice(self.device, 1)
sdl.SDL_ClearQueuedAudio(self.device)
sdl.SDL_CloseAudioDevice(self.device)
self.device = 0
def _close(self):
"""Close for good, discarding anything still queued.
Waits out an in-flight rebuild first: that worker owns the device handle
and would otherwise reopen it moments after this returns.
"""
self._wait_rebuild()
self._close_device()
self._coalesce.clear()
self._shadow.clear()
self._queued_total = 0
del self._samples[:]
self._prime_pause = True
def _wait_rebuild(self, timeout_ms=3000):
"""Wait out an in-flight rebuild before touching the device."""
waited = 0
while self._recycling and waited < timeout_ms:
_sleep_ms(self.poll_ms)
waited += self.poll_ms
return not self._recycling
# -- queue accounting -----------------------------------------------------
def _hw_queued(self):
"""Bytes SDL still holds. The only trustworthy measure of playback."""
if not self.device:
return 0
return int(sdl.SDL_GetQueuedAudioSize(self.device))
[docs]
def queued_size(self):
"""Bytes still waiting to play, including what has not been handed to SDL.
Both buffers count, so audio parked in ``_coalesce`` during a rebuild is
not mistaken for silence. Use `_hw_queued` instead when the
question is what the *device* is doing.
"""
return self._hw_queued() + len(self._coalesce)
[docs]
def is_active(self):
"""True while PCM is still queued anywhere.
Deliberately ignores pause state: the device stays unpaused for its whole
life, so testing that instead would report playback as active forever and
hang callers that wait for idle.
"""
return self.queued_size() > 0
# -- writing --------------------------------------------------------------
def _unpause_if_primed(self, force=False):
"""Start playback once ``_prebuffer_bytes`` are queued.
``force`` starts on whatever is queued -- used when the caller has said
no more PCM is coming (short sounds, flush, drain), so a 40ms beep plays.
The gate is ``_hw_queued()``, not ``queued_size()``. Counting software
bytes here is the single easiest way to reintroduce the wedge this whole
module works around: after a rebuild the re-queued tail satisfies the
threshold instantly, so the device starts nearly empty and dies again.
"""
if not self.device or not self._prime_pause:
return
# Only what SDL holds counts: starting on a nearly empty device queue
# starves it immediately, which is the very thing PREBUFFER_MS avoids.
queued = self._hw_queued()
if queued <= 0:
return
if not force and queued < self._prebuffer_bytes:
return
sdl.SDL_PauseAudioDevice(self.device, 0)
self._prime_pause = False
del self._samples[:]
def _queue_bytes(self, buf):
"""Hand ``buf`` to SDL, remembering it so a recycle can re-queue it.
The copy kept in ``_shadow`` is what makes recovery lossless: SDL discards
its queue on close, so the unplayed tail can only come from here.
Never waits for room. Backpressure belongs to the callers that can afford
it -- `_flush_coalesce` simply stops early, and `awrite` awaits
instead of sleeping. A wait here would block whichever thread or event
loop happened to be flushing.
"""
data = bytes(buf)
if self._lock is not None:
self._lock.acquire()
try:
if not self.device:
self._open_device()
rc = sdl.SDL_QueueAudio(self.device, data, len(data))
if rc == 0:
self._queued_total += len(data)
self._shadow.push(data)
finally:
if self._lock is not None:
self._lock.release()
if rc != 0:
raise OSError(sdl.SDL_GetError())
def _flush_coalesce(self, force=False):
"""Move buffered PCM into SDL in period-sized pieces.
``force`` means the caller has no more PCM: queue everything and start it
now, regardless of the prebuffer threshold.
Without ``force`` this never blocks and never overfills: it stops at
``_queue_limit`` and leaves the rest buffered, because the caller may be
a UI thread. `_unpause_if_primed` is called once at the end rather
than per piece, so a large flush cannot start the device on its first
chunk.
"""
frame = max(1, self.format.frame_size)
while self._coalesce and not self._recycling:
pending = len(self._coalesce)
if not force and pending < self._coalesce_bytes:
break
# One coalesce window at a time even when forced, so no piece is
# bigger than that.
take = min(pending, self._coalesce_bytes)
take -= take % frame
if take <= 0:
break
if not force and self._hw_queued() + take > self._queue_limit:
# Full: keep the rest buffered rather than blocking the caller,
# which may be the UI thread.
break
self._queue_bytes(self._coalesce.take(take))
# Start (or not) once, after everything that fits has been queued, so the
# device never begins on the first small chunk of a large flush.
self._unpause_if_primed(force=force)
def _write(self, buf):
"""Accept PCM, queueing as much as fits. Always consumes all of ``buf``.
Safe to call during a rebuild -- the data is buffered and queued in order
behind the re-queued tail once the device is back, so a caller does not
have to know a recovery is in progress. ``_max_pending`` is only a
backstop against callers that ignore `queued_size` entirely.
"""
if not self._recycling:
self._open_device()
if not buf:
return 0
waited = 0
while len(self._coalesce) >= self._max_pending and waited < 500:
_sleep_ms(self.poll_ms)
waited += self.poll_ms
# While the device is being rebuilt the PCM just accumulates here; the
# next service tick queues it in order behind the re-queued tail.
self._accept(buf)
if self._recycling:
return len(buf)
self._flush_coalesce(force=False)
return len(buf)
async def _awrite(self, buf):
"""Async `write`: awaits backpressure instead of sleeping through it.
Yields once up front even when there is room. `write`'s bounded
sleeps would otherwise stall the whole event loop, and a task looping on
``awrite`` alone would never give the loop a chance to run anything else
-- including its own cancellation.
"""
if not buf:
return 0
await _asleep_ms(0)
if not self._recycling:
self._open_device()
waited = 0
while len(self._coalesce) >= self._max_pending and waited < 500:
await _asleep_ms(self.poll_ms)
waited += self.poll_ms
self._accept(buf)
if not self._recycling:
self._flush_coalesce(force=False)
return len(buf)
def _accept(self, buf):
taken = self._coalesce.write(buf)
if taken < len(buf):
# Full even after the wait: the caller is far ahead of realtime.
self.lost_bytes += len(buf) - taken
[docs]
def clear(self):
"""Drop queued PCM now (abort); keep the device and re-prime on next write."""
self._coalesce.clear()
if not self.device:
return
sdl.SDL_PauseAudioDevice(self.device, 1)
sdl.SDL_ClearQueuedAudio(self.device)
self._prime_pause = True
self._shadow.clear()
self._queued_total = 0
del self._samples[:]
# -- stall recovery -------------------------------------------------------
[docs]
def service(self):
"""Call from the app's tick: flush partial writes and watch for stalls.
Required, not optional -- stall recovery only happens here and in
`drain`. A no-op during a rebuild, since the worker owns the device
and the pending PCM is queued on the next tick.
Re-entrancy: a MicroPython ``mp_sched`` callback (spremote's pump) can
fire between bytecodes on this same thread and call ``service()`` again
while we are mid-``_check_stall``. Both would mutate ``self._samples``
and the inner one leaves the outer indexing an emptied list. The guard
makes the nested call a no-op; the outer call finishes the tick.
"""
if self._recycling or not self.device or self._servicing:
return
self._servicing = True
try:
if self._coalesce:
self._flush_coalesce(force=False)
# Failsafe: a pump parked at the fill watermark must not leave paused.
self._unpause_if_primed()
self._check_stall()
finally:
self._servicing = False
def _check_stall(self):
"""Recycle the device when it plays back well below realtime.
Measures bytes actually consumed per second over ``_stall_window_ms``,
and only while the queue is deep enough that a slow rate can only be the
device rather than a caller that stopped writing.
Consumption is ``_queued_total - _hw_queued()``, a monotonic total. The
tempting version -- "has the queue depth stopped falling?" -- does not
work: the pump refills each consumed period before the next check, so
depth stays flat during healthy playback and during a total stall alike.
"""
try:
self._check_stall_impl()
except IndexError:
# Re-entrancy safety net. The service() guard stops the common
# nested case, but a scheduled pump's write()->_unpause and drain()
# can still empty self._samples between our index checks on this
# same thread. Skip the tick; the window rebuilds on the next call.
return
def _check_stall_impl(self):
if not self.device or self._prime_pause:
return
if self._grace_until is not None and _elapsed_ms(self._grace_until) < 0:
del self._samples[:]
return
hw = self._hw_queued()
consumed = self._queued_total - hw
if hw < self._min_depth_bytes:
del self._samples[:]
return
now = _monotonic_ms()
samples = self._samples
if not samples or _diff_ms(now, samples[-1][0]) >= STALL_SAMPLE_MS:
samples.append((now, consumed))
while len(samples) > 1 and _diff_ms(now, samples[1][0]) >= self._stall_window_ms:
del samples[0]
# Snapshot the head once, and tolerate an empty list: _open_device no
# longer clears self._samples off-thread, but _close/clear/drain still
# can, so read the oldest sample defensively rather than index twice.
if not samples:
return
head_t, head_c = samples[0]
span = _diff_ms(now, head_t)
if span < self._stall_window_ms:
return
rate = (consumed - head_c) * 1000 // span
if rate >= self._min_rate:
return
del samples[:]
self._recycle_device(stalled_bytes=hw, rate=rate)
def _recycle_device(self, stalled_bytes=0, rate=None):
"""Rebuild the device, keeping the audio SDL had not played yet.
Closing and reopening blocks for over a second on some hosts, so it runs
on a worker thread: the caller may be driving a UI. The unplayed tail is
pushed back to the front of the coalesce buffer, which keeps it ahead of
anything written during the rebuild and keeps it visible to
``queued_size()`` so callers do not mistake the gap for end of playback.
"""
if self._recycling:
return
stuck = min(int(stalled_bytes), len(self._shadow))
tail = self._shadow.tail(stuck) if stuck else b""
self.lost_bytes += int(stalled_bytes) - len(tail)
self.requeued_bytes += len(tail)
self.recycles += 1
self._recycling = True
del self._samples[:]
if tail:
self.lost_bytes += len(tail) - self._coalesce.unread(tail)
if self._lock is None:
self._rebuild_device()
else:
threading.Thread(target=self._rebuild_device, daemon=True).start()
def _rebuild_device(self, attempts=3):
"""Close, settle, reopen. Runs on the recycle worker thread.
The ``RECOVER_SETTLE_MS`` gap is the point of this function: without it
the host hands back the same wedged sink. Reopening can still fail while
the sink is busy, so it retries.
Never raises. Nothing is waiting to catch this, and a half-finished
rebuild is worse than a reported failure: with no device, `service`
does nothing, so any PCM left buffered would keep `is_active` true
forever and hang callers waiting for playback to end. If no device can be
had, that audio is dropped and counted.
"""
error = None
try:
self._close_device()
for _ in range(attempts):
_sleep_ms(RECOVER_SETTLE_MS)
try:
self._open_device()
return
except Exception as exc:
error = exc
self.lost_bytes += len(self._coalesce)
self._coalesce.clear()
self._shadow.clear()
print("[sdl2_audio] reopen after stall failed: %s" % (error,))
finally:
self._grace_until = _deadline_ms(RECOVER_GRACE_MS)
self._recycling = False
# -- draining -------------------------------------------------------------
def _drain_timeout_ms(self):
"""Real-time playout of what is queued, plus slack.
Never wait forever: a device that stopped consuming would otherwise hang
the caller instead of reporting the stall.
"""
queued_ms = self.queued_size() * 1000 // max(1, self._bytes_per_second)
return 2 * queued_ms + 500
[docs]
def drain(self, timeout_ms=None):
"""Block until queued PCM has played out. False if it timed out.
Keeps servicing the stall detector while it waits, and grants a fresh
playout budget whenever a recycle happens, so recovering mid-drain does
not truncate the tail it just re-queued.
"""
self.open()
self._wait_rebuild()
self._open_device()
self._flush_coalesce(force=True)
self._unpause_if_primed(force=True)
if timeout_ms is None:
timeout_ms = self._drain_timeout_ms()
waited = 0
seen = self.recycles
while self.queued_size() > 0 and waited < timeout_ms:
_sleep_ms(self.poll_ms)
waited += self.poll_ms
self._check_stall()
self._flush_coalesce(force=True)
if self.recycles != seen:
# A rebuild re-queued audio: allow it its own playout time.
seen = self.recycles
timeout_ms = waited + self._drain_timeout_ms()
return self.queued_size() == 0
[docs]
async def adrain(self, timeout_ms=None):
"""Async `drain`; identical rules, yields instead of sleeping."""
self.open()
self._wait_rebuild()
self._open_device()
self._flush_coalesce(force=True)
self._unpause_if_primed(force=True)
if timeout_ms is None:
timeout_ms = self._drain_timeout_ms()
waited = 0
seen = self.recycles
while self.queued_size() > 0 and waited < timeout_ms:
await _asleep_ms(self.poll_ms)
waited += self.poll_ms
self._check_stall()
self._flush_coalesce(force=True)
if self.recycles != seen:
seen = self.recycles
timeout_ms = waited + self._drain_timeout_ms()
return self.queued_size() == 0
[docs]
def pcm_out(
format=None,
*,
device=None,
latency=None,
samples=None,
queue_ms=None,
coalesce_ms=None,
prebuffer_ms=None,
poll_ms=2,
):
"""Create an SDL-backed `PCMOutput`.
``latency`` picks a profile (see `audiodev.LATENCIES`); pass
``"low"`` for interactive callers such as a synth. Any of ``samples``,
``queue_ms``, ``coalesce_ms`` and ``prebuffer_ms`` given explicitly
override the profile.
"""
check_latency(latency)
p_samples, p_queue_ms, p_coalesce_ms, p_prebuffer_ms = _PLAY_PROFILES[latency]
fmt = format or AudioFormat(16000, 2, 16)
return SDLPCMOutput(
fmt,
device=device,
samples=p_samples if samples is None else samples,
queue_ms=p_queue_ms if queue_ms is None else queue_ms,
coalesce_ms=p_coalesce_ms if coalesce_ms is None else coalesce_ms,
prebuffer_ms=p_prebuffer_ms if prebuffer_ms is None else prebuffer_ms,
poll_ms=poll_ms,
session=_android_session(),
)
[docs]
def pcm_in(
format=None,
*,
device=None,
latency=None,
samples=None,
queue_ms=None,
poll_ms=2,
timeout_ms=100,
):
"""Create an SDL-backed `PCMInput` using real host capture.
``latency`` picks a profile as in `audio_out`; ``samples`` and
``queue_ms`` given explicitly override it. A read returns after
``timeout_ms`` with no samples rather than waiting for them.
"""
check_latency(latency)
default_samples, default_queue_ms = _CAPTURE_PROFILES[latency]
fmt = format or AudioFormat(16000, 1, 16)
return SDLPCMInput(
fmt,
device=device,
samples=default_samples if samples is None else samples,
queue_ms=default_queue_ms if queue_ms is None else queue_ms,
poll_ms=poll_ms,
timeout_ms=timeout_ms,
)