fix(player): resolve tvOS freeze on player exit by reordering mpv options

Signed-off-by: Lance Chant <13349722+lancechant@users.noreply.github.com>

.github/pull_request_template.md

@@ -10,13 +10,10 @@
 ## 🔖 Summary
 <!--
 A concise description of the changes introduced by this PR.
-CodeRabbit will auto-generate a summary here if enabled.
 Example:
-"Add real-time currency conversion widget to dashboard."
+“Add real-time currency conversion widget to dashboard.”
 -->
 
-@coderabbitai summary
-
 ## 🏷️ Ticket / Issue
 <!--
 Link to the related ticket, issue or user story.

app/(auth)/player/direct-player.tsx

@@ -449,7 +449,7 @@ export default function page() {
     async (data: { nativeEvent: MpvOnProgressEventPayload }) => {
       if (isSeeking.get() || isPlaybackStopped) return;
 
-      const { position } = data.nativeEvent;
+      const { position, cacheSeconds } = data.nativeEvent;
       // MPV reports position in seconds, convert to ms
       const currentTime = position * 1000;
 
@@ -459,6 +459,12 @@ export default function page() {
 
       progress.set(currentTime);
 
+      // Update cache progress (current position + buffered seconds ahead)
+      if (cacheSeconds !== undefined && cacheSeconds > 0) {
+        const cacheEnd = currentTime + cacheSeconds * 1000;
+        cacheProgress.set(cacheEnd);
+      }
+
       // Update URL immediately after seeking, or every 30 seconds during normal playback
       const now = Date.now();
       const shouldUpdateUrl = wasJustSeeking.get();

modules/mpv-player/android/src/main/java/expo/modules/mpvplayer/MPVLayerRenderer.kt

@@ -1,10 +1,13 @@
 package expo.modules.mpvplayer
 
 import android.content.Context
+import android.content.res.AssetManager
 import android.os.Handler
 import android.os.Looper
 import android.util.Log
 import android.view.Surface
+import java.io.File
+import java.io.FileOutputStream
 
 /**
  * MPV renderer that wraps libmpv for video playback.
@@ -26,7 +29,7 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
     }
     
     interface Delegate {
-        fun onPositionChanged(position: Double, duration: Double)
+        fun onPositionChanged(position: Double, duration: Double, cacheSeconds: Double)
         fun onPauseChanged(isPaused: Boolean)
         fun onLoadingChanged(isLoading: Boolean)
         fun onReadyToSeek()
@@ -46,6 +49,7 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
     // Cached state
     private var cachedPosition: Double = 0.0
     private var cachedDuration: Double = 0.0
+    private var cachedCacheSeconds: Double = 0.0
     private var _isPaused: Boolean = true
     private var _isLoading: Boolean = false
     private var _playbackSpeed: Double = 1.0
@@ -101,6 +105,52 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
             MPVLib.create(context)
             MPVLib.addObserver(this)
             
+            /**
+             * Create mpv config directory and copy font files to ensure SubRip subtitles load properly on Android.
+             *
+             * Technical Background:
+             * ====================
+             * On Android, mpv requires access to a font file to render text-based subtitles, particularly SubRip (.srt)
+             * format subtitles. Without an available font in the config directory, mpv will fail to display subtitles
+             * even when subtitle tracks are properly detected and loaded.
+             *
+             * Why This Is Necessary:
+             * =====================
+             * 1. Android's font system is isolated from native libraries like mpv. While Android has system fonts,
+             *    mpv cannot access them directly due to sandboxing and library isolation.
+             *
+             * 2. SubRip subtitles require a font to render text overlay on video. When no font is available in the
+             *    configured directory, mpv either:
+             *    - Fails silently (subtitles don't appear)
+             *    - Falls back to a default font that may not support the required character set
+             *    - Crashes or produces rendering errors
+             *
+             * 3. By placing a font file (font.ttf) in mpv's config directory and setting that directory via
+             *    MPVLib.setOptionString("config-dir", ...), we ensure mpv has a known, accessible font source.
+             *
+             * Reference:
+             * =========
+             * This workaround is documented in the mpv-android project:
+             * https://github.com/mpv-android/mpv-android/issues/96
+             *
+             * The issue discusses that without a font in the config directory, SubRip subtitles fail to load
+             * properly on Android, and the solution is to copy a font file to a known location that mpv can access.
+             */
+            // Create mpv config directory and copy font files
+            val mpvDir = File(context.getExternalFilesDir(null) ?: context.filesDir, "mpv")
+            //Log.i(TAG, "mpv config dir: $mpvDir")
+            if (!mpvDir.exists()) mpvDir.mkdirs()
+            // This needs to be named `subfont.ttf` else it won't work
+            arrayOf("subfont.ttf").forEach { fileName ->
+                val file = File(mpvDir, fileName)
+                if (file.exists()) return@forEach
+                context.assets
+                    .open(fileName, AssetManager.ACCESS_STREAMING)
+                    .copyTo(FileOutputStream(file))
+            }
+            MPVLib.setOptionString("config", "yes")
+            MPVLib.setOptionString("config-dir", mpvDir.path)
+            
             // Configure mpv options before initialization (based on Findroid)
             MPVLib.setOptionString("vo", "gpu")
             MPVLib.setOptionString("gpu-context", "android")
@@ -124,7 +174,7 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
             MPVLib.setOptionString("hr-seek-framedrop", "yes")
             
             // Subtitle settings
-            MPVLib.setOptionString("sub-scale-with-window", "yes")
+            MPVLib.setOptionString("sub-scale-with-window", "no")
             MPVLib.setOptionString("sub-use-margins", "no")
             MPVLib.setOptionString("subs-match-os-language", "yes")
             MPVLib.setOptionString("subs-fallback", "yes")
@@ -283,6 +333,7 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
         MPVLib.observeProperty("pause", MPV_FORMAT_FLAG)
         MPVLib.observeProperty("track-list/count", MPV_FORMAT_INT64)
         MPVLib.observeProperty("paused-for-cache", MPV_FORMAT_FLAG)
+        MPVLib.observeProperty("demuxer-cache-duration", MPV_FORMAT_DOUBLE)
         // Video dimensions for PiP aspect ratio
         MPVLib.observeProperty("video-params/w", MPV_FORMAT_INT64)
         MPVLib.observeProperty("video-params/h", MPV_FORMAT_INT64)
@@ -561,7 +612,7 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
         when (property) {
             "duration" -> {
                 cachedDuration = value
-                mainHandler.post { delegate?.onPositionChanged(cachedPosition, cachedDuration) }
+                mainHandler.post { delegate?.onPositionChanged(cachedPosition, cachedDuration, cachedCacheSeconds) }
             }
             "time-pos" -> {
                 cachedPosition = value
@@ -570,9 +621,12 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
                 val shouldUpdate = _isSeeking || (now - lastProgressUpdateTime >= 1000)
                 if (shouldUpdate) {
                     lastProgressUpdateTime = now
-                    mainHandler.post { delegate?.onPositionChanged(cachedPosition, cachedDuration) }
+                    mainHandler.post { delegate?.onPositionChanged(cachedPosition, cachedDuration, cachedCacheSeconds) }
                 }
             }
+            "demuxer-cache-duration" -> {
+                cachedCacheSeconds = value
+            }
         }
     }
     

modules/mpv-player/android/src/main/java/expo/modules/mpvplayer/MpvPlayerView.kt

@@ -307,7 +307,7 @@ class MpvPlayerView(context: Context, appContext: AppContext) : ExpoView(context
 
     // MARK: - MPVLayerRenderer.Delegate
     
-    override fun onPositionChanged(position: Double, duration: Double) {
+    override fun onPositionChanged(position: Double, duration: Double, cacheSeconds: Double) {
         cachedPosition = position
         cachedDuration = duration
         
@@ -319,7 +319,8 @@ class MpvPlayerView(context: Context, appContext: AppContext) : ExpoView(context
         onProgress(mapOf(
             "position" to position,
             "duration" to duration,
-            "progress" to if (duration > 0) position / duration else 0.0
+            "progress" to if (duration > 0) position / duration else 0.0,
+            "cacheSeconds" to cacheSeconds
         ))
     }
     

modules/mpv-player/ios/MPVLayerRenderer.swift

@@ -5,7 +5,7 @@ import CoreVideo
 import AVFoundation
 
 protocol MPVLayerRendererDelegate: AnyObject {
-    func renderer(_ renderer: MPVLayerRenderer, didUpdatePosition position: Double, duration: Double)
+    func renderer(_ renderer: MPVLayerRenderer, didUpdatePosition position: Double, duration: Double, cacheSeconds: Double)
     func renderer(_ renderer: MPVLayerRenderer, didChangePause isPaused: Bool)
     func renderer(_ renderer: MPVLayerRenderer, didChangeLoading isLoading: Bool)
     func renderer(_ renderer: MPVLayerRenderer, didBecomeReadyToSeek: Bool)
@@ -44,6 +44,7 @@ final class MPVLayerRenderer {
     // Thread-safe state for playback
     private var _cachedDuration: Double = 0
     private var _cachedPosition: Double = 0
+    private var _cachedCacheSeconds: Double = 0
     private var _isPaused: Bool = true
     private var _playbackSpeed: Double = 1.0
     private var _isLoading: Bool = false
@@ -75,6 +76,10 @@ final class MPVLayerRenderer {
         get { stateQueue.sync { _cachedPosition } }
         set { stateQueue.async(flags: .barrier) { self._cachedPosition = newValue } }
     }
+    private var cachedCacheSeconds: Double {
+        get { stateQueue.sync { _cachedCacheSeconds } }
+        set { stateQueue.async(flags: .barrier) { self._cachedCacheSeconds = newValue } }
+    }
     private var isPaused: Bool {
         get { stateQueue.sync { _isPaused } }
         set { stateQueue.async(flags: .barrier) { self._isPaused = newValue } }
@@ -164,6 +169,7 @@ final class MPVLayerRenderer {
 
         // Enable composite OSD mode - renders subtitles directly onto video frames using GPU
         // This is better for PiP as subtitles are baked into the video
+        // NOTE: Must be set BEFORE the #if targetEnvironment check or tvOS will freeze on player exit
         checkError(mpv_set_option_string(handle, "avfoundation-composite-osd", "yes"))
 
         // Hardware decoding with VideoToolbox
@@ -340,7 +346,8 @@ final class MPVLayerRenderer {
             ("time-pos", MPV_FORMAT_DOUBLE),
             ("pause", MPV_FORMAT_FLAG),
             ("track-list/count", MPV_FORMAT_INT64),
-            ("paused-for-cache", MPV_FORMAT_FLAG)
+            ("paused-for-cache", MPV_FORMAT_FLAG),
+            ("demuxer-cache-duration", MPV_FORMAT_DOUBLE)
         ]
         for (name, format) in properties {
             mpv_observe_property(handle, 0, name, format)
@@ -484,7 +491,7 @@ final class MPVLayerRenderer {
                 cachedDuration = value
                 DispatchQueue.main.async { [weak self] in
                     guard let self else { return }
-                    self.delegate?.renderer(self, didUpdatePosition: self.cachedPosition, duration: self.cachedDuration)
+                    self.delegate?.renderer(self, didUpdatePosition: self.cachedPosition, duration: self.cachedDuration, cacheSeconds: self.cachedCacheSeconds)
                 }
             }
         case "time-pos":
@@ -499,10 +506,16 @@ final class MPVLayerRenderer {
                     lastProgressUpdateTime = now
                     DispatchQueue.main.async { [weak self] in
                         guard let self else { return }
-                        self.delegate?.renderer(self, didUpdatePosition: self.cachedPosition, duration: self.cachedDuration)
+                        self.delegate?.renderer(self, didUpdatePosition: self.cachedPosition, duration: self.cachedDuration, cacheSeconds: self.cachedCacheSeconds)
                     }
                 }
             }
+        case "demuxer-cache-duration":
+            var value = Double(0)
+            let status = getProperty(handle: handle, name: name, format: MPV_FORMAT_DOUBLE, value: &value)
+            if status >= 0 {
+                cachedCacheSeconds = value
+            }
         case "pause":
             var flag: Int32 = 0
             let status = getProperty(handle: handle, name: name, format: MPV_FORMAT_FLAG, value: &flag)

modules/mpv-player/ios/MpvPlayerView.swift

@@ -298,7 +298,7 @@ class MpvPlayerView: ExpoView {
 // MARK: - MPVLayerRendererDelegate
 
 extension MpvPlayerView: MPVLayerRendererDelegate {
-	func renderer(_: MPVLayerRenderer, didUpdatePosition position: Double, duration: Double) {
+	func renderer(_: MPVLayerRenderer, didUpdatePosition position: Double, duration: Double, cacheSeconds: Double) {
 		cachedPosition = position
 		cachedDuration = duration
 		
@@ -313,6 +313,7 @@ extension MpvPlayerView: MPVLayerRendererDelegate {
 				"position": position,
 				"duration": duration,
 				"progress": duration > 0 ? position / duration : 0,
+				"cacheSeconds": cacheSeconds,
 			])
 		}
 	}

modules/mpv-player/src/MpvPlayer.types.ts

@@ -15,6 +15,8 @@ export type OnProgressEventPayload = {
   position: number;
   duration: number;
   progress: number;
+  /** Seconds of video buffered ahead of current position */
+  cacheSeconds: number;
 };
 
 export type OnErrorEventPayload = {