# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""pygame-ce playback and capture backend for the portable `audiodev` contract.
Uses **pygame's own SDL** only (never ``usdl2`` / system libSDL2):
- **Playback:** ``SDL_QueueAudio`` via ctypes against pygame-ce's bundled
``libSDL2`` — no ``pygame.mixer``, no Python audio callback (avoids the
GIL+pause deadlock that freezes the UI under WSLg).
- **Capture:** ``pygame._sdl2.AudioDevice`` (callback), with async close.
Mixing SDL libraries is the one thing that must not change: pygame-ce links its
own ``libSDL2``, and driving pygame's devices through ``usdl2``'s copy means two
SDL states in one process. Load the bundled library (`_pygame_sdl`) or use
``sdl2_audio`` instead — never both against the same device.
Before simplifying playback
---------------------------
`PygamePCMOutput` deliberately mirrors ``sdl2_audio.SDLPCMOutput``
mechanism for mechanism: rate-based stall detection, a hardware-only prebuffer
gate, an off-thread rebuild with a settle gap, and a shadow buffer for lossless
recovery. Each exists because the simpler version measurably failed. That module's
docstring records what each one prevents, and ``README.md`` in this directory has
the full account.
Keep the two in step. When a fix lands in one backend it belongs in the other,
because the failure they work around is in the host's audio sink, not in either
library.
"""
import asyncio
import collections
import os
import sys
import threading
import time
from pathlib import Path
from audiodev import AudioFormat, PCMInput, PCMOutput, check_latency
try:
import ctypes
from ctypes import c_char_p, c_int, c_uint8, c_uint16, c_uint32, c_void_p
except ImportError: # MicroPython
ctypes = None
def _sleep_ms(milliseconds):
time.sleep(milliseconds / 1000)
async def _asleep_ms(milliseconds):
await asyncio.sleep(milliseconds / 1000)
def _ensure_pygame():
import pygame
if not pygame.get_init():
pygame.init()
# This backend drives SDL audio directly, so ``pygame.mixer`` would hold a
# second, unused output device open. Under WSLg two concurrent streams make
# the PulseAudio RDP sink stop consuming after ~30s (playback wedges), so
# release the mixer device we never use.
try:
if pygame.mixer.get_init():
pygame.mixer.quit()
except Exception:
pass
return pygame
def _pygame_audio_format(fmt):
"""Map `AudioFormat` to a ``pygame._sdl2.audio`` format constant."""
from pygame._sdl2 import audio as sdl_audio
if fmt.bits == 8:
return sdl_audio.AUDIO_S8 if fmt.signed else sdl_audio.AUDIO_U8
if fmt.bits == 16:
if fmt.byteorder == "little":
return sdl_audio.AUDIO_S16LSB if fmt.signed else sdl_audio.AUDIO_U16LSB
return sdl_audio.AUDIO_S16MSB if fmt.signed else sdl_audio.AUDIO_U16MSB
if fmt.bits == 32:
if fmt.byteorder == "little":
return sdl_audio.AUDIO_S32LSB if fmt.signed else sdl_audio.AUDIO_U32LSB
return sdl_audio.AUDIO_S32MSB if fmt.signed else sdl_audio.AUDIO_U32MSB
raise ValueError("unsupported pygame audio format %r" % (fmt,))
# SDL_AudioFormat integers (match pygame._sdl2 / SDL2 headers).
_AUDIO_U8 = 0x0008
_AUDIO_S8 = 0x8008
_AUDIO_U16LSB = 0x0010
_AUDIO_S16LSB = 0x8010
_AUDIO_U16MSB = 0x1010
_AUDIO_S16MSB = 0x9010
_AUDIO_S32LSB = 0x8020
_AUDIO_S32MSB = 0x9020
_SDL = None
# SDL device period (``SDL_AudioSpec.samples``) for playback. Writes are queued
# rather than callback driven, so device latency is not important.
DEFAULT_PLAY_SAMPLES = 4096
# Playback cushion held in SDL's queue.
DEFAULT_PLAY_QUEUE_MS = 2000
# PCM to accumulate in the *software* buffer before handing a piece to SDL.
DEFAULT_COALESCE_MS = 100
# Playback settings per ``audiodev`` latency profile; see the matching table in
# sdl2_audio.py for why "low" uses these numbers. Only values a caller left unset
# are taken from here.
_PLAY_PROFILES = {
None: (DEFAULT_PLAY_SAMPLES, DEFAULT_PLAY_QUEUE_MS, DEFAULT_COALESCE_MS),
"buffered": (DEFAULT_PLAY_SAMPLES, DEFAULT_PLAY_QUEUE_MS, DEFAULT_COALESCE_MS),
"low": (512, 250, 20),
}
# Capture profiles: period and queue only.
_CAPTURE_PROFILES = {
None: (512, 500),
"buffered": (512, 500),
"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 _sdl_format_int(fmt):
"""Map `AudioFormat` to an ``SDL_AudioFormat`` integer.
Raises for combinations SDL2 has no format for, rather than substituting the
nearest one: a silently wrong format is decoded as noise at the wrong speed,
which is far harder to recognize than an exception at open time.
"""
if fmt.bits == 8:
return _AUDIO_S8 if fmt.signed else _AUDIO_U8
if fmt.bits == 16:
if fmt.byteorder == "little":
return _AUDIO_S16LSB if fmt.signed else _AUDIO_U16LSB
return _AUDIO_S16MSB if fmt.signed else _AUDIO_U16MSB
if fmt.bits == 32:
# SDL2 defines only S32 and F32 at 32 bits -- there is no AUDIO_U32.
if not fmt.signed:
raise ValueError("SDL2 has no unsigned 32-bit format: %r" % (fmt,))
return _AUDIO_S32LSB if fmt.byteorder == "little" else _AUDIO_S32MSB
raise ValueError("unsupported pygame audio format %r" % (fmt,))
def _pygame_sdl():
"""Load the libSDL2 that pygame-ce already linked (not system usdl2)."""
global _SDL
if _SDL is not None:
return _SDL
if ctypes is None:
raise OSError("pygame_audio QueueAudio needs ctypes (CPython)")
_ensure_pygame()
import pygame
root = Path(pygame.__file__).resolve().parent
libs = root.parent / "pygame_ce.libs"
candidates = sorted(libs.glob("libSDL2-*.so*")) if libs.is_dir() else []
if not candidates:
# Windows / alternate layout
candidates = sorted(root.glob("**/libSDL2*.dll")) + sorted(
(root.parent / "pygame_ce.libs").glob("SDL2*.dll")
if (root.parent / "pygame_ce.libs").is_dir()
else []
)
if not candidates:
raise OSError("could not find pygame-ce bundled libSDL2")
lib = ctypes.CDLL(str(candidates[0]))
class SDL_AudioSpec(ctypes.Structure):
_fields_ = [
("freq", c_int),
("format", c_uint16),
("channels", c_uint8),
("silence", c_uint8),
("samples", c_uint16),
("padding", c_uint16),
("size", c_uint32),
("callback", c_void_p),
("userdata", c_void_p),
]
lib.SDL_InitSubSystem.argtypes = [c_uint32]
lib.SDL_InitSubSystem.restype = c_int
lib.SDL_OpenAudioDevice.argtypes = [
c_char_p,
c_int,
ctypes.POINTER(SDL_AudioSpec),
ctypes.POINTER(SDL_AudioSpec),
c_int,
]
lib.SDL_OpenAudioDevice.restype = c_uint32
lib.SDL_CloseAudioDevice.argtypes = [c_uint32]
lib.SDL_CloseAudioDevice.restype = None
lib.SDL_PauseAudioDevice.argtypes = [c_uint32, c_int]
lib.SDL_PauseAudioDevice.restype = None
lib.SDL_QueueAudio.argtypes = [c_uint32, c_void_p, c_uint32]
lib.SDL_QueueAudio.restype = c_int
lib.SDL_GetQueuedAudioSize.argtypes = [c_uint32]
lib.SDL_GetQueuedAudioSize.restype = c_uint32
lib.SDL_ClearQueuedAudio.argtypes = [c_uint32]
lib.SDL_ClearQueuedAudio.restype = None
lib.SDL_GetError.argtypes = []
lib.SDL_GetError.restype = c_char_p
lib.SDL_AudioSpec = SDL_AudioSpec
lib.SDL_INIT_AUDIO = 0x00000010
_SDL = lib
return lib
def _close_audiodevice_async(dev):
"""``AudioDevice.close`` may futex-deadlock — pause sync, close on a daemon.
Do not make this synchronous. The pause takes effect immediately, which is
all a caller actually needs (capture stops), while ``close`` itself can block
indefinitely inside SDL waiting on its callback thread. The daemon thread
means a stuck close cannot keep the process alive either.
"""
if dev is None:
return
try:
dev.pause(1)
except Exception:
pass
def _close_native():
try:
dev.close()
except Exception:
pass
threading.Thread(
target=_close_native, name="pygame-audiodevice-close", daemon=True
).start()
[docs]
class PygamePCMOutput(PCMOutput):
"""PCM playback via pygame's SDL ``QueueAudio`` (no mixer, no py callback).
PCM travels through two buffers: writes land in ``_coalesce`` (software) and
are handed to SDL in ~100ms 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,
*,
samples=DEFAULT_PLAY_SAMPLES,
poll_ms=2,
queue_ms=DEFAULT_PLAY_QUEUE_MS,
coalesce_ms=DEFAULT_COALESCE_MS,
):
super().__init__(fmt)
# ~2s HW QueueAudio cushion: moonshine sentence synth often exceeds
# the old 400ms limit, which underruns to silence between utterances.
self.samples = int(samples)
self.poll_ms = int(poll_ms)
self._bytes_per_second = fmt.rate * fmt.frame_size
self._queue_limit = max(
fmt.frame_size,
self._bytes_per_second * int(queue_ms) // 1000,
)
self._coalesce = bytearray()
self.coalesce_ms = int(coalesce_ms)
self._coalesce_bytes = max(
fmt.frame_size,
self._bytes_per_second * self.coalesce_ms // 1000,
)
# Do not start the device on a nearly empty queue: starting on ~40ms and
# then starving it makes PulseAudio's RDP sink stop asking for data.
# Kept well under the caller's fill watermark so the pump cannot block
# while we are still paused.
self._prebuffer_bytes = min(
self._queue_limit // 4,
max(fmt.frame_size, self._bytes_per_second * PREBUFFER_MS // 1000),
)
self.device = 0
self._prime_pause = True
self.channel = None # debug probes
self.mode = "queue"
period_bytes = self.samples * fmt.frame_size
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.
self._max_pending = 4 * self._queue_limit
# 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._lock = threading.Lock()
self._recycling = 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 = 0.0
# Copy of the most recently queued PCM (never more than one full device
# queue). A recycle discards whatever SDL still held, so the unplayed
# tail is re-queued from here instead of being dropped.
self._shadow = bytearray()
self.recycles = 0
self.lost_bytes = 0
self.requeued_bytes = 0
def _open(self):
self._open_device()
def _open_device(self):
"""Open the 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
sdl = _pygame_sdl()
if sdl.SDL_InitSubSystem(sdl.SDL_INIT_AUDIO) != 0:
err = sdl.SDL_GetError()
raise OSError(err.decode() if err else "SDL_InitSubSystem AUDIO failed")
spec = sdl.SDL_AudioSpec(
self.format.rate,
_sdl_format_int(self.format),
self.format.channels,
0,
max(64, int(self.samples)),
0,
0,
None, # NULL callback → QueueAudio mode
None,
)
obtained = sdl.SDL_AudioSpec()
self.device = sdl.SDL_OpenAudioDevice(
None,
0,
ctypes.byref(spec),
ctypes.byref(obtained),
0, # allowed_changes=0 — pin format
)
if not self.device:
err = sdl.SDL_GetError()
raise OSError(err.decode() if err else "SDL_OpenAudioDevice failed")
self._prime_pause = True
self._queued_total = 0
del self._samples[:]
sdl.SDL_PauseAudioDevice(self.device, 1)
return self
def _hw_queued(self):
"""Bytes SDL still holds. The only trustworthy measure of playback."""
if not self.device:
return 0
return int(_pygame_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. After the first unpause
``_prime_pause`` stays False for the life of the device, so reading it as
"playing" pinned this True forever and hung callers waiting for idle.
"""
return self.queued_size() > 0
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
there is no more PCM coming (short sounds, flush, drain), so a 40ms beep
still 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 = _pygame_sdl()
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.
"""
sdl = _pygame_sdl()
data = bytes(buf)
with self._lock:
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.extend(data)
if len(self._shadow) > self._shadow_limit:
# Slice assignment: MP/CP bytearrays cannot ``del``.
self._shadow[: len(self._shadow) - self._shadow_limit] = b""
if rc != 0:
err = sdl.SDL_GetError()
raise OSError(err.decode() if err else "SDL_QueueAudio failed")
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
take = pending if force else 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
piece = bytes(self._coalesce[:take])
# Slice assignment: MP/CP bytearrays cannot ``del``.
self._coalesce[:take] = b""
self._queue_bytes(piece)
# 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._coalesce.extend(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._coalesce.extend(buf)
if not self._recycling:
self._flush_coalesce(force=False)
return len(buf)
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.
"""
if not self.device or self._prime_pause:
return
now = time.time()
if now < self._grace_until:
del self._samples[:]
return
hw = self._hw_queued()
consumed = self._queued_total - hw
if hw < self._min_depth_bytes:
del self._samples[:]
return
samples = self._samples
if not samples or (now - samples[-1][0]) * 1000 >= STALL_SAMPLE_MS:
samples.append((now, consumed))
while len(samples) > 1 and (now - samples[1][0]) * 1000 >= self._stall_window_ms:
del samples[0]
span = now - samples[0][0]
if span * 1000 < self._stall_window_ms:
return
rate = int((consumed - samples[0][1]) / 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 = bytes(self._shadow[-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._coalesce[:0] = tail
threading.Thread(
target=self._rebuild_device, name="pygame-audio-rebuild", 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[:] = b""
self._shadow = bytearray()
print("[pygame_audio] reopen after stall failed: %s" % (error,))
finally:
self._grace_until = time.time() + RECOVER_GRACE_MS / 1000.0
self._recycling = False
[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.
"""
if self._recycling or not self.device:
return
if self._coalesce:
self._flush_coalesce(force=False)
# Failsafe: pump may be blocked at the HW watermark while still paused.
self._unpause_if_primed()
self._check_stall()
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
def _drain_timeout_ms(self):
"""Real-time playout of what is queued, plus slack.
Never wait forever: a stalled sink (WSLg RDP sink stops consuming) used
to hang the caller indefinitely 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)
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)
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 clear(self):
"""Drop queued PCM now (abort); keep the device and re-prime on next write."""
self._coalesce = bytearray()
if not self.device:
return
sdl = _pygame_sdl()
sdl.SDL_PauseAudioDevice(self.device, 1)
sdl.SDL_ClearQueuedAudio(self.device)
self._prime_pause = True
self._shadow = bytearray()
self._queued_total = 0
del self._samples[:]
def _close_device(self):
"""Tear the SDL device down, leaving the software buffers alone."""
if not self.device:
return
sdl = _pygame_sdl()
try:
sdl.SDL_PauseAudioDevice(self.device, 1)
sdl.SDL_ClearQueuedAudio(self.device)
sdl.SDL_CloseAudioDevice(self.device)
except Exception:
pass
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 = bytearray()
self._shadow = bytearray()
self._queued_total = 0
del self._samples[:]
self._prime_pause = True
[docs]
def pcm_out(
format=None,
*,
latency=None,
samples=None,
poll_ms=2,
queue_ms=None,
coalesce_ms=None,
):
"""Create a pygame-ce-backed PCM playback device (QueueAudio on pygame SDL).
``latency`` picks a profile (see `audiodev.LATENCIES`); ``samples``,
``queue_ms`` and ``coalesce_ms`` given explicitly override it.
"""
check_latency(latency)
default_samples, default_queue_ms, default_coalesce_ms = _PLAY_PROFILES[latency]
fmt = format or AudioFormat(16000, 2, 16)
return PygamePCMOutput(
fmt,
samples=default_samples if samples is None else samples,
poll_ms=poll_ms,
queue_ms=default_queue_ms if queue_ms is None else queue_ms,
coalesce_ms=default_coalesce_ms if coalesce_ms is None else coalesce_ms,
)
[docs]
def pcm_in(format=None, *, device=None, latency=None, samples=None, poll_ms=2, queue_ms=None):
"""Create a pygame-ce-backed PCM capture device via ``_sdl2.AudioDevice``.
``latency`` picks a profile as in `audio_out`; ``samples`` and
``queue_ms`` given explicitly override it.
"""
check_latency(latency)
default_samples, default_queue_ms = _CAPTURE_PROFILES[latency]
fmt = format or AudioFormat(16000, 1, 16)
return PygamePCMInput(
fmt,
device=device,
samples=default_samples if samples is None else samples,
poll_ms=poll_ms,
queue_ms=default_queue_ms if queue_ms is None else queue_ms,
)