fix: playbackState is Playing only while a running session has rendered, on both platforms

Author: xTMNTxRaphaelx

android/src/main/java/com/margelo/nitro/webmplayer/HybridWebmPlayer.kt

@@ -41,7 +41,8 @@ class HybridWebmPlayer : HybridWebmPlayerSpec() {
   private var surface: PlayerView? = null
   private var context: Context? = null
   private var key: String? = null
-  private var source: WorkletSource? = null
+  // Read by the playbackState getter on the JS thread.
+  @Volatile private var source: WorkletSource? = null
   private var broadcastEnded = false
   private var focusLost = false
   private var rejoinAttempts = 0
@@ -71,7 +72,9 @@ class HybridWebmPlayer : HybridWebmPlayerSpec() {
     get() = when {
       stats.failed.get() -> WebmPlaybackState.FAILED
       !active.get() -> WebmPlaybackState.IDLE
-      stats.rendered.get() -> WebmPlaybackState.PLAYING
+      // A re-attached surface re-renders the last frame, so rendered alone
+      // would read Playing while the source is stopped for a focus loss.
+      stats.rendered.get() && source != null -> WebmPlaybackState.PLAYING
       else -> WebmPlaybackState.BUFFERING
     }
 
@@ -157,6 +160,9 @@ class HybridWebmPlayer : HybridWebmPlayerSpec() {
   private fun stopSource() {
     source?.stop()
     source = null
+    // Nothing renders until the next session's first frame: a pending rejoin
+    // and a focus loss read Buffering, not Playing.
+    stats.rendered.set(false)
   }
 
   private fun fail(detail: String) {

docs/DEVICE_VALIDATION.md

@@ -253,12 +253,16 @@ broadcast as the iPhone runs, over `adb logcat -s WebmPlayer ReactNativeJS`.
   reported buffering every two seconds and the worklet's lag reached 13 s,
   227 fragments, and rejoined; playback was clean before and after. Not
   chased: Android tuning is outside this round.
-- **`playbackState` reads Playing while nothing plays**, on both platforms:
-  it is "something has rendered this session", so it stays Playing through
-  an interruption, a focus loss and, on iOS, a rejoin (Android's
-  `newSession` clears it there). Health is right in all three cases. A
-  follow-up for the spec: Buffering whenever the source is stopped or a
-  rejoin is pending.
+- **`playbackState` read Playing while nothing played**, on both platforms:
+  it was "something has rendered this session", so it stayed Playing through
+  an interruption, a focus loss and, on iOS, a rejoin. Now Playing only
+  while the session's source is running and has rendered (iOS: a source and
+  `_clockStarted`; Android: `rendered` cleared when the source stops, plus a
+  running source, since a re-attached surface re-renders the last frame and
+  set `rendered` again). Verified the same evening: Android read Buffering
+  through a YouTube focus loss and after returning to the app (log); the
+  iPhone read Buffering from "stream stalled" through the rejoin and Playing
+  after "stream resumed" (on screen; the console dropped with the Wi-Fi).
 
 ## Still to run on hardware
 

ios/WebmPlaybackEngine.mm

@@ -288,10 +288,10 @@ - (WebmPlaybackState)playbackState {
   // Checked before _running so a failure survives stop(), as on Android; play() clears it.
   if (_failed.load()) return WebmPlaybackStateFailed;
   if (!_running) return WebmPlaybackStateIdle;
-  // From the decoders, not mirrored counters: an audio-only stream must leave Buffering too.
-  if (_videoDecoder.framesPresented == 0 && _audioDecoder.packetsDecoded == 0) {
-    return WebmPlaybackStateBuffering;
-  }
+  // Playing only while a session's source is running and has decoded its
+  // first sample: the join, a pending rejoin and an interruption are all
+  // Buffering, as on Android. _clockStarted is per session (reset re-arms it).
+  if (!_source || !_clockStarted.load()) return WebmPlaybackStateBuffering;
   return WebmPlaybackStatePlaying;
 }
 

src/specs/webm-player.nitro.ts

@@ -66,6 +66,11 @@ export interface WebmPlayer extends HybridObject<{
   play(key: string): void
   stop(): void
 
+  /**
+   * Playing only while a joined session is running and has rendered. Joining,
+   * a pending rejoin, an interruption and a focus loss are Buffering; a
+   * finished broadcast is Idle; Failed survives stop() until the next play().
+   */
   readonly playbackState: WebmPlaybackState
   muted: boolean