Read ahead so a stalled source cannot speed up playback

[Isma-L154]

Closes #26

The symptom

Tracks occasionally speed up for a moment and then settle — reported from real use as "a veces reproduce algunas canciones rápido y después vuelve a la normalidad."

The mechanism

discord.py's player paces itself against a wall clock:

next_time = self._start + DELAY * self.loops
delay = max(0, DELAY + (next_time - time.perf_counter()))
time.sleep(delay)

When source.read() blocks — FFmpeg waiting on bytes from yt-dlp — the player falls behind that schedule. next_time is then in the past, delay clamps to zero, and it sends frames as fast as it can until it catches up.

That burst is what you hear.

FFmpegPCMAudio reads straight from the subprocess pipe with no buffering beyond the pipe itself, so any gap in yt-dlp's delivery propagates directly into the player's timing.

Why bandwidth was not the answer

Sustained throughput measured at ~112 KB/s against the ~20 KB/s realtime needs — about 6x headroom. Average rate was never the problem. The problem is momentary gaps, which YouTube produces once it starts throttling a long download after the initial burst.

The fix

BufferedAudioSource keeps 5 seconds of PCM ready, filled by a background thread. A stall shorter than the buffer never reaches the player.

The queue is bounded. An unbounded one in front of a fast source would pull an entire track into RAM and undo the backpressure that the yt-dlp pipe exists to provide — the same property #6 was careful to preserve. 5 s is 250 frames, ~960 KB.

Order in the chain is load-bearing

FFmpegPCMAudio  ->  BufferedAudioSource  ->  PCMVolumeTransformer

The read-ahead wraps FFmpeg, which is the thing that stalls. PCMVolumeTransformer stays outermost because MusicPlayer.set_volume does:

if vc and vc.source and isinstance(vc.source, discord.PCMVolumeTransformer):

Wrapping the buffer around the outside would have silently broken !volume — no error, just a command that stops doing anything. test_the_volume_transformer_stays_outermost guards it.

Verification

Against real YouTube audio on the production host, consuming at realtime pace:

cadena: PCMVolumeTransformer -> BufferedAudioSource -> FFmpegPCMAudio
capacidad del buffer: 250 tramas (5.0s)
tramas listas tras 6s: 250

lectura mas lenta   : 0.2 ms   (limite antes de acelerar: 20 ms)
desfase acumulado   : +0 ms

Slowest read was 0.2 ms against a 20 ms budget, with zero accumulated drift — exactly the condition under which the catch-up burst cannot happen.

Unit tests (15 new) drive sources that stall deliberately: a 1-second stall is absorbed with reads completing in under 0.2 s total; frames arrive in order with none dropped; the buffer stays bounded and the producer does not run past the cap; cleanup() stops the thread and reaches the wrapped source; a source that raises ends playback instead of hanging; and no reader threads are left behind across repeated construction.

258 passed overall.

Note on confidence

The mechanism is derived from discord.py's player source and matches the reported symptom precisely, but the symptom was not reproduced live — it is intermittent and depends on YouTube's throttling. The change is low risk and independently justified (a stalling audio pipeline is worth insulating regardless). If speed-ups persist after this lands, the cause is elsewhere and worth a fresh issue.