react-native-audio-browser 0.2.0-next.91 → 0.2.0-next.93

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -46,6 +46,8 @@ enum EngineEvent {
46
46
  var resumePosition: Double? { get }
47
47
  /// The end of the seekable window; nil when there is none.
48
48
  var liveEdge: Double? { get }
49
+ /// How far back a live item can seek from its live edge; nil for an on-demand item or none.
50
+ var liveWindowSeconds: Double? { get }
49
51
  var isPlaybackLikelyToKeepUp: Bool { get }
50
52
  var isAirPlayRoute: Bool { get }
51
53
  /// 0–1.
@@ -55,12 +57,17 @@ enum EngineEvent {
55
57
 
56
58
  /// Resolves `src` for `track` afresh, so a short-lived URL is minted anew, and loads it. The
57
59
  /// outcome arrives as `itemPrepared`, `loadFailed`, `unplayable` or `invalidSource`.
58
- func resolveAndLoad(src: String, track: Track)
60
+ /// - Parameter shortStartBuffer: The item is ready once about 1 s is buffered, not the several
61
+ /// seconds AVPlayer otherwise waits for, then buffers as configured.
62
+ func resolveAndLoad(src: String, track: Track, shortStartBuffer: Bool)
59
63
  func cancelLoading()
60
64
  /// Drops the asset and stops observing the item, leaving the item in place for the reload.
61
65
  func dropAsset()
62
66
  /// Drops the asset and removes the item.
63
67
  func clearItem()
68
+ /// Drops the asset and its connection, leaving in the item's place one with no media that carries
69
+ /// the now-playing info: auto-publishing reads it only from the current item (docs/adr/0005).
70
+ func replaceItemWithNowPlayingCarrier()
64
71
  func stopObservingItem()
65
72
  /// Whether the AVPlayer itself has failed, not only its item: it plays nothing until recreated.
66
73
  var playerFailed: Bool { get }
@@ -71,6 +78,8 @@ enum EngineEvent {
71
78
 
72
79
  func play()
73
80
  func pause()
81
+ /// Caps how far ahead the current item loads, in seconds; nil restores the configured buffer.
82
+ func capForwardBuffer(_ seconds: Double?)
74
83
  /// Stages `rate` for the next play; applies it now only when `playing`, since a nonzero
75
84
  /// AVPlayer rate starts playback.
76
85
  func setRate(_ rate: Float, playing: Bool)
@@ -197,4 +197,25 @@ struct AsyncLoadingTests {
197
197
  let hasError = !spy.retryableErrors.isEmpty || spy.unplayableCount > 0
198
198
  #expect(hasError, "expected a retryable error or unplayable callback for non-existent file")
199
199
  }
200
+
201
+ @Test(arguments: [(0.0, 0.0, 1.0), (500, 0.5, 0.5), (5000, 5, 1)])
202
+ func aShortStartBufferIsOneSecond_orTheConfiguredOneWhenShorter(
203
+ configuredMs: Double, expected: Double, expectedShort: Double,
204
+ ) async throws {
205
+ let url = try makeSilentAudioFile()
206
+ defer { try? FileManager.default.removeItem(at: url) }
207
+ var buffers: [Double] = []
208
+ for shortStartBuffer in [false, true] {
209
+ let (loader, spy) = makeLoader()
210
+ loader.bufferDuration = configuredMs
211
+ loader.resolveAndLoad(src: url.absoluteString, shortStartBuffer: shortStartBuffer)
212
+ let deadline = ContinuousClock.now + .seconds(5)
213
+ while spy.preparedItems.isEmpty, ContinuousClock.now < deadline {
214
+ try await Task.sleep(for: .milliseconds(10))
215
+ }
216
+ let item = try #require(spy.preparedItems.first)
217
+ buffers.append(item.preferredForwardBufferDuration)
218
+ }
219
+ #expect(buffers == [expected, expectedShort])
220
+ }
200
221
  }
@@ -49,6 +49,23 @@ struct ItemObserverTests {
49
49
  observer.invalidate()
50
50
  }
51
51
 
52
+ @Test func reportsTheItemBecomingReady() async throws {
53
+ let url = try makeSilentAudioFile()
54
+ defer { try? FileManager.default.removeItem(at: url) }
55
+
56
+ let item = AVPlayerItem(url: url)
57
+ var events: [ItemObserver.Event] = []
58
+ let observer = ItemObserver(item: item) { events.append($0) }
59
+ let player = AVPlayer(playerItem: item)
60
+ let deadline = ContinuousClock.now + .seconds(5)
61
+ while !events.map(label).contains("readyToPlay"), ContinuousClock.now < deadline {
62
+ try await Task.sleep(for: .milliseconds(10))
63
+ }
64
+ #expect(events.map(label).contains("readyToPlay"))
65
+ observer.invalidate()
66
+ _ = player
67
+ }
68
+
52
69
  @Test func dropsADeliveryThatLandsAfterInvalidate() async {
53
70
  let item = makeItem()
54
71
  var events: [ItemObserver.Event] = []
@@ -71,6 +88,7 @@ struct ItemObserverTests {
71
88
  private func label(_ event: ItemObserver.Event) -> String {
72
89
  switch event {
73
90
  case .likelyToKeepUp: "likelyToKeepUp"
91
+ case .readyToPlay: "readyToPlay"
74
92
  case .failed: "failed"
75
93
  case .playedToEnd: "playedToEnd"
76
94
  case .failedToPlayToEnd: "failedToPlayToEnd"
@@ -6,9 +6,10 @@ import Testing
6
6
  private func makeLoading(
7
7
  src: String? = "https://example.com/a.mp3",
8
8
  live: Bool = false,
9
+ scheduler: any SleepTimerScheduling = ManualSleepTimerScheduler(),
9
10
  ) throws -> (Player, MockPlayerEngine, MockPlayerCallbacks) {
10
11
  let engine = MockPlayerEngine()
11
- let player = makePlayer(engine: engine)
12
+ let player = makePlayer(engine: engine, sleepTimerScheduler: scheduler)
12
13
  let callbacks = MockPlayerCallbacks()
13
14
  player.callbacks = callbacks
14
15
  try player.setQueue([Track(id: "t1", src: src, title: "T", live: live)])
@@ -16,8 +17,11 @@ private func makeLoading(
16
17
  }
17
18
 
18
19
  @MainActor
19
- private func makePlaying(live: Bool = false) throws -> (Player, MockPlayerEngine, MockPlayerCallbacks) {
20
- let (player, engine, callbacks) = try makeLoading(live: live)
20
+ private func makePlaying(
21
+ live: Bool = false,
22
+ scheduler: any SleepTimerScheduling = ManualSleepTimerScheduler(),
23
+ ) throws -> (Player, MockPlayerEngine, MockPlayerCallbacks) {
24
+ let (player, engine, callbacks) = try makeLoading(live: live, scheduler: scheduler)
21
25
  player.setPlayWhenReady(true)
22
26
  engine.hasItem = true
23
27
  engine.hasLoadedAsset = true
@@ -68,6 +72,7 @@ private func makeVirtual(online: Bool = true) throws -> (Player, MockPlayerEngin
68
72
  private func makeConnecting(
69
73
  playWhenReady: Bool = true,
70
74
  previousBuffered: Double = 0,
75
+ live: Bool = true,
71
76
  ) throws -> (Player, MockPlayerEngine, VirtualClock) {
72
77
  let clock = VirtualClock()
73
78
  let retry = RetryLoop(clock: clock)
@@ -75,7 +80,7 @@ private func makeConnecting(
75
80
  let engine = MockPlayerEngine()
76
81
  engine.bufferedPosition = previousBuffered
77
82
  let player = makePlayer(engine: engine, retry: retry)
78
- try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T", live: true)], playWhenReady: playWhenReady)
83
+ try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T", live: live)], playWhenReady: playWhenReady)
79
84
  return (player, engine, clock)
80
85
  }
81
86
 
@@ -210,6 +215,7 @@ struct PlayerSeekingTests {
210
215
  let engine = MockPlayerEngine()
211
216
  let player = makePlayer(engine: engine)
212
217
  try player.setQueue([Track(id: "t1", src: "https://example.com/a.m3u8", title: "T", live: true)], startPositionMs: 25000)
218
+ player.play()
213
219
  engine.seekResult = nil
214
220
  engine.hasItem = true
215
221
  engine.hasLoadedAsset = true
@@ -234,6 +240,7 @@ struct PlayerSeekingTests {
234
240
  engine.liveEdge = nil
235
241
  player.seekToLiveEdge()
236
242
  #expect(engine.resolveAndLoadCalls.count == 2)
243
+ #expect(engine.shortStartBufferRequests == [false, false])
237
244
  #expect(player.state == .loading)
238
245
  }
239
246
 
@@ -325,6 +332,16 @@ struct PlayerEngineEventTests {
325
332
  #expect(liveEngine.resolveAndLoadCalls.count == 2)
326
333
  }
327
334
 
335
+ /// docs/adr/0014: a stream that keeps closing keeps playing, with a short gap at each close.
336
+ @Test func aLiveEndsReconnectStartsOnAShortBuffer_theListenersConnectsDoNot() async throws {
337
+ let (player, engine, _) = try makePlaying(live: true)
338
+ engine.emit(.playedToEnd)
339
+ await player.retry.pendingTask?.value
340
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
341
+ player.retryNow()
342
+ #expect(engine.shortStartBufferRequests == [false, true, false])
343
+ }
344
+
328
345
  /// AVPlayer pauses an item at its end, so a seek within its window would leave it silent.
329
346
  @Test func aLiveEndReconnectsEvenWithASeekableWindow() async throws {
330
347
  let (player, engine, _) = try makePlaying(live: true)
@@ -437,6 +454,7 @@ struct PlayerRecoveringTests {
437
454
  #expect(callbacks.playbackChanges.last?.error?.retrying == true)
438
455
  await player.retry.pendingTask?.value
439
456
  #expect(engine.resolveAndLoadCalls.count == 2)
457
+ #expect(engine.shortStartBufferRequests == [false, true])
440
458
  #expect(player.state == .loading)
441
459
  }
442
460
 
@@ -540,8 +558,8 @@ struct PlayerRecoveringTests {
540
558
  #expect(engine.resolveAndLoadCalls.count == 3)
541
559
  }
542
560
 
543
- @Test func aPauseDuringAConnectHoldsItPastTheTimeout() async throws {
544
- let (player, engine, clock) = try makeConnecting()
561
+ @Test func aPauseDuringAnOnDemandConnectHoldsItPastTheTimeout() async throws {
562
+ let (player, engine, clock) = try makeConnecting(live: false)
545
563
  await clock.run(until: 10_000)
546
564
  player.pause()
547
565
  await clock.run(until: 200_000)
@@ -561,8 +579,9 @@ struct PlayerRecoveringTests {
561
579
  #expect(engine.resolveAndLoadCalls.count == 1)
562
580
  }
563
581
 
582
+ /// On demand: a live stream queued without play intent does not connect.
564
583
  @Test func aPlayWhileConnectingWatchesTheConnect() async throws {
565
- let (player, engine, clock) = try makeConnecting(playWhenReady: false)
584
+ let (player, engine, clock) = try makeConnecting(playWhenReady: false, live: false)
566
585
  await clock.run(until: 10_000)
567
586
  player.play()
568
587
  await clock.run(until: 41_000)
@@ -815,6 +834,7 @@ struct PlayerRecoveringTests {
815
834
 
816
835
  /// A connect that delivered nothing ends online, and counts toward `maxRetries`: only the watch
817
836
  /// gives it up, as without the drop.
837
+ /// On demand: a live stream queued without play intent does not connect.
818
838
  @Test func aSilentConnectFromBeforeTheDropWaitsOutTheWatch() async throws {
819
839
  let clock = VirtualClock()
820
840
  let retry = RetryLoop(online: false, clock: clock)
@@ -823,7 +843,7 @@ struct PlayerRecoveringTests {
823
843
  )))
824
844
  let engine = MockPlayerEngine()
825
845
  let player = makePlayer(engine: engine, retry: retry)
826
- try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T", live: true)])
846
+ try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T")])
827
847
  player.networkStatusDidChange(isOnline: true)
828
848
 
829
849
  player.play()
@@ -833,6 +853,26 @@ struct PlayerRecoveringTests {
833
853
  #expect(engine.resolveAndLoadCalls.count == 1)
834
854
  }
835
855
 
856
+ /// A live stream queued, then played, as a separate call: its connect is dropped and the engine
857
+ /// reports nothing about it, ever. The stall watch fails it at 30 s, and a Load that never played
858
+ /// gives up 12 s after its first failure.
859
+ @Test func aConnectThatEndsUnreportedStillEndsInTheError() async throws {
860
+ let clock = VirtualClock()
861
+ let retry = RetryLoop(clock: clock)
862
+ retry.updatePolicy(from: .first(true))
863
+ let engine = MockPlayerEngine()
864
+ let player = makePlayer(engine: engine, retry: retry)
865
+ try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T", live: true)])
866
+ player.play()
867
+
868
+ await clock.run(until: 41_999)
869
+ #expect(player.state == .loading)
870
+ #expect(engine.resolveAndLoadCalls.count == 2)
871
+ await clock.run(until: 42_000)
872
+ #expect(player.state == .error)
873
+ #expect(player.errorStatus.error == .playbackStalled)
874
+ }
875
+
836
876
  @Test func aStallAfterAShortDropWithRetryOffIsLeftToAVPlayer() async throws {
837
877
  let (player, engine, callbacks, clock) = try makeVirtual()
838
878
  player.retry.updatePolicy(from: nil)
@@ -1384,3 +1424,320 @@ struct PlayerReviewRegressionTests {
1384
1424
  #expect(callbacks.errorEvents.count == 1)
1385
1425
  }
1386
1426
  }
1427
+
1428
+ @Suite("Player - pausing a live stream")
1429
+ @MainActor
1430
+ struct PlayerLivePauseTests {
1431
+ @Test func aLivePauseClosesTheConnection() throws {
1432
+ let (player, engine, _) = try makePlaying(live: true)
1433
+ let carriers = engine.carrierCount
1434
+ player.pause()
1435
+ #expect(engine.carrierCount == carriers + 1)
1436
+ #expect(player.state == .paused)
1437
+ #expect(player.load?.reloadOnPlay == true)
1438
+ }
1439
+
1440
+ /// A skip back from the lock screen while paused, then a play.
1441
+ @Test func aPlayAfterALivePauseReconnectsAtTheLiveEdge() throws {
1442
+ let (player, engine, _) = try makePlaying(live: true)
1443
+ player.pause()
1444
+ engine.resumePosition = 120
1445
+ player.seek(by: -15)
1446
+ player.play()
1447
+ #expect(engine.resolveAndLoadCalls.count == 2)
1448
+ #expect(player.state == .loading)
1449
+
1450
+ engine.hasItem = true
1451
+ engine.hasLoadedAsset = true
1452
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
1453
+ #expect(engine.seekCalls.isEmpty)
1454
+ }
1455
+
1456
+ /// A live HLS stream with a DVR window, playing 2 minutes behind its edge.
1457
+ @MainActor private func makePlayingSeekableLive(window: Double = 600) throws -> (Player, MockPlayerEngine) {
1458
+ let (player, engine, _) = try makePlaying(live: true)
1459
+ engine.liveWindowSeconds = window
1460
+ engine.liveEdge = 1000
1461
+ engine.currentTime = 880
1462
+ engine.resumePosition = 880
1463
+ return (player, engine)
1464
+ }
1465
+
1466
+ @Test func aSeekableLivePauseKeepsItsPositionAndResumesFromIt() throws {
1467
+ let (player, engine) = try makePlayingSeekableLive()
1468
+ let plays = engine.startPlaybackCallCount
1469
+ player.pause()
1470
+ engine.emit(.timeControlStatus(.paused, waitingForNoItem: false))
1471
+ #expect(engine.carrierCount == 0)
1472
+ #expect(player.state == .paused)
1473
+ #expect(player.load?.reloadOnPlay == false)
1474
+ #expect(engine.currentTime == 880)
1475
+
1476
+ player.play()
1477
+ #expect(engine.resolveAndLoadCalls.count == 1)
1478
+ #expect(engine.startPlaybackCallCount == plays + 1)
1479
+ #expect(engine.seekCalls.isEmpty)
1480
+ }
1481
+
1482
+ @Test func aJumpToTheLiveEdgeWhileASeekableLiveTrackIsPausedSeeksToTheWindowEnd() throws {
1483
+ let (player, engine) = try makePlayingSeekableLive()
1484
+ player.pause()
1485
+ player.seekToLiveEdge()
1486
+ #expect(engine.seekCalls == [1000])
1487
+ #expect(engine.resolveAndLoadCalls.count == 1)
1488
+ }
1489
+
1490
+ @Test func aPausedSeekableLiveItemCapsItsBufferUntilPlay() throws {
1491
+ let (player, engine) = try makePlayingSeekableLive()
1492
+ engine.forwardBufferCaps.removeAll()
1493
+ player.pause()
1494
+ #expect(engine.forwardBufferCaps == [Player.pausedLiveBufferSeconds])
1495
+ player.play()
1496
+ #expect(engine.forwardBufferCaps == [Player.pausedLiveBufferSeconds, nil])
1497
+ }
1498
+
1499
+ @Test func aStoppedSeekableLiveItemCapsItsBuffer() throws {
1500
+ let (player, engine) = try makePlayingSeekableLive()
1501
+ engine.forwardBufferCaps.removeAll()
1502
+ player.stop()
1503
+ #expect(engine.forwardBufferCaps == [Player.pausedLiveBufferSeconds])
1504
+ }
1505
+
1506
+ @Test func aPausedOnDemandItemKeepsItsBuffer() throws {
1507
+ let (player, engine, _) = try makePlaying()
1508
+ engine.forwardBufferCaps.removeAll()
1509
+ player.pause()
1510
+ #expect(!engine.forwardBufferCaps.contains { $0 != nil })
1511
+ }
1512
+
1513
+ @Test func aSeekableLiveStopKeepsItsItem() throws {
1514
+ let (player, engine) = try makePlayingSeekableLive()
1515
+ player.stop()
1516
+ #expect(engine.carrierCount == 0)
1517
+ #expect(player.state == .stopped)
1518
+ player.seekToLiveEdge()
1519
+ #expect(engine.seekCalls == [1000])
1520
+ }
1521
+
1522
+ @Test func aLiveWindowShorterThanAPauseIsWorthClosesLikeAStreamWithNone() throws {
1523
+ let (player, engine) = try makePlayingSeekableLive(window: Player.pausableLiveWindowSeconds - 1)
1524
+ player.pause()
1525
+ #expect(engine.carrierCount == 1)
1526
+ #expect(player.load?.reloadOnPlay == true)
1527
+ }
1528
+
1529
+ @Test func anOnDemandPauseKeepsTheItem() throws {
1530
+ let (player, engine, _) = try makePlaying()
1531
+ player.pause()
1532
+ engine.emit(.timeControlStatus(.paused, waitingForNoItem: false))
1533
+ #expect(engine.carrierCount == 0)
1534
+ #expect(player.state == .paused)
1535
+ #expect(player.load?.reloadOnPlay == false)
1536
+ }
1537
+
1538
+ @Test func aLiveStopClosesTheConnectionWithoutPassingThroughPaused() throws {
1539
+ let (player, engine, callbacks) = try makePlaying(live: true)
1540
+ let carriers = engine.carrierCount
1541
+ callbacks.playbackChanges.removeAll()
1542
+ player.stop()
1543
+ #expect(engine.carrierCount == carriers + 1)
1544
+ #expect(callbacks.playbackChanges.map(\.state) == [.stopped])
1545
+ player.play()
1546
+ #expect(engine.resolveAndLoadCalls.count == 2)
1547
+ }
1548
+
1549
+ @Test func aLiveStreamLoadedWithoutIntentOpensNoConnection() throws {
1550
+ let scheduler = ManualSleepTimerScheduler()
1551
+ let (player, engine, _) = try makeLoading(live: true, scheduler: scheduler)
1552
+ #expect(engine.resolveAndLoadCalls.isEmpty)
1553
+ #expect(engine.carrierCount == 0)
1554
+ #expect(player.state == .loading)
1555
+
1556
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1557
+ #expect(engine.resolveAndLoadCalls.isEmpty)
1558
+ #expect(engine.carrierCount == 1)
1559
+ #expect(player.state == .paused)
1560
+ player.play()
1561
+ #expect(engine.resolveAndLoadCalls.count == 1)
1562
+ }
1563
+
1564
+ /// A station started from paused as two calls, the way a consumer without `playWhenReady` does.
1565
+ @Test func aLiveStreamQueuedThenPlayedFromPausedNeverReportsPaused() throws {
1566
+ let scheduler = ManualSleepTimerScheduler()
1567
+ let (player, engine, callbacks) = try makePlaying(live: true, scheduler: scheduler)
1568
+ player.pause()
1569
+ let carriers = engine.carrierCount
1570
+ callbacks.playbackChanges.removeAll()
1571
+
1572
+ try player.setQueue([Track(id: "t2", src: "https://example.com/b.mp3", title: "B", live: true)])
1573
+ player.play()
1574
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1575
+ #expect(engine.resolveAndLoadCalls.count == 2)
1576
+ #expect(engine.carrierCount == carriers)
1577
+ #expect(!callbacks.playbackChanges.contains { $0.state == .paused })
1578
+ #expect(player.state == .loading)
1579
+ }
1580
+
1581
+ @Test func aPlayArriving100msAfterTheQueueNeverReportsPaused() async throws {
1582
+ let (player, engine, callbacks) = try makePlaying(live: true, scheduler: MainQueueSleepTimerScheduler())
1583
+ player.pause()
1584
+ let carriers = engine.carrierCount
1585
+ callbacks.playbackChanges.removeAll()
1586
+
1587
+ try player.setQueue([Track(id: "t2", src: "https://example.com/b.mp3", title: "B", live: true)])
1588
+ try await Task.sleep(for: .milliseconds(100))
1589
+ player.play()
1590
+ try await Task.sleep(for: .seconds(Player.idleLiveParkDelaySeconds + 0.5))
1591
+ #expect(engine.resolveAndLoadCalls.count == 2)
1592
+ #expect(engine.carrierCount == carriers)
1593
+ #expect(!callbacks.playbackChanges.contains { $0.state == .paused })
1594
+ #expect(player.state == .loading)
1595
+ }
1596
+
1597
+ @Test func withNoPlayTheDeferredParkFiresOnTheMainQueue() async throws {
1598
+ let (player, engine, _) = try makeLoading(live: true, scheduler: MainQueueSleepTimerScheduler())
1599
+ try await Task.sleep(for: .seconds(Player.idleLiveParkDelaySeconds + 0.5))
1600
+ #expect(engine.carrierCount == 1)
1601
+ #expect(player.state == .paused)
1602
+ }
1603
+
1604
+ @Test func aStopDuringTheDeferredParkClosesTheItemAndStaysStopped() throws {
1605
+ let scheduler = ManualSleepTimerScheduler()
1606
+ let (player, engine, _) = try makeLoading(live: true, scheduler: scheduler)
1607
+ player.stop()
1608
+ #expect(engine.carrierCount == 1)
1609
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1610
+ #expect(player.state == .stopped)
1611
+ #expect(engine.carrierCount == 1)
1612
+ }
1613
+
1614
+ @Test func aPauseDuringTheDeferredParkStillParksAtTheDeadline() throws {
1615
+ let scheduler = ManualSleepTimerScheduler()
1616
+ let (player, engine, _) = try makeLoading(live: true, scheduler: scheduler)
1617
+ player.pause()
1618
+ #expect(player.state == .loading)
1619
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1620
+ #expect(player.state == .paused)
1621
+ #expect(engine.resolveAndLoadCalls.isEmpty)
1622
+ }
1623
+
1624
+ @Test func aPlayPauseAndPlayInsideTheDelayIsNotParkedByIt() throws {
1625
+ let scheduler = ManualSleepTimerScheduler()
1626
+ let (player, engine, _) = try makeLoading(live: true, scheduler: scheduler)
1627
+ player.play()
1628
+ player.pause()
1629
+ player.play()
1630
+ let carriers = engine.carrierCount
1631
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1632
+ #expect(engine.carrierCount == carriers)
1633
+ #expect(player.state == .loading)
1634
+ #expect(engine.resolveAndLoadCalls.count == 2)
1635
+ }
1636
+
1637
+ @Test func aLiveStreamQueuedToPlayConnectsWithoutParking() throws {
1638
+ let engine = MockPlayerEngine()
1639
+ let player = makePlayer(engine: engine)
1640
+ let callbacks = MockPlayerCallbacks()
1641
+ player.callbacks = callbacks
1642
+ try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T", live: true)], playWhenReady: true)
1643
+ #expect(engine.carrierCount == 0)
1644
+ #expect(engine.resolveAndLoadCalls.count == 1)
1645
+ #expect(!callbacks.playbackChanges.contains { $0.state == .paused })
1646
+ }
1647
+
1648
+ @Test func skippingToALiveStreamWhilePausedDoesNotConnect() throws {
1649
+ let scheduler = ManualSleepTimerScheduler()
1650
+ let (player, engine, _) = try makePlaying(scheduler: scheduler)
1651
+ try player.add([Track(id: "t2", src: "https://example.com/b.mp3", title: "B", live: true)])
1652
+ player.pause()
1653
+ player.next()
1654
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1655
+ #expect(engine.resolveAndLoadCalls.count == 1)
1656
+ #expect(player.state == .paused)
1657
+ }
1658
+
1659
+ @Test func aMediaServicesResetWhileParkedDoesNotConnect() throws {
1660
+ let scheduler = ManualSleepTimerScheduler()
1661
+ let (player, engine, _) = try makePlaying(live: true, scheduler: scheduler)
1662
+ player.pause()
1663
+ player.mediaServicesWereReset()
1664
+ scheduler.advance(to: Player.idleLiveParkDelaySeconds)
1665
+ #expect(engine.resolveAndLoadCalls.count == 1)
1666
+ #expect(player.state == .paused)
1667
+ }
1668
+
1669
+ /// The carrier item has no asset: the AVPlayer reports a pause without one.
1670
+ @Test func thePausedStatusOfTheEmptiedPlayerKeepsItPaused() throws {
1671
+ let (player, engine, _) = try makePlaying(live: true)
1672
+ player.pause()
1673
+ engine.emit(.timeControlStatus(.paused, waitingForNoItem: false))
1674
+ #expect(player.state == .paused)
1675
+ }
1676
+
1677
+ /// The dropped item's first audio, reported after the pause that dropped it.
1678
+ @Test func audioReportedAfterTheDropKeepsItPaused() throws {
1679
+ let (player, engine, _) = try makePlaying(live: true)
1680
+ player.pause()
1681
+ engine.emit(.audioDidStart)
1682
+ #expect(player.state == .paused)
1683
+ }
1684
+
1685
+ @Test func aLivePauseDuringAConnectClosesIt() async throws {
1686
+ let (player, engine, clock) = try makeConnecting()
1687
+ await clock.run(until: 10_000)
1688
+ player.pause()
1689
+ await clock.run(until: 200_000)
1690
+ #expect(engine.carrierCount == 1)
1691
+ #expect(engine.resolveAndLoadCalls.count == 1)
1692
+ #expect(player.state == .paused)
1693
+ }
1694
+
1695
+ @Test func aLivePauseDuringAStallLeavesNoReconnect() async throws {
1696
+ let (player, engine, _, clock) = try makeVirtual()
1697
+ player.transition(.avPlayerPlaying)
1698
+ await clock.run(until: 10_000)
1699
+ player.transition(.avPlayerWaiting)
1700
+ #expect(player.retry.stallTask != nil)
1701
+
1702
+ player.pause()
1703
+ #expect(player.retry.stallTask == nil)
1704
+ #expect(player.retry.pendingTask == nil)
1705
+ await clock.run(until: 600_000)
1706
+ #expect(engine.resolveAndLoadCalls.count == 1)
1707
+ #expect(player.state == .paused)
1708
+ }
1709
+
1710
+ @Test func aLivePauseAfterTheRetryGaveUpClosesTheConnection() throws {
1711
+ let (player, engine, _) = try makePlaying(live: true)
1712
+ player.transition(.errorOccurred(.playbackStalled))
1713
+ let carriers = engine.carrierCount
1714
+ player.pause()
1715
+ #expect(engine.carrierCount == carriers + 1)
1716
+ #expect(player.state == .error)
1717
+ player.play()
1718
+ #expect(engine.resolveAndLoadCalls.count == 2)
1719
+ }
1720
+
1721
+ @Test func aJumpToTheLiveEdgeAfterAStopStaysStopped() throws {
1722
+ let (player, engine, _) = try makePlaying(live: true)
1723
+ player.stop()
1724
+ player.seekToLiveEdge()
1725
+ player.retryNow()
1726
+ #expect(player.state == .stopped)
1727
+ #expect(engine.resolveAndLoadCalls.count == 1)
1728
+ }
1729
+
1730
+ /// Paused longer than any silence the loop tolerates: the reconnect gets a whole budget.
1731
+ @Test func aPlayAfterAPauseLongerThanTheBudgetReconnectsWithoutError() async throws {
1732
+ let (player, engine, callbacks, clock) = try makeVirtual()
1733
+ player.transition(.avPlayerPlaying)
1734
+ await clock.run(until: 10_000)
1735
+ player.pause()
1736
+ await clock.run(until: 610_000)
1737
+ player.play()
1738
+ await clock.run(until: 615_000)
1739
+ #expect(engine.resolveAndLoadCalls.count == 2)
1740
+ #expect(player.state == .loading)
1741
+ #expect(callbacks.errorEvents.isEmpty)
1742
+ }
1743
+ }
@@ -0,0 +1,13 @@
1
+ import AVFoundation
2
+ import Testing
3
+
4
+ /// A 0.1 s silent WAV in the temporary directory, which AVFoundation loads as playable. The caller
5
+ /// removes it.
6
+ func makeSilentAudioFile() throws -> URL {
7
+ let url = FileManager.default.temporaryDirectory.appendingPathComponent("\(UUID().uuidString).wav")
8
+ let format = try #require(AVAudioFormat(standardFormatWithSampleRate: 8000, channels: 1))
9
+ let buffer = try #require(AVAudioPCMBuffer(pcmFormat: format, frameCapacity: 800))
10
+ buffer.frameLength = 800
11
+ try AVAudioFile(forWriting: url, settings: format.settings).write(from: buffer)
12
+ return url
13
+ }
@@ -41,19 +41,26 @@ final class MockPlayerEngine: PlayerEngine {
41
41
  var bufferedPosition: Double = 0
42
42
  var resumePosition: Double?
43
43
  var liveEdge: Double?
44
+ var liveWindowSeconds: Double?
44
45
  var isPlaybackLikelyToKeepUp = false
45
46
  var isAirPlayRoute = false
46
47
  var playerFailed = false
47
48
  var volume: Float = 1
48
49
 
49
50
  var resolveAndLoadCalls: [String] = []
51
+ var shortStartBufferRequests: [Bool] = []
50
52
  var cancelLoadingCount = 0
51
53
  var dropAssetCount = 0
52
54
  var clearItemCount = 0
55
+ var carrierCount = 0
53
56
  var stopObservingItemCount = 0
54
57
  var recreateCount = 0
55
58
 
56
- func resolveAndLoad(src: String, track _: Track) { resolveAndLoadCalls.append(src) }
59
+ func resolveAndLoad(src: String, track _: Track, shortStartBuffer: Bool) {
60
+ resolveAndLoadCalls.append(src)
61
+ shortStartBufferRequests.append(shortStartBuffer)
62
+ }
63
+
57
64
  func cancelLoading() { cancelLoadingCount += 1 }
58
65
  func dropAsset() {
59
66
  dropAssetCount += 1
@@ -67,6 +74,15 @@ final class MockPlayerEngine: PlayerEngine {
67
74
  resumePosition = nil
68
75
  }
69
76
 
77
+ func replaceItemWithNowPlayingCarrier() {
78
+ carrierCount += 1
79
+ hasItem = true
80
+ hasLoadedAsset = false
81
+ resumePosition = nil
82
+ liveEdge = nil
83
+ liveWindowSeconds = nil
84
+ }
85
+
70
86
  func stopObservingItem() { stopObservingItemCount += 1 }
71
87
  func recreate() {
72
88
  recreateCount += 1
@@ -82,6 +98,8 @@ final class MockPlayerEngine: PlayerEngine {
82
98
  var seekResult: Bool? = true
83
99
 
84
100
  func play() { startPlaybackCallCount += 1 }
101
+ var forwardBufferCaps: [Double?] = []
102
+ func capForwardBuffer(_ seconds: Double?) { forwardBufferCaps.append(seconds) }
85
103
  func pause() { pausePlaybackCallCount += 1 }
86
104
  func setRate(_ rate: Float, playing: Bool) { rates.append((rate, playing)) }
87
105
  private var seeksInFlight: [@MainActor (Bool) -> Void] = []
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-audio-browser",
3
- "version": "0.2.0-next.91",
3
+ "version": "0.2.0-next.93",
4
4
  "description": "react-native-audio-browser is a react native package built with Nitro",
5
5
  "keywords": [
6
6
  "react-native",
@@ -144,6 +144,35 @@ resolved URL, so an expired one re-resolves only after that first attempt
144
144
  fails (see [Fresh URLs on reconnect](#fresh-urls-on-reconnect)).
145
145
  General seeking is in [Playback](/guide/playback).
146
146
 
147
+ ## Pausing a live stream
148
+
149
+ On iOS and Android, how a live track pauses depends on whether it can be
150
+ rewound.
151
+
152
+ A stream that can't be rewound holds no connection while paused or stopped.
153
+ That covers progressive (ICY/Icecast) radio, and live HLS whose seekable
154
+ window is under 30 seconds. Left open, a paused player goes on downloading
155
+ it (on macOS for as long as it stays paused), and a resume plays what it
156
+ buffered, behind the stream. So pause and stop close the connection. The
157
+ now-playing surfaces go on showing the track, paused, and play reconnects at
158
+ the live edge.
159
+
160
+ A stream with a seekable window of 30 seconds or more (HLS with a DVR window)
161
+ pauses as an on-demand track does. It keeps its position, and play resumes
162
+ from there. [`seekToLiveEdge()`](/api/features/playback/#seektoliveedge)
163
+ while paused moves it to the window's end. On iOS a paused one keeps what it
164
+ has buffered but loads no more than 10 seconds ahead, where it would otherwise
165
+ go on loading toward the live edge; on Android the buffer limit (`maxBuffer`)
166
+ bounds it. A shorter window doesn't count: a short pause would carry the
167
+ position out of it.
168
+
169
+ A live track loaded without play intent (`load` or `setQueue` without
170
+ `playWhenReady`) opens no connection. It stays `loading` for a second, so a
171
+ `play()` that follows connects at once, with no `paused` in between. With no
172
+ play by then it reports `paused`. On iOS this holds for a seekable window too,
173
+ since a window isn't known before the stream connects. On Android a live
174
+ track loaded or skipped to while paused still connects and buffers.
175
+
147
176
  ## Periodic position updates (Android)
148
177
 
149
178
  While the player plays or loads, Media3's media session sends External