feat(android): add surface type prop (#4719)

Author: KrzysztofMoch

bun.lock

@@ -53,6 +53,7 @@ export default App;
 | `autoEnterPictureInPicture` | `boolean` | No | `false` | Whether the video should automatically enter PiP mode when it starts playing and the app is backgrounded (behavior might vary by platform). |
 | `resizeMode` | `'contain' \| 'cover' \| 'stretch' \| 'none'` | No | `'none'` | How the video should be resized to fit the view. |
 | `keepScreenAwake` | `boolean` | No | `true` | Whether to keep the device screen awake while the video view is mounted. |
+| `surfaceType` | `'surface' \| 'texture'` | No (Android only) | `'surface'` | (Android) Underlying native view type. `'surface'` uses a SurfaceView (better performance, no transforms/overlap), `'texture'` uses a TextureView (supports animations, transforms, overlapping UI) at a small performance cost. Ignored on iOS. |
 
 ## Events
 
@@ -104,4 +105,26 @@ Available methods on the `VideoViewRef`:
 | `exitFullscreen()` | `() => void` | Programmatically requests the video view to exit fullscreen mode. |
 | `enterPictureInPicture()` | `() => void` | Programmatically requests the video view to enter picture-in-picture mode. |
 | `exitPictureInPicture()` | `() => void` | Programmatically requests the video view to exit picture-in-picture mode. |
-| `canEnterPictureInPicture()` | `() => boolean` | Checks if picture-in-picture mode is currently available and supported. Returns `true` if PiP can be entered, `false` otherwise. |
+| `canEnterPictureInPicture()` | `() => boolean` | Checks if picture-in-picture mode is currently available and supported. Returns `true` if PiP can be entered, `false` otherwise. |
+
+## Android: Choosing a surface type
+
+On Android the default rendering path uses a `SurfaceView` (set via `surfaceType="surface"`) for optimal decoding performance and lower latency. However `SurfaceView` lives in a separate window and can't be:
+
+- Animated with transforms (scale, rotate, opacity fade)
+- Clipped by parent views (rounded corners, masks)
+- Overlapped reliably with sibling views (z-order issues)
+
+If you need those UI effects, switch to `TextureView`:
+
+```tsx
+<VideoView
+  player={player}
+  surfaceType="texture"
+  style={{ width: 300, height: 170, borderRadius: 16, overflow: 'hidden' }}
+  resizeMode="cover"
+  controls
+/>
+```
+
+Use `TextureView` only when required, as it can be slightly less performant and may increase power consumption on some devices.

docs/docs/video-view.md

@@ -1565,7 +1565,7 @@ PODS:
     - React-logger (= 0.77.2)
     - React-perflogger (= 0.77.2)
     - React-utils (= 0.77.2)
-  - ReactNativeVideo (7.0.0-alpha.4):
+  - ReactNativeVideo (7.0.0-alpha.5):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1904,7 +1904,7 @@ SPEC CHECKSUMS:
   ReactAppDependencyProvider: f334cebc0beed0a72490492e978007082c03d533
   ReactCodegen: 474fbb3e4bb0f1ee6c255d1955db76e13d509269
   ReactCommon: 7763e59534d58e15f8f22121cdfe319040e08888
-  ReactNativeVideo: f365bc4f1a57ab50ddb655cda2f47bc06698a53b
+  ReactNativeVideo: 705a2a90d9f04afff9afd90d4ef194e1bc1135d5
   ReactNativeVideoDrm: 62840ae0e184f711a2e6495c18e342a74cb598f8
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
   Yoga: 31a098f74c16780569aebd614a0f37a907de0189

example/ios/Podfile.lock

@@ -78,6 +78,12 @@ class HybridVideoViewViewManager(nitroId: Int): HybridVideoViewViewManagerSpec()
       videoView.get()?.keepScreenAwake = value
     }
 
+  override var surfaceType: SurfaceType
+    get() = videoView.get()?.surfaceType ?: SurfaceType.SURFACE
+    set(value) {
+      videoView.get()?.surfaceType = value
+    }
+
   // View callbacks
   override var onPictureInPictureChange: ((Boolean) -> Unit)? = null
     set(value) {

packages/react-native-video/android/src/main/java/com/twg/video/hybrids/videoviewviewmanager/HybridVideoViewViewManager.kt

@@ -8,6 +8,7 @@ import android.os.Build
 import android.util.AttributeSet
 import android.util.DisplayMetrics
 import android.util.Log
+import android.view.LayoutInflater
 import android.view.View
 import android.view.ViewGroup
 import android.view.WindowManager
@@ -22,6 +23,7 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.video.HybridVideoPlayer
 import com.margelo.nitro.video.ResizeMode
+import com.margelo.nitro.video.SurfaceType
 import com.margelo.nitro.video.VideoViewEvents
 import com.twg.video.core.LibraryError
 import com.twg.video.core.VideoManager
@@ -36,6 +38,8 @@ import com.twg.video.core.extensions.toAspectRatioFrameLayout
 import com.twg.video.core.utils.PictureInPictureUtils
 import com.twg.video.core.utils.PictureInPictureUtils.createDisabledPictureInPictureParams
 import com.twg.video.core.utils.SmallVideoPlayerOptimizer
+import com.twg.video.R.layout.player_view_surface
+import com.twg.video.R.layout.player_view_texture
 
 @UnstableApi
 class VideoView @JvmOverloads constructor(
@@ -90,6 +94,20 @@ class VideoView @JvmOverloads constructor(
 
   var pictureInPictureEnabled: Boolean = false
 
+  var surfaceType: SurfaceType = SurfaceType.SURFACE
+    set(value) {
+      if (field == value) return
+      field = value
+
+      runOnMainThread {
+        removeView(playerView)
+        playerView.player = null
+        playerView = createPlayerView()
+        playerView.player = hybridPlayer?.player
+        addView(playerView)
+      }
+    }
+
   var resizeMode: ResizeMode = ResizeMode.NONE
     set(value) {
       field = value
@@ -101,7 +119,9 @@ class VideoView @JvmOverloads constructor(
   var keepScreenAwake: Boolean
     get() = playerView.keepScreenOn
     set(value) {
-      playerView.keepScreenOn = value
+      runOnMainThread {
+        playerView.keepScreenOn = value
+      }
     }
 
   var events = object : VideoViewEvents {
@@ -114,15 +134,7 @@ class VideoView @JvmOverloads constructor(
   }
 
   var onNitroIdChange: ((Int?) -> Unit)? = null
-  var playerView = PlayerView(context).apply {
-    layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
-    setShutterBackgroundColor(Color.TRANSPARENT)
-    setShowSubtitleButton(true)
-    useController = false
-
-    // Apply optimizations based on video player size if needed
-    configureForSmallPlayer()
-  }
+  var playerView = createPlayerView()
   var isInFullscreen: Boolean = false
     set(value) {
       field = value
@@ -153,6 +165,22 @@ class VideoView @JvmOverloads constructor(
     playerView.resizeMode = resizeMode.toAspectRatioFrameLayout()
   }
 
+  @SuppressLint("InflateParams")
+  private fun createPlayerView(): PlayerView {
+    return when (surfaceType) {
+      SurfaceType.SURFACE -> LayoutInflater.from(context).inflate(player_view_surface, null) as PlayerView
+      SurfaceType.TEXTURE -> LayoutInflater.from(context).inflate(player_view_texture, null) as PlayerView
+    }.apply {
+      layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
+      setShutterBackgroundColor(Color.TRANSPARENT)
+      setShowSubtitleButton(true)
+      useController = false
+
+      // Apply optimizations based on video player size if needed
+      configureForSmallPlayer()
+    }
+  }
+
   private val layoutRunnable = Runnable {
     measure(
       MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),

packages/react-native-video/android/src/main/java/com/twg/video/view/VideoView.kt

@@ -0,0 +1,7 @@
+<androidx.media3.ui.PlayerView 
+  android:id="@+id/player_view_surface"
+  android:layout_width="match_parent"
+  android:layout_height="match_parent"
+  xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:app="http://schemas.android.com/apk/res-auto"
+  app:surface_type="surface_view" />

packages/react-native-video/android/src/main/res/layout/player_view_surface.xml

@@ -0,0 +1,7 @@
+<androidx.media3.ui.PlayerView
+    android:id="@+id/player_view_texture"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    app:surface_type="texture_view" />

packages/react-native-video/android/src/main/res/layout/player_view_texture.xml

@@ -138,6 +138,9 @@ class HybridVideoViewViewManager: HybridVideoViewViewManagerSpec {
     }
   }
 
+  // Android only - no-op on iOS
+  var surfaceType: SurfaceType = .surface
+  
   func enterFullscreen() throws {
     guard let view else {
       throw VideoViewError.viewIsDeallocated.error()