Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Cette page décrit les différents types de surfaces pouvant être utilisées pour la lecture vidéo avec Media3, et explique comment choisir le type adapté à votre cas d'utilisation. Pour en savoir plus sur les objets Surface dans Android, consultez cette documentation sur les graphiques.
Choisir un type de surface pour PlayerView
L'attribut surface_type de PlayerView vous permet de définir le type de surface utilisé pour la lecture de la vidéo. Les valeurs autorisées sont les suivantes :
spherical_gl_surface_view (SphericalGLSurfaceView) : pour la lecture de vidéos sphériques
video_decoder_gl_surface_view (VideoDecoderGLSurfaceView) : rendu vidéo à l'aide de renderers d'extension
none, qui est réservé à la lecture audio et doit être utilisé pour éviter d'avoir à créer une surface, car cela peut être coûteux.
Si la vue est destinée à la lecture de vidéos classiques, surface_view ou texture_view doivent être utilisés. SurfaceView présente plusieurs avantages par rapport à TextureView pour la lecture de vidéos :
Un timing des images plus précis, ce qui permet une lecture plus fluide des vidéos.
Prise en charge de la sortie vidéo HDR de meilleure qualité sur les appareils compatibles.
Prise en charge de la sortie sécurisée lors de la lecture de contenu protégé par DRM.
Possibilité d'afficher du contenu vidéo à la résolution maximale de l'écran sur les appareils Android TV qui mettent à l'échelle la couche d'interface utilisateur.
Dans la mesure du possible, il est donc préférable d'utiliser SurfaceView plutôt que TextureView.
TextureView ne doit être utilisé que si SurfaceView ne répond pas à vos besoins. Par exemple, des animations fluides ou le défilement de la surface vidéo sont nécessaires avant Android 7.0 (niveau d'API 24), comme décrit dans les notes suivantes. Dans ce cas, il est préférable d'utiliser TextureView uniquement lorsque SDK_INT est inférieur à 24 (Android 7.0) et SurfaceView dans le cas contraire.
Le module Media3 ui-compose fournit un composable PlayerSurface qui associe Player à un Surface en tenant compte du cycle de vie. Dans ce cas, les types de surface sont les suivants :
Il n'existe pas de type none, car cela correspondrait à ne pas inclure PlayerSurface dans votre arborescence de l'UI Compose.
Le contenu et les exemples de code de cette page sont soumis aux licences décrites dans la Licence de contenu. Java et OpenJDK sont des marques ou des marques déposées d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/27 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Il n'y a pas l'information dont j'ai besoin","missingTheInformationINeed","thumb-down"],["Trop compliqué/Trop d'étapes","tooComplicatedTooManySteps","thumb-down"],["Obsolète","outOfDate","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Mauvais exemple/Erreur de code","samplesCodeIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/08/27 (UTC)."],[],[],null,["This page describes the different types of surfaces that can be used for video\nplayback with Media3, and how to choose the right type for your use case. To\nfind out more about Surface objects in Android, read this [graphics\ndocumentation](https://source.android.com/docs/core/graphics/arch-sh).\n\nChoose a surface type for PlayerView\n\nThe `surface_type` attribute of [`PlayerView`](/reference/androidx/media3/ui/PlayerView) lets you set the type of\nsurface used for video playback. The allowed values are:\n\n- `surface_view` ([`SurfaceView`](/reference/android/view/SurfaceView))\n- `texture_view` ([`TextureView`](/reference/android/view/TextureView))\n- `spherical_gl_surface_view` ([`SphericalGLSurfaceView`](/reference/androidx/media3/exoplayer/video/spherical/SphericalGLSurfaceView)) - for spherical video playback\n- `video_decoder_gl_surface_view` ([`VideoDecoderGLSurfaceView`](/reference/androidx/media3/exoplayer/video/VideoDecoderGLSurfaceView)) - video rendering using extension renderers\n- `none` - which is for audio playback only and should be used to avoid having to create a surface because doing so can be expensive.\n\nIf the view is for regular video playback then `surface_view` or `texture_view`\nshould be used. [`SurfaceView`](/reference/android/view/SurfaceView) has a number of benefits over\n[`TextureView`](/reference/android/view/TextureView) for video playback:\n\n- Significantly [lower power consumption](/media/media3/exoplayer/battery-consumption) on many devices.\n- More accurate frame timing, resulting in smoother video playback.\n- Support for higher quality HDR video output on capable devices.\n- Support for secure output when playing DRM-protected content.\n- The ability to render video content at the full resolution of the display on Android TV devices that upscale the UI layer.\n\n`SurfaceView` should therefore be preferred over `TextureView` where possible.\n`TextureView` should be used only if `SurfaceView` does not meet your needs. One\nexample is where smooth animations or scrolling of the video surface is required\nprior to Android 7.0 (API level 24), as described in the following notes. For\nthis case, it's preferable to use `TextureView` only when [`SDK_INT`](/reference/android/os/Build.VERSION#SDK_INT) is less\nthan 24 (Android 7.0) and `SurfaceView` otherwise.\n| **Note:** `SurfaceView` rendering wasn't properly synchronized with view animations until Android 7.0 (API level 24). On earlier releases, improper synchronization could result in unwanted effects when a `SurfaceView` was placed into a scrolling container, or when it was animated. Unwanted effects included the view's contents appearing to lag slightly behind where it should be displayed, and the view turning black when animated. To achieve smooth animation or scrolling of video prior to Android 7.0, use `TextureView` rather than `SurfaceView`.\n| **Note:** The lifecycle of a `SurfaceView`'s surface is tied to view visibility, whereas a `TextureView`'s surface lifecycle is tied to window attachment and detachment. Therefore, in scrolling UIs that use `SurfaceView`, starting playback can take longer because the output surface becomes available slightly later. From Android 14 onwards, `PlayerView` uses [`SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT)`](/reference/android/view/SurfaceView#setSurfaceLifecycle(int)) to avoid this behavior. If your app uses `SurfaceView` directly (without `PlayerView`) then you may want to enable this mode. Before Android 14, it's possible to work around the surface being destroyed by translating views off-screen when recycling them.\n| **Note:** Some Android TV devices run their UI layer at a resolution that's lower than the full resolution of the display, upscaling it for presentation to the user. For example, the UI layer may be run at 1080p on an Android TV that has a 4K display. On such devices, `SurfaceView` must be used to render content at the full resolution of the display. The full resolution of the display (in its current display mode) can be queried using [`Util.getCurrentDisplayModeSize`](/reference/androidx/media3/common/util/Util#getCurrentDisplayModeSize(android.content.Context)). The UI layer resolution can be queried using Android's [`Display.getSize`](/reference/android/view/Display#getSize(android.graphics.Point)) API.\n| **Note:** If you are using `PlayerView` inside of `AndroidView`, we cannot guarantee compatibility because `PlayerView` was not made with Compose in mind. One of the common problems for `SDK_INT == 34` is a stretched/cropped/leaked Surface that does not match the parent container (`AspectRatioFrameLayout`) correctly. You can opt into a Compose workaround by calling `PlayerView.setEnableComposeSurfaceSyncWorkaround`, but note that it causes issues with XML-based shared transitions.\n\nChoose a surface type in Compose\n\nIn Compose, the interop solution uses the `AndroidView` Composable to wrap\n[`SurfaceView`](/reference/android/view/SurfaceView) and [`TextureView`](/reference/android/view/TextureView). The two Composables that correspond to\nthat are [`AndroidExternalSurface`](/reference/kotlin/androidx/compose/foundation/package-summary#AndroidExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.foundation.AndroidExternalSurfaceZOrder,kotlin.Boolean,kotlin.Function1)) and [`AndroidEmbeddedExternalSurface`](/reference/kotlin/androidx/compose/foundation/package-summary#AndroidEmbeddedExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.ui.graphics.Matrix,kotlin.Function1)).\n\nMedia3 `ui-compose` module provides a [`PlayerSurface`](https://developer.android.com/reference/kotlin/androidx/media3/ui/compose/package-summary#PlayerSurface(androidx.media3.common.Player,androidx.compose.ui.Modifier,kotlin.Int)) Composable that links\nthe [`Player`](/reference/androidx/media3/common/Player) to a `Surface` in a lifecycle-aware manner. The surface types\nin this case are:\n\n- `SURFACE_TYPE_SURFACE_VIEW` (effectively [`AndroidExternalSurface`](/reference/kotlin/androidx/compose/foundation/package-summary#AndroidExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.foundation.AndroidExternalSurfaceZOrder,kotlin.Boolean,kotlin.Function1)))\n- `SURFACE_TYPE_TEXTURE_VIEW` (effectively [`AndroidEmbeddedExternalSurface`](/reference/kotlin/androidx/compose/foundation/package-summary#AndroidEmbeddedExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.ui.graphics.Matrix,kotlin.Function1)))\n\nThere is no type `none`, since that would correspond to not including the\n`PlayerSurface` in your Compose UI tree."]]
