Regularize show/hide logic for video player scrub/play controls (fixes #4073) (#4117)

When viewing a video in Tusky, there is a top toolbar where the
description is shown and the bottom toolbar where play, forward,
backward, and scrub controls are found. In both Tusky 23 and the new
media3 video player code, the logic for showing these toolbars is
*unrelated*; Tusky catches tap events and shows and hides the
description, and the Android media library separately catches tap events
and shows and hides the bottom toolbar. Meanwhile, Tusky and the Android
media library each separately manage a set of logic for auto-hiding
their respective toolbars after a certain number of seconds has passed.
This all results in several problems:

- The top and bottom toolbars can desync, so that one is visible and the
other is not, and tapping to show/hide after this will only swap which
one is visible. This happens *every* time you switch to another
application then back to Tusky while the video player is up.
- You can also desync the top and bottom toolbars in this way by simply
tapping very rapidly.
- The autohide logic was difficult for us to control or customize,
because it was partially hidden inside the Android libraries (relevant
because under media3, the autohide delay increased from 3 to something
like 5 or 6 seconds).

In this patch, I disabled all auto- and tap-based show/hide logic in
media3 and set the Tusky-side show/hide to directly control the media3
toolbar. I then audited the code with printfs until I understood the
state machine of show/hide, and removed anything irrational (some code
was either unreachable, or redundant; either these lines were broken in
the media3 transition, or they never worked).¹

While doing this, I made two policy changes:

- As discussed on Matrix, the autohide delay is now 4 seconds. (In
discussions with users on Mastodon, some complained the previous 3
seconds was too short; but in my opinion and [I think?] charlag's, the
new 5 seconds is too long).
- In the pre-existing code, if the user has hidden the controls, and
they switch to another app and back, the controls display for 4 seconds
then re-hide themselves, just like if the video had been presented for
the first time. I think this is good and kept it— *however* I made a
decision if the user intentionally taps to display the controls, *then*
switches to another app and back, the controls should *not* auto-hide,
because the user most recently requested those controls be shown.

Tests I performed on the final PR (successfully):

- Start video. Expect: toolbar+description hides after 4 seconds.
- Start video. Pause. Resume. Expect: t+d hides after 4 seconds.
- Start video. Wait 4 seconds until t+d hide. Switch to other app.
Switch back. Expect: t+d reappears, then hides after 4 seconds.
- Start video. Wait 4 seconds until t+d hide. Tap to show t+d. Switch to
other app. Switch back. Expect: t+d appear, do NOT autohide.
- Start video. Before 4 seconds up, switch to other app. Switch back.
Expect: t+d reappears, then hides after 4 seconds.
- Start video. Pause. Resume. Before 4 seconds up, switch to other app.
Switch back. Expect: t+d reappears, then hides after 4 seconds.
- Start video. Wait 4 seconds until t+d hide. Tap rapidly over and over
for many seconds. Expect: Nothing weird
- Start *audio*. Expect: At no point does controller autohide, not even
if I switch to another app and back, but I can hide it by manually
tapping

These tests were performed on Android 13. There is an entirely separate
`Build.VERSION.SDK_INT <= 23` path I did not test, but Android Studio
says this is dead code (I think it thinks our minimum SDK is higher than
that?)

---

<small>¹ Incidentally, the underlying cause of #4073 (the show/resume
part of it anyway) turned out to be that the STATE_READY event was being
received not just on video load but also a second time on app resume,
causing certain parts of the initialization code to run a second time
although the fragment had already been fully initialized.</small>

app/src/main/java/com/keylesspalace/tusky/fragment/ViewVideoFragment.kt

@@ -45,7 +45,6 @@ import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.exoplayer.source.DefaultMediaSourceFactory
 import androidx.media3.exoplayer.util.EventLogger
 import androidx.media3.ui.AspectRatioFrameLayout
-import androidx.media3.ui.PlayerControlView
 import com.bumptech.glide.Glide
 import com.bumptech.glide.request.target.CustomTarget
 import com.bumptech.glide.request.transition.Transition
@@ -95,6 +94,15 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
 
     private lateinit var mediaSourceFactory: DefaultMediaSourceFactory
 
+    /** Have we received at least one "READY" event? */
+    private var haveStarted = false
+
+    /** Is there a pending autohide? (We can't rely on Android's tracking because that clears on suspend.) */
+    private var pendingHideToolbar = false
+
+    /** Prevent the next play start from queueing a toolbar hide. */
+    private var suppressNextHideToolbar = false
+
     override fun onAttach(context: Context) {
         super.onAttach(context)
 
@@ -150,7 +158,7 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
                     /** A single tap should show/hide the media description */
                     override fun onSingleTapUp(e: MotionEvent): Boolean {
                         mediaActivity.onPhotoTap()
-                        return false
+                        return true // Do not pass gestures through to media3
                     }
 
                     /** A fling up/down should dismiss the fragment */
@@ -164,7 +172,7 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
                             videoActionsListener.onDismiss()
                             return true
                         }
-                        return false
+                        return true // Do not pass gestures through to media3
                     }
                 }
             )
@@ -193,9 +201,10 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
 
                 simpleGestureDetector.onTouchEvent(event)
 
-                // Allow the player's normal onTouch handler to run as well (e.g., to show the
-                // player controls on tap)
-                return false
+                // Do not pass gestures through to media3
+                // We have to do this because otherwise taps to hide will be double-handled and media3 will re-show itself
+                // media3 has a property to disable "hide on tap" but "show on tap" is unconditional
+                return true
             }
         }
 
@@ -205,13 +214,28 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
             override fun onPlaybackStateChanged(playbackState: Int) {
                 when (playbackState) {
                     Player.STATE_READY -> {
-                        // Wait until the media is loaded before accepting taps as we don't want toolbar to
-                        // be hidden until then.
-                        binding.videoView.setOnTouchListener(touchListener)
+                        if (!haveStarted) {
+                            // Wait until the media is loaded before accepting taps as we don't want toolbar to
+                            // be hidden until then.
+                            binding.videoView.setOnTouchListener(touchListener)
 
-                        binding.progressBar.hide()
-                        binding.videoView.useController = true
-                        binding.videoView.showController()
+                            binding.progressBar.hide()
+                            binding.videoView.useController = true
+                            binding.videoView.showController()
+                            haveStarted = true
+                        } else {
+                            // This isn't a real "done loading"; this is a resume event after backgrounding.
+                            if (mediaActivity.isToolbarVisible) {
+                                // Before suspend, the toolbar/description were visible, so description is visible already.
+                                // But media3 will have automatically hidden the video controls on suspend, so we need to match the description state.
+                                binding.videoView.showController()
+                                if (!pendingHideToolbar) {
+                                    suppressNextHideToolbar = true // The user most recently asked us to show the toolbar, so don't hide it when play starts.
+                                }
+                            } else {
+                                mediaActivity.onPhotoTap()
+                            }
+                        }
                     }
                     else -> { /* do nothing */ }
                 }
@@ -220,7 +244,11 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
             override fun onIsPlayingChanged(isPlaying: Boolean) {
                 if (isAudio) return
                 if (isPlaying) {
-                    hideToolbarAfterDelay(TOOLBAR_HIDE_DELAY_MS)
+                    if (suppressNextHideToolbar) {
+                        suppressNextHideToolbar = false
+                    } else {
+                        hideToolbarAfterDelay(TOOLBAR_HIDE_DELAY_MS)
+                    }
                 } else {
                     handler.removeCallbacks(hideToolbar)
                 }
@@ -260,9 +288,7 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
 
         if (Build.VERSION.SDK_INT <= 23 || player == null) {
             initializePlayer()
-            if (mediaActivity.isToolbarVisible && !isAudio) {
-                hideToolbarAfterDelay(TOOLBAR_HIDE_DELAY_MS)
-            }
+
             binding.videoView.onResume()
         }
     }
@@ -368,6 +394,7 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
     }
 
     private fun hideToolbarAfterDelay(delayMilliseconds: Int) {
+        pendingHideToolbar = true
         handler.postDelayed(hideToolbar, delayMilliseconds.toLong())
     }
 
@@ -395,18 +422,24 @@ class ViewVideoFragment : ViewMediaFragment(), Injectable {
             })
             .start()
 
-        if (visible && (binding.videoView.player?.isPlaying == true) && !isAudio) {
-            hideToolbarAfterDelay(TOOLBAR_HIDE_DELAY_MS)
+        // media3 controls bar
+        if (visible) {
+            binding.videoView.showController()
         } else {
-            handler.removeCallbacks(hideToolbar)
+            binding.videoView.hideController()
         }
+
+        // Either the user just requested toolbar display, or we just hid it.
+        // Either way, any pending hides are no longer appropriate.
+        pendingHideToolbar = false
+        handler.removeCallbacks(hideToolbar)
     }
 
     override fun onTransitionEnd() { }
 
     companion object {
         private const val TAG = "ViewVideoFragment"
-        private const val TOOLBAR_HIDE_DELAY_MS = PlayerControlView.DEFAULT_SHOW_TIMEOUT_MS
+        private const val TOOLBAR_HIDE_DELAY_MS = 4_000
         private const val SEEK_POSITION = "seekPosition"
     }
 }

app/src/main/res/layout/fragment_view_video.xml

@@ -34,7 +34,9 @@
         app:layout_constraintTop_toTopOf="parent"
         app:use_controller="false"
         app:show_previous_button="false"
-        app:show_next_button="false" />
+        app:show_next_button="false"
+        app:show_timeout="0"
+        app:hide_on_touch="false" />
 
     <ProgressBar
         android:id="@+id/progressBar"