途徑類型

本頁面說明可透過 Media3 播放影片的不同類型介面，以及如何根據用途選擇合適的類型。如要進一步瞭解 Android 中的 Surface 物件，請參閱這份圖像說明文件。

設定途徑

Player 有四個介面，可將視訊輸出連接至Surface：

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

清除方式也有所不同：

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

為 PlayerView 選擇介面類型

PlayerView 的 surface_type 屬性可讓你設定用於影片播放的介面類型。允許的值如下：

• surface_view (SurfaceView)
• texture_view (TextureView)
• spherical_gl_surface_view (SphericalGLSurfaceView) - 適用於球形影片播放
• video_decoder_gl_surface_view (VideoDecoderGLSurfaceView) - 使用擴充功能算繪器算繪影片
• none，僅用於音訊播放，應避免建立介面，因為這樣做可能很昂貴。

如果是用於一般影片播放，則應使用 surface_view 或 texture_view。SurfaceView 相較於 TextureView，在影片播放方面有許多優點：

• 大幅降低許多裝置的耗電量。
• 影格時間更準確，影片播放更流暢。
• 在支援的裝置上輸出更高畫質的 HDR 影片。
• 播放受 DRM 保護的內容時，支援安全輸出。
• 在會放大 UI 層的 Android TV 裝置上，以螢幕完整解析度顯示影片內容。

因此，建議盡可能使用 SurfaceView 而非 TextureView。只有在 SurfaceView 無法滿足需求時，才應使用 TextureView。舉例來說，在 Android 7.0 (API 級別 24) 之前，如果需要流暢的動畫或影片表面捲動效果，就必須使用這個方法，詳情請參閱下列附註。在這種情況下，建議僅在 SDK_INT 小於 24 (Android 7.0) 時使用 TextureView，否則請使用 SurfaceView。

在 Compose 中選擇介面類型

在 Compose 中，互通解決方案會使用 AndroidView 可組合函式包裝 SurfaceView 和 TextureView。對應的兩個可組合函式分別是 androidx.compose.foundation 中的 AndroidExternalSurface 和 AndroidEmbeddedExternalSurface。不過，這些 Proxy 類別提供的 API 介面會限制基礎檢視區塊的存取權。Player 需要這些檢視區塊，才能處理途徑的完整生命週期 (建立和大小更新)。

在 media3-ui-compose 模組中，您可以找到 ContentFrame 和 PlayerSurface 可組合項，以生命週期感知方式將 Player 連結至 Surface。在本例中，介面類型如下：

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

沒有 none 類型，因為這會對應至不在 Compose UI 樹狀結構中加入可組合函式。