Surface types

This page describes the different types of surfaces that can be used for video playback with Media3, and how to choose the right type for your use case. To find out more about Surface objects in Android, read this graphics documentation.

Set the surface

There are four entry points for the Player to connect its video output to some Surface:

• void setVideoSurface(@Nullable Surface surface)
• void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void setVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void setVideoTextureView(@Nullable TextureView textureView)

There are also different ways to clear it:

• void clearVideoSurface()
• void clearVideoSurface(@Nullable Surface surface)
• void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void clearVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void clearVideoTextureView(@Nullable TextureView textureView)

Choose a surface type for PlayerView

The surface_type attribute of PlayerView lets you set the type of surface used for video playback. The allowed values are:

• surface_view (SurfaceView)
• texture_view (TextureView)
• spherical_gl_surface_view (SphericalGLSurfaceView) - for spherical video playback
• video_decoder_gl_surface_view (VideoDecoderGLSurfaceView) - video rendering using extension renderers
• none - which is for audio playback only and should be used to avoid having to create a surface because doing so can be expensive.

If the view is for regular video playback then surface_view or texture_view should be used. SurfaceView has a number of benefits over TextureView for video playback:

• Significantly lower power consumption on many devices.
• More accurate frame timing, resulting in smoother video playback.
• Support for higher quality HDR video output on capable devices.
• Support for secure output when playing DRM-protected content.
• The ability to render video content at the full resolution of the display on Android TV devices that upscale the UI layer.

SurfaceView should therefore be preferred over TextureView where possible. TextureView should be used only if SurfaceView does not meet your needs. One example is where smooth animations or scrolling of the video surface is required prior to Android 7.0 (API level 24), as described in the following notes. For this case, it's preferable to use TextureView only when SDK_INT is less than 24 (Android 7.0) and SurfaceView otherwise.

Choose a surface type in Compose

In Compose, the interop solution uses the AndroidView Composable to wrap SurfaceView and TextureView. The two Composables that correspond to that are AndroidExternalSurface and AndroidEmbeddedExternalSurface from androidx.compose.foundation. However, these proxy classes provide an API surface that limits access of the underlying views. Those views are needed by the Player to handle a full lifecycle of the surface (creation and size updates).

In media3-ui-compose module, you can find ContentFrame and PlayerSurface composables that link the Player to a Surface in a lifecycle-aware manner. The surface types in this case are:

• androidx.media3.ui.compose.SURFACE_TYPE_SURFACE_VIEW
• androidx.media3.ui.compose.SURFACE_TYPE_TEXTURE_VIEW

There is no type none, since that would correspond to not including the composable in your Compose UI tree.