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_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.

class audiodev.pygame_audio.PygamePCMOutput(fmt, *, samples=4096, poll_ms=2, queue_ms=2000, coalesce_ms=100)[source]

Bases: 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.

queued_size()[source]

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.

is_active()[source]

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.

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.

drain(timeout_ms=None)[source]

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.

async adrain(timeout_ms=None)[source]

Async drain; identical rules, yields instead of sleeping.

clear()[source]

Drop queued PCM now (abort); keep the device and re-prime on next write.

class audiodev.pygame_audio.PygamePCMInput(fmt, *, device=None, samples=512, poll_ms=2, queue_ms=500)[source]

Bases: PCMInput

Microphone 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).

latency picks a profile (see audiodev.LATENCIES); samples, queue_ms and coalesce_ms given explicitly override it.

audiodev.pygame_audio.pcm_in(format=None, *, device=None, latency=None, samples=None, poll_ms=2, queue_ms=None)[source]

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.