detached 175a2c8

feat: add player RT fill path and underrun policy

commit
175a2c862c8b8c7c003116daa6709b2e0acf6610
author
brice · · 2026-04-09 15:34 UTC
parent
8096c50
signature
GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email
2 files · +619 -3
Split
UnifiedSplit
M internal/core/player.go +132 -3
@@ -2,6 +2,7 @@ package core
22
33 import (
44 "errors"
5+ "io"
56 "sync"
67 "sync/atomic"
78 )
@@ -11,14 +12,47 @@ var (
1112 ErrPlayerClosed = errors.New("player is closed")
1213 )
1314
15+// UnderrunPolicy determines how to handle underruns
16+type UnderrunPolicy int
17+
18+const (
19+ UnderrunFillSilence UnderrunPolicy = iota
20+ UnderrunFailFast
21+)
22+
23+// PCMBuffer represents a PCM audio buffer with deinterleaved samples
24+// Samples[channel][frame] format for cache efficiency
25+type PCMBuffer struct {
26+ Frames int
27+ Channels int
28+ Stride int
29+ Samples [][]float32
30+}
31+
32+// allocate allocates the Samples slice structure
33+func (b *PCMBuffer) allocate() {
34+ if b.Samples == nil {
35+ b.Samples = make([][]float32, b.Channels)
36+ for ch := 0; ch < b.Channels; ch++ {
37+ b.Samples[ch] = make([]float32, b.Frames)
38+ }
39+ }
40+}
41+
1442 // PlayerConfig holds configuration for the player
1543 type PlayerConfig struct {
16- // Minimal for now, will be extended in future tasks
44+ FramesPerBuffer int
45+ Channels int
46+ UnderrunPolicy UnderrunPolicy
1747 }
1848
1949 // PlayerCallbacks holds callbacks for player events
2050 type PlayerCallbacks struct {
2151 OnStateChange func(PlayerState)
52+ Fill func(*PCMBuffer) (int, error)
53+ OnUnderrun func(int)
54+ OnDrain func()
55+ OnError func(error)
2256 }
2357
2458 // playerConfig is the internal alias for PlayerConfig
@@ -57,6 +91,11 @@ func (p *player) setState(next PlayerState) {
5791 p.state.Store(int32(next))
5892 }
5993
94+// isPaused returns true if the player is paused
95+func (p *player) isPaused() bool {
96+ return p.paused.Load()
97+}
98+
6099 // transition attempts to transition to the next state
61100 func (p *player) transition(next PlayerState) error {
62101 p.mu.Lock()
@@ -93,9 +132,9 @@ func isValidTransition(current, next PlayerState) bool {
93132 case PlayerStateStarting:
94133 return next == PlayerStatePlaying || next == PlayerStateError
95134 case PlayerStatePlaying:
96- return next == PlayerStatePaused || next == PlayerStateStopped || next == PlayerStateClosing
135+ return next == PlayerStatePaused || next == PlayerStateStopped || next == PlayerStateClosing || next == PlayerStateError
97136 case PlayerStatePaused:
98- return next == PlayerStatePlaying || next == PlayerStateStopped || next == PlayerStateClosing
137+ return next == PlayerStatePlaying || next == PlayerStateStopped || next == PlayerStateClosing || next == PlayerStateError
99138 case PlayerStateStopped:
100139 return next == PlayerStateStarting || next == PlayerStateClosing
101140 case PlayerStateClosing:
@@ -220,6 +259,96 @@ func (p *player) teardown() {
220259 // Minimal placeholder - will be implemented in future tasks
221260 }
222261
262+// processPCM processes PCM audio data for the given buffer
263+// Returns the number of frames processed, or an error
264+func (p *player) processPCM(buf *PCMBuffer) (int, error) {
265+ // Ensure buffer is allocated
266+ buf.allocate()
267+
268+ state := p.State()
269+
270+ // If paused or stopped, fill with silence and return
271+ if state == PlayerStatePaused || state == PlayerStateStopped || state == PlayerStateIdle {
272+ p.fillSilence(buf, 0, buf.Frames)
273+ return buf.Frames, nil
274+ }
275+
276+ // If not playing, fill with silence
277+ if state != PlayerStatePlaying {
278+ p.fillSilence(buf, 0, buf.Frames)
279+ return buf.Frames, nil
280+ }
281+
282+ // Call Fill callback
283+ if p.callbacks.Fill == nil {
284+ p.fillSilence(buf, 0, buf.Frames)
285+ return buf.Frames, nil
286+ }
287+
288+ frames, err := p.callbacks.Fill(buf)
289+ if err != nil {
290+ if errors.Is(err, io.EOF) {
291+ // Drain condition - emit drain callback and return frames
292+ p.emitDrain()
293+ return frames, nil
294+ }
295+ // Other error - fail the player
296+ p.fail(err)
297+ return 0, err
298+ }
299+
300+ // Handle underrun if Fill returned fewer frames than requested
301+ if frames < buf.Frames {
302+ return p.handleUnderrun(buf, frames)
303+ }
304+
305+ return frames, nil
306+}
307+
308+// fillSilence fills the buffer with silence (0.0) from startFrame to endFrame
309+func (p *player) fillSilence(buf *PCMBuffer, startFrame, endFrame int) {
310+ for ch := 0; ch < buf.Channels; ch++ {
311+ for frame := startFrame; frame < endFrame && frame < len(buf.Samples[ch]); frame++ {
312+ buf.Samples[ch][frame] = 0.0
313+ }
314+ }
315+}
316+
317+// handleUnderrun applies the underrun policy when Fill returns fewer frames than requested
318+func (p *player) handleUnderrun(buf *PCMBuffer, filledFrames int) (int, error) {
319+ // Emit underrun callback
320+ if p.callbacks.OnUnderrun != nil {
321+ p.callbacks.OnUnderrun(buf.Frames - filledFrames)
322+ }
323+
324+ switch p.config.UnderrunPolicy {
325+ case UnderrunFailFast:
326+ err := errors.New("underrun occurred")
327+ p.fail(err)
328+ return 0, err
329+ case UnderrunFillSilence:
330+ fallthrough
331+ default:
332+ p.fillSilence(buf, filledFrames, buf.Frames)
333+ return buf.Frames, nil
334+ }
335+}
336+
337+// emitDrain invokes the OnDrain callback
338+func (p *player) emitDrain() {
339+ if p.callbacks.OnDrain != nil {
340+ p.callbacks.OnDrain()
341+ }
342+}
343+
344+// fail transitions the player to error state and invokes OnError
345+func (p *player) fail(err error) {
346+ p.transition(PlayerStateError)
347+ if p.callbacks.OnError != nil {
348+ p.callbacks.OnError(err)
349+ }
350+}
351+
223352 // Player is the exported wrapper for the internal player
224353 type Player struct {
225354 p *player
@@ -2,6 +2,7 @@ package core
2 2
3 import (3 import (
4 "errors"4 "errors"
5+ "io"
5 "sync"6 "sync"
6 "sync/atomic"7 "sync/atomic"
7 )8 )
@@ -11,14 +12,47 @@ var (
11 ErrPlayerClosed = errors.New("player is closed")12 ErrPlayerClosed = errors.New("player is closed")
12 )13 )
13 14
15+// UnderrunPolicy determines how to handle underruns
16+type UnderrunPolicy int
17+
18+const (
19+ UnderrunFillSilence UnderrunPolicy = iota
20+ UnderrunFailFast
21+)
22+
23+// PCMBuffer represents a PCM audio buffer with deinterleaved samples
24+// Samples[channel][frame] format for cache efficiency
25+type PCMBuffer struct {
26+ Frames int
27+ Channels int
28+ Stride int
29+ Samples [][]float32
30+}
31+
32+// allocate allocates the Samples slice structure
33+func (b *PCMBuffer) allocate() {
34+ if b.Samples == nil {
35+ b.Samples = make([][]float32, b.Channels)
36+ for ch := 0; ch < b.Channels; ch++ {
37+ b.Samples[ch] = make([]float32, b.Frames)
38+ }
39+ }
40+}
41+
14 // PlayerConfig holds configuration for the player42 // PlayerConfig holds configuration for the player
15 type PlayerConfig struct {43 type PlayerConfig struct {
16- // Minimal for now, will be extended in future tasks44+ FramesPerBuffer int
45+ Channels int
46+ UnderrunPolicy UnderrunPolicy
17 }47 }
18 48
19 // PlayerCallbacks holds callbacks for player events49 // PlayerCallbacks holds callbacks for player events
20 type PlayerCallbacks struct {50 type PlayerCallbacks struct {
21 OnStateChange func(PlayerState)51 OnStateChange func(PlayerState)
52+ Fill func(*PCMBuffer) (int, error)
53+ OnUnderrun func(int)
54+ OnDrain func()
55+ OnError func(error)
22 }56 }
23 57
24 // playerConfig is the internal alias for PlayerConfig58 // playerConfig is the internal alias for PlayerConfig
@@ -57,6 +91,11 @@ func (p *player) setState(next PlayerState) {
57 p.state.Store(int32(next))91 p.state.Store(int32(next))
58 }92 }
59 93
94+// isPaused returns true if the player is paused
95+func (p *player) isPaused() bool {
96+ return p.paused.Load()
97+}
98+
60 // transition attempts to transition to the next state99 // transition attempts to transition to the next state
61 func (p *player) transition(next PlayerState) error {100 func (p *player) transition(next PlayerState) error {
62 p.mu.Lock()101 p.mu.Lock()
@@ -93,9 +132,9 @@ func isValidTransition(current, next PlayerState) bool {
93 case PlayerStateStarting:132 case PlayerStateStarting:
94 return next == PlayerStatePlaying || next == PlayerStateError133 return next == PlayerStatePlaying || next == PlayerStateError
95 case PlayerStatePlaying:134 case PlayerStatePlaying:
96- return next == PlayerStatePaused || next == PlayerStateStopped || next == PlayerStateClosing135+ return next == PlayerStatePaused || next == PlayerStateStopped || next == PlayerStateClosing || next == PlayerStateError
97 case PlayerStatePaused:136 case PlayerStatePaused:
98- return next == PlayerStatePlaying || next == PlayerStateStopped || next == PlayerStateClosing137+ return next == PlayerStatePlaying || next == PlayerStateStopped || next == PlayerStateClosing || next == PlayerStateError
99 case PlayerStateStopped:138 case PlayerStateStopped:
100 return next == PlayerStateStarting || next == PlayerStateClosing139 return next == PlayerStateStarting || next == PlayerStateClosing
101 case PlayerStateClosing:140 case PlayerStateClosing:
@@ -220,6 +259,96 @@ func (p *player) teardown() {
220 // Minimal placeholder - will be implemented in future tasks259 // Minimal placeholder - will be implemented in future tasks
221 }260 }
222 261
262+// processPCM processes PCM audio data for the given buffer
263+// Returns the number of frames processed, or an error
264+func (p *player) processPCM(buf *PCMBuffer) (int, error) {
265+ // Ensure buffer is allocated
266+ buf.allocate()
267+
268+ state := p.State()
269+
270+ // If paused or stopped, fill with silence and return
271+ if state == PlayerStatePaused || state == PlayerStateStopped || state == PlayerStateIdle {
272+ p.fillSilence(buf, 0, buf.Frames)
273+ return buf.Frames, nil
274+ }
275+
276+ // If not playing, fill with silence
277+ if state != PlayerStatePlaying {
278+ p.fillSilence(buf, 0, buf.Frames)
279+ return buf.Frames, nil
280+ }
281+
282+ // Call Fill callback
283+ if p.callbacks.Fill == nil {
284+ p.fillSilence(buf, 0, buf.Frames)
285+ return buf.Frames, nil
286+ }
287+
288+ frames, err := p.callbacks.Fill(buf)
289+ if err != nil {
290+ if errors.Is(err, io.EOF) {
291+ // Drain condition - emit drain callback and return frames
292+ p.emitDrain()
293+ return frames, nil
294+ }
295+ // Other error - fail the player
296+ p.fail(err)
297+ return 0, err
298+ }
299+
300+ // Handle underrun if Fill returned fewer frames than requested
301+ if frames < buf.Frames {
302+ return p.handleUnderrun(buf, frames)
303+ }
304+
305+ return frames, nil
306+}
307+
308+// fillSilence fills the buffer with silence (0.0) from startFrame to endFrame
309+func (p *player) fillSilence(buf *PCMBuffer, startFrame, endFrame int) {
310+ for ch := 0; ch < buf.Channels; ch++ {
311+ for frame := startFrame; frame < endFrame && frame < len(buf.Samples[ch]); frame++ {
312+ buf.Samples[ch][frame] = 0.0
313+ }
314+ }
315+}
316+
317+// handleUnderrun applies the underrun policy when Fill returns fewer frames than requested
318+func (p *player) handleUnderrun(buf *PCMBuffer, filledFrames int) (int, error) {
319+ // Emit underrun callback
320+ if p.callbacks.OnUnderrun != nil {
321+ p.callbacks.OnUnderrun(buf.Frames - filledFrames)
322+ }
323+
324+ switch p.config.UnderrunPolicy {
325+ case UnderrunFailFast:
326+ err := errors.New("underrun occurred")
327+ p.fail(err)
328+ return 0, err
329+ case UnderrunFillSilence:
330+ fallthrough
331+ default:
332+ p.fillSilence(buf, filledFrames, buf.Frames)
333+ return buf.Frames, nil
334+ }
335+}
336+
337+// emitDrain invokes the OnDrain callback
338+func (p *player) emitDrain() {
339+ if p.callbacks.OnDrain != nil {
340+ p.callbacks.OnDrain()
341+ }
342+}
343+
344+// fail transitions the player to error state and invokes OnError
345+func (p *player) fail(err error) {
346+ p.transition(PlayerStateError)
347+ if p.callbacks.OnError != nil {
348+ p.callbacks.OnError(err)
349+ }
350+}
351+
223 // Player is the exported wrapper for the internal player352 // Player is the exported wrapper for the internal player
224 type Player struct {353 type Player struct {
225 p *player354 p *player
A internal/core/player_rt_test.go +487 -0
@@ -0,0 +1,487 @@
1+package core
2+
3+import (
4+ "errors"
5+ "io"
6+ "testing"
7+)
8+
9+// TestProcessCallbackSilenceFillUnderrun tests that when Fill returns fewer frames
10+// than requested, the remaining frames are filled with silence
11+func TestProcessCallbackSilenceFillUnderrun(t *testing.T) {
12+ fillCallCount := 0
13+ var receivedBuf *PCMBuffer
14+
15+ p := newPlayer(
16+ PlayerConfig{
17+ FramesPerBuffer: 4,
18+ Channels: 2,
19+ UnderrunPolicy: UnderrunFillSilence,
20+ },
21+ PlayerCallbacks{
22+ Fill: func(buf *PCMBuffer) (int, error) {
23+ fillCallCount++
24+ receivedBuf = buf
25+ // Return only 2 frames, leaving 2 frames as underrun
26+ return 2, nil
27+ },
28+ },
29+ )
30+
31+ // Set player to playing state
32+ p.setState(PlayerStatePlaying)
33+
34+ buf := &PCMBuffer{
35+ Frames: 4,
36+ Channels: 2,
37+ }
38+ buf.allocate()
39+
40+ frames, err := p.processPCM(buf)
41+ if err != nil {
42+ t.Fatalf("processPCM returned error: %v", err)
43+ }
44+
45+ if frames != 4 {
46+ t.Errorf("processPCM returned %d frames, want 4", frames)
47+ }
48+
49+ if fillCallCount != 1 {
50+ t.Errorf("Fill callback called %d times, want 1", fillCallCount)
51+ }
52+
53+ // Verify the buffer was silence-filled
54+ // Frames 0-1 should have data (we don't verify the actual values since Fill could write anything)
55+ // Frames 2-3 should be silence (0.0)
56+ for ch := 0; ch < 2; ch++ {
57+ for frame := 2; frame < 4; frame++ {
58+ if buf.Samples[ch][frame] != 0.0 {
59+ t.Errorf("Expected silence at channel %d frame %d, got %f", ch, frame, buf.Samples[ch][frame])
60+ }
61+ }
62+ }
63+
64+ if receivedBuf != buf {
65+ t.Error("Fill callback received different buffer than passed to processPCM")
66+ }
67+}
68+
69+// TestProcessCallbackFailFastUnderrun tests that when configured to fail on underrun,
70+// the player transitions to error state and invokes OnError callback
71+func TestProcessCallbackFailFastUnderrun(t *testing.T) {
72+ errCalled := false
73+ var errReceived error
74+
75+ p := newPlayer(
76+ PlayerConfig{
77+ FramesPerBuffer: 4,
78+ Channels: 2,
79+ UnderrunPolicy: UnderrunFailFast,
80+ },
81+ PlayerCallbacks{
82+ Fill: func(buf *PCMBuffer) (int, error) {
83+ // Return only 2 frames, triggering underrun
84+ return 2, nil
85+ },
86+ OnError: func(err error) {
87+ errCalled = true
88+ errReceived = err
89+ },
90+ },
91+ )
92+
93+ // Set player to playing state
94+ p.setState(PlayerStatePlaying)
95+
96+ buf := &PCMBuffer{
97+ Frames: 4,
98+ Channels: 2,
99+ }
100+ buf.allocate()
101+
102+ _, err := p.processPCM(buf)
103+ if err == nil {
104+ t.Fatal("processPCM should have returned error for underrun with FailFast policy")
105+ }
106+
107+ if p.State() != PlayerStateError {
108+ t.Errorf("expected state Error after underrun, got %v", p.State())
109+ }
110+
111+ if !errCalled {
112+ t.Error("OnError callback was not called")
113+ }
114+
115+ if errReceived == nil {
116+ t.Error("OnError callback received nil error")
117+ }
118+}
119+
120+// TestProcessCallbackPausedSuppressesFillAndEmitsSilence tests that when paused,
121+// Fill is not called and the buffer is filled with silence
122+func TestProcessCallbackPausedSuppressesFillAndEmitsSilence(t *testing.T) {
123+ fillCallCount := 0
124+
125+ p := newPlayer(
126+ PlayerConfig{
127+ FramesPerBuffer: 4,
128+ Channels: 2,
129+ UnderrunPolicy: UnderrunFillSilence,
130+ },
131+ PlayerCallbacks{
132+ Fill: func(buf *PCMBuffer) (int, error) {
133+ fillCallCount++
134+ return 4, nil
135+ },
136+ },
137+ )
138+
139+ // Set player to paused state
140+ p.setState(PlayerStatePaused)
141+
142+ buf := &PCMBuffer{
143+ Frames: 4,
144+ Channels: 2,
145+ }
146+ buf.allocate()
147+
148+ frames, err := p.processPCM(buf)
149+ if err != nil {
150+ t.Fatalf("processPCM returned error: %v", err)
151+ }
152+
153+ if frames != 4 {
154+ t.Errorf("processPCM returned %d frames, want 4", frames)
155+ }
156+
157+ if fillCallCount != 0 {
158+ t.Errorf("Fill callback called %d times while paused, want 0", fillCallCount)
159+ }
160+
161+ // Verify the entire buffer is silence
162+ for ch := 0; ch < 2; ch++ {
163+ for frame := 0; frame < 4; frame++ {
164+ if buf.Samples[ch][frame] != 0.0 {
165+ t.Errorf("Expected silence at channel %d frame %d while paused, got %f", ch, frame, buf.Samples[ch][frame])
166+ }
167+ }
168+ }
169+}
170+
171+// TestProcessCallbackStoppedFillsSilence tests that when stopped,
172+// Fill is not called and the buffer is filled with silence
173+func TestProcessCallbackStoppedFillsSilence(t *testing.T) {
174+ fillCallCount := 0
175+
176+ p := newPlayer(
177+ PlayerConfig{
178+ FramesPerBuffer: 4,
179+ Channels: 2,
180+ UnderrunPolicy: UnderrunFillSilence,
181+ },
182+ PlayerCallbacks{
183+ Fill: func(buf *PCMBuffer) (int, error) {
184+ fillCallCount++
185+ return 4, nil
186+ },
187+ },
188+ )
189+
190+ // Set player to stopped state
191+ p.setState(PlayerStateStopped)
192+
193+ buf := &PCMBuffer{
194+ Frames: 4,
195+ Channels: 2,
196+ }
197+ buf.allocate()
198+
199+ frames, err := p.processPCM(buf)
200+ if err != nil {
201+ t.Fatalf("processPCM returned error: %v", err)
202+ }
203+
204+ if frames != 4 {
205+ t.Errorf("processPCM returned %d frames, want 4", frames)
206+ }
207+
208+ if fillCallCount != 0 {
209+ t.Errorf("Fill callback called %d times while stopped, want 0", fillCallCount)
210+ }
211+
212+ // Verify the entire buffer is silence
213+ for ch := 0; ch < 2; ch++ {
214+ for frame := 0; frame < 4; frame++ {
215+ if buf.Samples[ch][frame] != 0.0 {
216+ t.Errorf("Expected silence at channel %d frame %d while stopped, got %f", ch, frame, buf.Samples[ch][frame])
217+ }
218+ }
219+ }
220+}
221+
222+// TestProcessCallbackDrainOnEOF tests that io.EOF from Fill triggers drain callback
223+func TestProcessCallbackDrainOnEOF(t *testing.T) {
224+ drainCalled := false
225+ fillCallCount := 0
226+
227+ p := newPlayer(
228+ PlayerConfig{
229+ FramesPerBuffer: 4,
230+ Channels: 2,
231+ UnderrunPolicy: UnderrunFillSilence,
232+ },
233+ PlayerCallbacks{
234+ Fill: func(buf *PCMBuffer) (int, error) {
235+ fillCallCount++
236+ // Return EOF to signal drain
237+ return 2, io.EOF
238+ },
239+ OnDrain: func() {
240+ drainCalled = true
241+ },
242+ },
243+ )
244+
245+ // Set player to playing state
246+ p.setState(PlayerStatePlaying)
247+
248+ buf := &PCMBuffer{
249+ Frames: 4,
250+ Channels: 2,
251+ }
252+ buf.allocate()
253+
254+ frames, err := p.processPCM(buf)
255+ if err != nil {
256+ t.Fatalf("processPCM returned error: %v", err)
257+ }
258+
259+ if frames != 2 {
260+ t.Errorf("processPCM returned %d frames, want 2", frames)
261+ }
262+
263+ if !drainCalled {
264+ t.Error("OnDrain callback was not called on io.EOF")
265+ }
266+
267+ if fillCallCount != 1 {
268+ t.Errorf("Fill callback called %d times, want 1", fillCallCount)
269+ }
270+}
271+
272+// TestProcessCallbackErrorHandling tests that errors from Fill (other than EOF)
273+// fail the player and invoke OnError callback
274+func TestProcessCallbackErrorHandling(t *testing.T) {
275+ testErr := errors.New("fill error")
276+ errCalled := false
277+ var errReceived error
278+
279+ p := newPlayer(
280+ PlayerConfig{
281+ FramesPerBuffer: 4,
282+ Channels: 2,
283+ UnderrunPolicy: UnderrunFillSilence,
284+ },
285+ PlayerCallbacks{
286+ Fill: func(buf *PCMBuffer) (int, error) {
287+ return 0, testErr
288+ },
289+ OnError: func(err error) {
290+ errCalled = true
291+ errReceived = err
292+ },
293+ },
294+ )
295+
296+ // Set player to playing state
297+ p.setState(PlayerStatePlaying)
298+
299+ buf := &PCMBuffer{
300+ Frames: 4,
301+ Channels: 2,
302+ }
303+ buf.allocate()
304+
305+ _, err := p.processPCM(buf)
306+ if err == nil {
307+ t.Fatal("processPCM should have returned error")
308+ }
309+
310+ if p.State() != PlayerStateError {
311+ t.Errorf("expected state Error after fill error, got %v", p.State())
312+ }
313+
314+ if !errCalled {
315+ t.Error("OnError callback was not called")
316+ }
317+
318+ if !errors.Is(errReceived, testErr) {
319+ t.Errorf("OnError received error %v, want %v", errReceived, testErr)
320+ }
321+}
322+
323+// TestProcessCallbackIdleFillsSilence tests that when idle,
324+// Fill is not called and the buffer is filled with silence
325+func TestProcessCallbackIdleFillsSilence(t *testing.T) {
326+ fillCallCount := 0
327+
328+ p := newPlayer(
329+ PlayerConfig{
330+ FramesPerBuffer: 4,
331+ Channels: 2,
332+ UnderrunPolicy: UnderrunFillSilence,
333+ },
334+ PlayerCallbacks{
335+ Fill: func(buf *PCMBuffer) (int, error) {
336+ fillCallCount++
337+ return 4, nil
338+ },
339+ },
340+ )
341+
342+ // Player starts in Idle state
343+ buf := &PCMBuffer{
344+ Frames: 4,
345+ Channels: 2,
346+ }
347+ buf.allocate()
348+
349+ frames, err := p.processPCM(buf)
350+ if err != nil {
351+ t.Fatalf("processPCM returned error: %v", err)
352+ }
353+
354+ if frames != 4 {
355+ t.Errorf("processPCM returned %d frames, want 4", frames)
356+ }
357+
358+ if fillCallCount != 0 {
359+ t.Errorf("Fill callback called %d times while idle, want 0", fillCallCount)
360+ }
361+}
362+
363+// TestProcessCallbackUnderrunCallback tests that OnUnderrun is called when underrun occurs
364+func TestProcessCallbackUnderrunCallback(t *testing.T) {
365+ underrunCalled := false
366+ underrunFrames := 0
367+
368+ p := newPlayer(
369+ PlayerConfig{
370+ FramesPerBuffer: 4,
371+ Channels: 2,
372+ UnderrunPolicy: UnderrunFillSilence,
373+ },
374+ PlayerCallbacks{
375+ Fill: func(buf *PCMBuffer) (int, error) {
376+ return 2, nil
377+ },
378+ OnUnderrun: func(frames int) {
379+ underrunCalled = true
380+ underrunFrames = frames
381+ },
382+ },
383+ )
384+
385+ // Set player to playing state
386+ p.setState(PlayerStatePlaying)
387+
388+ buf := &PCMBuffer{
389+ Frames: 4,
390+ Channels: 2,
391+ }
392+ buf.allocate()
393+
394+ _, err := p.processPCM(buf)
395+ if err != nil {
396+ t.Fatalf("processPCM returned error: %v", err)
397+ }
398+
399+ if !underrunCalled {
400+ t.Error("OnUnderrun callback was not called")
401+ }
402+
403+ if underrunFrames != 2 {
404+ t.Errorf("OnUnderrun received %d frames, want 2", underrunFrames)
405+ }
406+}
407+
408+// TestProcessCallbackFillReturnsFullFrames tests normal operation when Fill returns all requested frames
409+func TestProcessCallbackFillReturnsFullFrames(t *testing.T) {
410+ fillCallCount := 0
411+
412+ p := newPlayer(
413+ PlayerConfig{
414+ FramesPerBuffer: 4,
415+ Channels: 2,
416+ UnderrunPolicy: UnderrunFillSilence,
417+ },
418+ PlayerCallbacks{
419+ Fill: func(buf *PCMBuffer) (int, error) {
420+ fillCallCount++
421+ // Write some data to verify Fill was called
422+ for ch := 0; ch < buf.Channels; ch++ {
423+ for frame := 0; frame < buf.Frames; frame++ {
424+ buf.Samples[ch][frame] = float32(frame + ch*10)
425+ }
426+ }
427+ return 4, nil
428+ },
429+ },
430+ )
431+
432+ // Set player to playing state
433+ p.setState(PlayerStatePlaying)
434+
435+ buf := &PCMBuffer{
436+ Frames: 4,
437+ Channels: 2,
438+ }
439+ buf.allocate()
440+
441+ frames, err := p.processPCM(buf)
442+ if err != nil {
443+ t.Fatalf("processPCM returned error: %v", err)
444+ }
445+
446+ if frames != 4 {
447+ t.Errorf("processPCM returned %d frames, want 4", frames)
448+ }
449+
450+ if fillCallCount != 1 {
451+ t.Errorf("Fill callback called %d times, want 1", fillCallCount)
452+ }
453+
454+ // Verify the data was written by Fill
455+ for ch := 0; ch < 2; ch++ {
456+ for frame := 0; frame < 4; frame++ {
457+ expected := float32(frame + ch*10)
458+ if buf.Samples[ch][frame] != expected {
459+ t.Errorf("Expected %f at channel %d frame %d, got %f", expected, ch, frame, buf.Samples[ch][frame])
460+ }
461+ }
462+ }
463+}
464+
465+// TestPCMBufferAllocate tests the allocate method
466+func TestPCMBufferAllocate(t *testing.T) {
467+ buf := &PCMBuffer{
468+ Frames: 4,
469+ Channels: 2,
470+ }
471+
472+ buf.allocate()
473+
474+ if buf.Samples == nil {
475+ t.Fatal("Samples is nil after allocate")
476+ }
477+
478+ if len(buf.Samples) != 2 {
479+ t.Errorf("len(Samples) = %d, want 2", len(buf.Samples))
480+ }
481+
482+ for ch := 0; ch < 2; ch++ {
483+ if len(buf.Samples[ch]) != 4 {
484+ t.Errorf("len(Samples[%d]) = %d, want 4", ch, len(buf.Samples[ch]))
485+ }
486+ }
487+}
@@ -0,0 +1,487 @@
1+package core
2+
3+import (
4+ "errors"
5+ "io"
6+ "testing"
7+)
8+
9+// TestProcessCallbackSilenceFillUnderrun tests that when Fill returns fewer frames
10+// than requested, the remaining frames are filled with silence
11+func TestProcessCallbackSilenceFillUnderrun(t *testing.T) {
12+ fillCallCount := 0
13+ var receivedBuf *PCMBuffer
14+
15+ p := newPlayer(
16+ PlayerConfig{
17+ FramesPerBuffer: 4,
18+ Channels: 2,
19+ UnderrunPolicy: UnderrunFillSilence,
20+ },
21+ PlayerCallbacks{
22+ Fill: func(buf *PCMBuffer) (int, error) {
23+ fillCallCount++
24+ receivedBuf = buf
25+ // Return only 2 frames, leaving 2 frames as underrun
26+ return 2, nil
27+ },
28+ },
29+ )
30+
31+ // Set player to playing state
32+ p.setState(PlayerStatePlaying)
33+
34+ buf := &PCMBuffer{
35+ Frames: 4,
36+ Channels: 2,
37+ }
38+ buf.allocate()
39+
40+ frames, err := p.processPCM(buf)
41+ if err != nil {
42+ t.Fatalf("processPCM returned error: %v", err)
43+ }
44+
45+ if frames != 4 {
46+ t.Errorf("processPCM returned %d frames, want 4", frames)
47+ }
48+
49+ if fillCallCount != 1 {
50+ t.Errorf("Fill callback called %d times, want 1", fillCallCount)
51+ }
52+
53+ // Verify the buffer was silence-filled
54+ // Frames 0-1 should have data (we don't verify the actual values since Fill could write anything)
55+ // Frames 2-3 should be silence (0.0)
56+ for ch := 0; ch < 2; ch++ {
57+ for frame := 2; frame < 4; frame++ {
58+ if buf.Samples[ch][frame] != 0.0 {
59+ t.Errorf("Expected silence at channel %d frame %d, got %f", ch, frame, buf.Samples[ch][frame])
60+ }
61+ }
62+ }
63+
64+ if receivedBuf != buf {
65+ t.Error("Fill callback received different buffer than passed to processPCM")
66+ }
67+}
68+
69+// TestProcessCallbackFailFastUnderrun tests that when configured to fail on underrun,
70+// the player transitions to error state and invokes OnError callback
71+func TestProcessCallbackFailFastUnderrun(t *testing.T) {
72+ errCalled := false
73+ var errReceived error
74+
75+ p := newPlayer(
76+ PlayerConfig{
77+ FramesPerBuffer: 4,
78+ Channels: 2,
79+ UnderrunPolicy: UnderrunFailFast,
80+ },
81+ PlayerCallbacks{
82+ Fill: func(buf *PCMBuffer) (int, error) {
83+ // Return only 2 frames, triggering underrun
84+ return 2, nil
85+ },
86+ OnError: func(err error) {
87+ errCalled = true
88+ errReceived = err
89+ },
90+ },
91+ )
92+
93+ // Set player to playing state
94+ p.setState(PlayerStatePlaying)
95+
96+ buf := &PCMBuffer{
97+ Frames: 4,
98+ Channels: 2,
99+ }
100+ buf.allocate()
101+
102+ _, err := p.processPCM(buf)
103+ if err == nil {
104+ t.Fatal("processPCM should have returned error for underrun with FailFast policy")
105+ }
106+
107+ if p.State() != PlayerStateError {
108+ t.Errorf("expected state Error after underrun, got %v", p.State())
109+ }
110+
111+ if !errCalled {
112+ t.Error("OnError callback was not called")
113+ }
114+
115+ if errReceived == nil {
116+ t.Error("OnError callback received nil error")
117+ }
118+}
119+
120+// TestProcessCallbackPausedSuppressesFillAndEmitsSilence tests that when paused,
121+// Fill is not called and the buffer is filled with silence
122+func TestProcessCallbackPausedSuppressesFillAndEmitsSilence(t *testing.T) {
123+ fillCallCount := 0
124+
125+ p := newPlayer(
126+ PlayerConfig{
127+ FramesPerBuffer: 4,
128+ Channels: 2,
129+ UnderrunPolicy: UnderrunFillSilence,
130+ },
131+ PlayerCallbacks{
132+ Fill: func(buf *PCMBuffer) (int, error) {
133+ fillCallCount++
134+ return 4, nil
135+ },
136+ },
137+ )
138+
139+ // Set player to paused state
140+ p.setState(PlayerStatePaused)
141+
142+ buf := &PCMBuffer{
143+ Frames: 4,
144+ Channels: 2,
145+ }
146+ buf.allocate()
147+
148+ frames, err := p.processPCM(buf)
149+ if err != nil {
150+ t.Fatalf("processPCM returned error: %v", err)
151+ }
152+
153+ if frames != 4 {
154+ t.Errorf("processPCM returned %d frames, want 4", frames)
155+ }
156+
157+ if fillCallCount != 0 {
158+ t.Errorf("Fill callback called %d times while paused, want 0", fillCallCount)
159+ }
160+
161+ // Verify the entire buffer is silence
162+ for ch := 0; ch < 2; ch++ {
163+ for frame := 0; frame < 4; frame++ {
164+ if buf.Samples[ch][frame] != 0.0 {
165+ t.Errorf("Expected silence at channel %d frame %d while paused, got %f", ch, frame, buf.Samples[ch][frame])
166+ }
167+ }
168+ }
169+}
170+
171+// TestProcessCallbackStoppedFillsSilence tests that when stopped,
172+// Fill is not called and the buffer is filled with silence
173+func TestProcessCallbackStoppedFillsSilence(t *testing.T) {
174+ fillCallCount := 0
175+
176+ p := newPlayer(
177+ PlayerConfig{
178+ FramesPerBuffer: 4,
179+ Channels: 2,
180+ UnderrunPolicy: UnderrunFillSilence,
181+ },
182+ PlayerCallbacks{
183+ Fill: func(buf *PCMBuffer) (int, error) {
184+ fillCallCount++
185+ return 4, nil
186+ },
187+ },
188+ )
189+
190+ // Set player to stopped state
191+ p.setState(PlayerStateStopped)
192+
193+ buf := &PCMBuffer{
194+ Frames: 4,
195+ Channels: 2,
196+ }
197+ buf.allocate()
198+
199+ frames, err := p.processPCM(buf)
200+ if err != nil {
201+ t.Fatalf("processPCM returned error: %v", err)
202+ }
203+
204+ if frames != 4 {
205+ t.Errorf("processPCM returned %d frames, want 4", frames)
206+ }
207+
208+ if fillCallCount != 0 {
209+ t.Errorf("Fill callback called %d times while stopped, want 0", fillCallCount)
210+ }
211+
212+ // Verify the entire buffer is silence
213+ for ch := 0; ch < 2; ch++ {
214+ for frame := 0; frame < 4; frame++ {
215+ if buf.Samples[ch][frame] != 0.0 {
216+ t.Errorf("Expected silence at channel %d frame %d while stopped, got %f", ch, frame, buf.Samples[ch][frame])
217+ }
218+ }
219+ }
220+}
221+
222+// TestProcessCallbackDrainOnEOF tests that io.EOF from Fill triggers drain callback
223+func TestProcessCallbackDrainOnEOF(t *testing.T) {
224+ drainCalled := false
225+ fillCallCount := 0
226+
227+ p := newPlayer(
228+ PlayerConfig{
229+ FramesPerBuffer: 4,
230+ Channels: 2,
231+ UnderrunPolicy: UnderrunFillSilence,
232+ },
233+ PlayerCallbacks{
234+ Fill: func(buf *PCMBuffer) (int, error) {
235+ fillCallCount++
236+ // Return EOF to signal drain
237+ return 2, io.EOF
238+ },
239+ OnDrain: func() {
240+ drainCalled = true
241+ },
242+ },
243+ )
244+
245+ // Set player to playing state
246+ p.setState(PlayerStatePlaying)
247+
248+ buf := &PCMBuffer{
249+ Frames: 4,
250+ Channels: 2,
251+ }
252+ buf.allocate()
253+
254+ frames, err := p.processPCM(buf)
255+ if err != nil {
256+ t.Fatalf("processPCM returned error: %v", err)
257+ }
258+
259+ if frames != 2 {
260+ t.Errorf("processPCM returned %d frames, want 2", frames)
261+ }
262+
263+ if !drainCalled {
264+ t.Error("OnDrain callback was not called on io.EOF")
265+ }
266+
267+ if fillCallCount != 1 {
268+ t.Errorf("Fill callback called %d times, want 1", fillCallCount)
269+ }
270+}
271+
272+// TestProcessCallbackErrorHandling tests that errors from Fill (other than EOF)
273+// fail the player and invoke OnError callback
274+func TestProcessCallbackErrorHandling(t *testing.T) {
275+ testErr := errors.New("fill error")
276+ errCalled := false
277+ var errReceived error
278+
279+ p := newPlayer(
280+ PlayerConfig{
281+ FramesPerBuffer: 4,
282+ Channels: 2,
283+ UnderrunPolicy: UnderrunFillSilence,
284+ },
285+ PlayerCallbacks{
286+ Fill: func(buf *PCMBuffer) (int, error) {
287+ return 0, testErr
288+ },
289+ OnError: func(err error) {
290+ errCalled = true
291+ errReceived = err
292+ },
293+ },
294+ )
295+
296+ // Set player to playing state
297+ p.setState(PlayerStatePlaying)
298+
299+ buf := &PCMBuffer{
300+ Frames: 4,
301+ Channels: 2,
302+ }
303+ buf.allocate()
304+
305+ _, err := p.processPCM(buf)
306+ if err == nil {
307+ t.Fatal("processPCM should have returned error")
308+ }
309+
310+ if p.State() != PlayerStateError {
311+ t.Errorf("expected state Error after fill error, got %v", p.State())
312+ }
313+
314+ if !errCalled {
315+ t.Error("OnError callback was not called")
316+ }
317+
318+ if !errors.Is(errReceived, testErr) {
319+ t.Errorf("OnError received error %v, want %v", errReceived, testErr)
320+ }
321+}
322+
323+// TestProcessCallbackIdleFillsSilence tests that when idle,
324+// Fill is not called and the buffer is filled with silence
325+func TestProcessCallbackIdleFillsSilence(t *testing.T) {
326+ fillCallCount := 0
327+
328+ p := newPlayer(
329+ PlayerConfig{
330+ FramesPerBuffer: 4,
331+ Channels: 2,
332+ UnderrunPolicy: UnderrunFillSilence,
333+ },
334+ PlayerCallbacks{
335+ Fill: func(buf *PCMBuffer) (int, error) {
336+ fillCallCount++
337+ return 4, nil
338+ },
339+ },
340+ )
341+
342+ // Player starts in Idle state
343+ buf := &PCMBuffer{
344+ Frames: 4,
345+ Channels: 2,
346+ }
347+ buf.allocate()
348+
349+ frames, err := p.processPCM(buf)
350+ if err != nil {
351+ t.Fatalf("processPCM returned error: %v", err)
352+ }
353+
354+ if frames != 4 {
355+ t.Errorf("processPCM returned %d frames, want 4", frames)
356+ }
357+
358+ if fillCallCount != 0 {
359+ t.Errorf("Fill callback called %d times while idle, want 0", fillCallCount)
360+ }
361+}
362+
363+// TestProcessCallbackUnderrunCallback tests that OnUnderrun is called when underrun occurs
364+func TestProcessCallbackUnderrunCallback(t *testing.T) {
365+ underrunCalled := false
366+ underrunFrames := 0
367+
368+ p := newPlayer(
369+ PlayerConfig{
370+ FramesPerBuffer: 4,
371+ Channels: 2,
372+ UnderrunPolicy: UnderrunFillSilence,
373+ },
374+ PlayerCallbacks{
375+ Fill: func(buf *PCMBuffer) (int, error) {
376+ return 2, nil
377+ },
378+ OnUnderrun: func(frames int) {
379+ underrunCalled = true
380+ underrunFrames = frames
381+ },
382+ },
383+ )
384+
385+ // Set player to playing state
386+ p.setState(PlayerStatePlaying)
387+
388+ buf := &PCMBuffer{
389+ Frames: 4,
390+ Channels: 2,
391+ }
392+ buf.allocate()
393+
394+ _, err := p.processPCM(buf)
395+ if err != nil {
396+ t.Fatalf("processPCM returned error: %v", err)
397+ }
398+
399+ if !underrunCalled {
400+ t.Error("OnUnderrun callback was not called")
401+ }
402+
403+ if underrunFrames != 2 {
404+ t.Errorf("OnUnderrun received %d frames, want 2", underrunFrames)
405+ }
406+}
407+
408+// TestProcessCallbackFillReturnsFullFrames tests normal operation when Fill returns all requested frames
409+func TestProcessCallbackFillReturnsFullFrames(t *testing.T) {
410+ fillCallCount := 0
411+
412+ p := newPlayer(
413+ PlayerConfig{
414+ FramesPerBuffer: 4,
415+ Channels: 2,
416+ UnderrunPolicy: UnderrunFillSilence,
417+ },
418+ PlayerCallbacks{
419+ Fill: func(buf *PCMBuffer) (int, error) {
420+ fillCallCount++
421+ // Write some data to verify Fill was called
422+ for ch := 0; ch < buf.Channels; ch++ {
423+ for frame := 0; frame < buf.Frames; frame++ {
424+ buf.Samples[ch][frame] = float32(frame + ch*10)
425+ }
426+ }
427+ return 4, nil
428+ },
429+ },
430+ )
431+
432+ // Set player to playing state
433+ p.setState(PlayerStatePlaying)
434+
435+ buf := &PCMBuffer{
436+ Frames: 4,
437+ Channels: 2,
438+ }
439+ buf.allocate()
440+
441+ frames, err := p.processPCM(buf)
442+ if err != nil {
443+ t.Fatalf("processPCM returned error: %v", err)
444+ }
445+
446+ if frames != 4 {
447+ t.Errorf("processPCM returned %d frames, want 4", frames)
448+ }
449+
450+ if fillCallCount != 1 {
451+ t.Errorf("Fill callback called %d times, want 1", fillCallCount)
452+ }
453+
454+ // Verify the data was written by Fill
455+ for ch := 0; ch < 2; ch++ {
456+ for frame := 0; frame < 4; frame++ {
457+ expected := float32(frame + ch*10)
458+ if buf.Samples[ch][frame] != expected {
459+ t.Errorf("Expected %f at channel %d frame %d, got %f", expected, ch, frame, buf.Samples[ch][frame])
460+ }
461+ }
462+ }
463+}
464+
465+// TestPCMBufferAllocate tests the allocate method
466+func TestPCMBufferAllocate(t *testing.T) {
467+ buf := &PCMBuffer{
468+ Frames: 4,
469+ Channels: 2,
470+ }
471+
472+ buf.allocate()
473+
474+ if buf.Samples == nil {
475+ t.Fatal("Samples is nil after allocate")
476+ }
477+
478+ if len(buf.Samples) != 2 {
479+ t.Errorf("len(Samples) = %d, want 2", len(buf.Samples))
480+ }
481+
482+ for ch := 0; ch < 2; ch++ {
483+ if len(buf.Samples[ch]) != 4 {
484+ t.Errorf("len(Samples[%d]) = %d, want 4", ch, len(buf.Samples[ch]))
485+ }
486+ }
487+}

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 8

↑↓ moveenter openesc close