向应用添加播放控件

播放媒体的应用需要用于显示媒体和控制播放的界面组件。Media3 库包含一个界面模块,该模块包含许多界面组件。如需依赖于界面模块,请添加以下依赖项:

Kotlin

implementation("androidx.media3:media3-ui:1.3.0")

Groovy

implementation "androidx.media3:media3-ui:1.3.0"

最重要的组件是 PlayerView,它是媒体播放的视图。PlayerView 在播放期间显示视频、字幕和专辑封面,以及播放控件。

PlayerView 有一个 setPlayer 方法,用于附加和分离(通过传递 null)玩家实例。

播放器视图

PlayerView 可用于视频和音频播放。它可在视频播放时呈现视频和字幕,并且可以显示作为元数据包含在音频文件中的海报图片。您可以像添加任何其他界面组件一样将其添加到布局文件中。例如,以下 XML 中可以包含 PlayerView

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

上面的代码段说明了 PlayerView 提供了多个属性。这些属性可用于自定义视图的行为及其外观和风格。其中大多数属性都有相应的 setter 方法,可用于在运行时自定义视图。PlayerView Javadoc 更详细地列出了这些属性和 setter 方法。

在布局文件中声明视图后,可以在 activity 的 onCreate 方法中查找视图:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

初始化播放器后,可以通过调用 setPlayer 将其附加到视图:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

选择表面类型

借助 PlayerViewsurface_type 属性,您可以设置用于视频播放的 surface 类型。除了 spherical_gl_surface_view(球形视频播放的特殊值)和 video_decoder_gl_surface_view(用于使用扩展程序渲染程序呈现视频)之外,允许的值还有 surface_viewtexture_viewnone。如果该视图仅用于音频播放,则应使用 none 以避免必须创建 Surface,因为这样做的开销可能会很高。

如果该视图用于常规视频播放,则应使用 surface_viewtexture_view。与 TextureView 相比,SurfaceView 在视频播放方面具有多项优势:

  • 在许多设备上显著降低功耗
  • 帧时间更准确,使视频播放更流畅。
  • 在符合条件的设备上支持更高质量的 HDR 视频输出。
  • 支持在播放受 DRM 保护的内容时的安全输出。
  • 能够在提升界面层的 Android TV 设备上以屏幕的完整分辨率呈现视频内容。

因此,应尽可能优先使用 SurfaceView,而非 TextureView。仅当 SurfaceView 无法满足您的需求时,才应使用 TextureView。例如,在 Android 7.0(API 级别 24)之前,需要在视频界面上流畅播放动画或进行滚动,如以下备注所述。在这种情况下,最好仅在 SDK_INT 小于 24 (Android 7.0) 时使用 TextureView,否则使用 SurfaceView

Android TV 上的方向键导航

Android TV 的遥控器具有方向键控件,该控件会发送以按键事件形式到达 ActivitydispatchKeyEvent(KeyEvent) 的命令。这些控件需要委托给播放器视图:

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

为播放器视图请求焦点对于浏览播放控件和跳过广告非常重要。考虑在 ActivityonCreate 中请求焦点:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

如果您在 Android TV 上使用 Compose,则需要将 AndroidView 设置为可聚焦,并通过将修饰符参数相应地传递到 AndroidView 来委托事件:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

替换可绘制对象

PlayerView 使用 PlayerControlView 显示播放控件和进度条。PlayerControlView 使用的可绘制对象可被应用中定义的名称相同的可绘制对象替换。如需查看可替换的控件可绘制对象的列表,请参阅 PlayerControlView Javadoc。

进一步自定义

如果需要进行上述自定义,我们预计应用开发者将实现自己的界面组件,而不是使用 Media3 的界面模块提供的组件。