yonlu
6cb22359c8
- Add 15-SUMMARY.md with implementation details - Update STATE.md with quick task 15 completion
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
---
|
|
phase: 15-fix-audio-glitches
|
|
plan: 01
|
|
subsystem: player
|
|
tags: [audio, buffering, performance, glitch-fix]
|
|
dependency_graph:
|
|
requires: []
|
|
provides: [BufferedStreamer, read-ahead-buffering]
|
|
affects: [player-pipeline, speaker-init]
|
|
tech_stack:
|
|
added: []
|
|
patterns: [ring-buffer, goroutine-read-ahead, channel-signaling]
|
|
key_files:
|
|
created:
|
|
- backend/player/buffered_streamer.go
|
|
- backend/player/buffered_streamer_test.go
|
|
modified:
|
|
- backend/player/player.go
|
|
decisions:
|
|
- "2-second ring buffer (88200 samples at 44100 Hz) provides sufficient runway for I/O stalls and GC pauses"
|
|
- "Source reads happen outside mutex lock to avoid blocking speaker callback"
|
|
- "Empty buffer returns silence rather than blocking or signaling end-of-stream"
|
|
- "Speaker buffer doubled from 100ms to 200ms as secondary underrun protection"
|
|
metrics:
|
|
duration: "10m 38s"
|
|
completed: "2026-03-05"
|
|
tasks: 2
|
|
files_changed: 3
|
|
---
|
|
|
|
# Quick Task 15: Fix Audio Glitches and Skips in Decoding Summary
|
|
|
|
Ring-buffer `BufferedStreamer` with goroutine read-ahead between decoder/resampler and speaker output, plus 200ms speaker buffer — eliminates glitches from disk I/O stalls, GC pauses, and CPU scheduling delays.
|
|
|
|
## Tasks Completed
|
|
|
|
| # | Task | Commit | Key Changes |
|
|
|---|------|--------|-------------|
|
|
| 1 | Create BufferedStreamer with goroutine read-ahead | 85b23ac | New `BufferedStreamer` type with ring buffer, read-ahead goroutine, silence-on-empty, Close() cleanup; 5 unit tests |
|
|
| 2 | Insert BufferedStreamer into player pipeline and increase speaker buffer | 8a0b16a | Chain: decode→resample→**BufferedStreamer**→ctrl→volume→speaker; speaker buffer 100ms→200ms; Close on unload/track-change |
|
|
|
|
## Implementation Details
|
|
|
|
### BufferedStreamer Design
|
|
|
|
- **Ring buffer**: Pre-allocated `[][2]float64` of configurable size (default 88200 samples ≈ 2 seconds at 44100 Hz)
|
|
- **Read-ahead goroutine**: Reads from source in 512-sample chunks outside the mutex, copies into ring under lock
|
|
- **Thread safety**: Mutex protects ring metadata only; source I/O never holds the lock, so the speaker goroutine is never blocked by disk
|
|
- **Empty buffer handling**: Returns silence (`len(samples), true`) when buffer temporarily empty — brief silence is far better than a glitch or premature track end
|
|
- **Shutdown**: `Close()` signals goroutine via channel; safe to call multiple times; called on track change and unload
|
|
|
|
### Player Pipeline Changes
|
|
|
|
- `buffered *BufferedStreamer` field added to Player struct
|
|
- Inserted between `beep.Resample` and `beep.Ctrl` in `updateStreamers()`
|
|
- `loadFileLocked()` closes old BufferedStreamer before loading new track
|
|
- `UnloadTrack()` closes and nils BufferedStreamer to prevent goroutine leaks
|
|
- Speaker buffer changed from `time.Second/10` (100ms) to `time.Second/5` (200ms)
|
|
|
|
### Lock Safety
|
|
|
|
No changes to lock ordering or mutex-sensitive code paths. The BufferedStreamer is self-contained and does not interact with `speaker.Lock()` or `p.mu`.
|
|
|
|
## Verification Results
|
|
|
|
- `go build ./backend/...` — PASS
|
|
- `go vet ./backend/player/...` — PASS
|
|
- `go test ./backend/player/ -v` — all 12 tests pass (5 BufferedStreamer + 7 existing)
|
|
|
|
## Deviations from Plan
|
|
|
|
None — plan executed exactly as written.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All created files exist, all commits verified.
|