audiodev.pygame_audio
pygame-ce playback and capture backend for the portable audiodev contract.
Uses pygame’s own SDL only (never usdl2 / system libSDL2):
Playback:
SDL_QueueAudiovia ctypes against pygame-ce’s bundledlibSDL2— nopygame.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.
- class audiodev.pygame_audio.PygamePCMOutput(fmt, *, samples=4096, poll_ms=2, queue_ms=2000, coalesce_ms=100)[source]
Bases:
PCMOutputPCM 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_sizereports both, so a caller can treat “queued_size() == 0” as end of playback without knowing which buffer holds what.Callers must call
servicefrom their tick. Without it, a partial write can sit in_coalesceunqueued and a wedged device is never noticed.- queued_size()[source]
Bytes still waiting to play, including what has not been handed to SDL.
Both buffers count, so audio parked in
_coalesceduring a rebuild is not mistaken for silence. Use_hw_queuedinstead when the question is what the device is doing.
- is_active()[source]
True while PCM is still queued anywhere.
Deliberately ignores pause state. After the first unpause
_prime_pausestays False for the life of the device, so reading it as “playing” pinned this True forever and hung callers waiting for idle.
- service()[source]
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.
- class audiodev.pygame_audio.PygamePCMInput(fmt, *, device=None, samples=512, poll_ms=2, queue_ms=500)[source]
Bases:
PCMInputMicrophone capture via
pygame._sdl2.AudioDevice.
- audiodev.pygame_audio.pcm_out(format=None, *, latency=None, samples=None, poll_ms=2, queue_ms=None, coalesce_ms=None)[source]
Create a pygame-ce-backed PCM playback device (QueueAudio on pygame SDL).
latencypicks a profile (seeaudiodev.LATENCIES);samples,queue_msandcoalesce_msgiven explicitly override it.