AndroidX Media3 迁移指南

MediaSessionConnector 在 Media3 中的功能

下表显示了处理以前在 MediaSessionConnector 中实现的功能的 Media3 API。

将 MediaBrowserService 迁移到 MediaLibraryService

AndroidX Media3 引入了 MediaLibraryService，它取代了 MediaBrowserServiceCompat。 MediaLibraryService 及其父类 MediaSessionService 的 JavaDoc 提供了有关 API 和服务异步编程模型的良好介绍。

MediaLibraryService 与 MediaBrowserService 向后兼容。使用 MediaBrowserCompat 或 MediaControllerCompat 的客户端应用在连接到 MediaLibraryService 时，无需代码更改即可继续工作。对于客户端来说，您的应用是使用 MediaLibraryService 还是旧版 MediaBrowserServiceCompat 是透明的。

1. 为了使向后兼容性起作用，您需要在 AndroidManifest.xml 中注册服务接口。这样，客户端就可以通过所需的接口找到您的服务。

   <service android:name=".MusicService" android:exported="true">
       <intent-filter>
           <action android:name="androidx.media3.session.MediaLibraryService"/>
           <action android:name="android.media.browse.MediaBrowserService" />
       </intent-filter>
   </service>
   

2. 在维护依赖项的 build.gradle 文件中，添加对 AndroidX Media3 会话模块 的实现依赖项，并删除旧版依赖项。

   implementation "androidx.media3:media3-session:1.4.1"
   

3. 将您的服务更改为继承自 MediaLibraryService 而不是 MediaBrowserService。如前所述，MediaLibraryService 与旧版 MediaBrowserService 兼容。因此，服务提供给客户端的更广泛的 API 仍然相同。因此，应用很可能可以保留实现 MediaBrowserService 所需的大部分逻辑，并将其适配到新的 MediaLibraryService。

   与旧版 MediaBrowserServiceCompat 相比，主要区别如下：

   • 实现服务生命周期方法：服务本身需要重写的方法是 onCreate/onDestroy，应用在其中分配/释放库会话、播放器和其他资源。除了标准的服务生命周期方法外，应用还需要重写 onGetSession(MediaSession.ControllerInfo) 以返回在 onCreate 中构建的 MediaLibrarySession。

   • 实现 MediaLibraryService.MediaLibrarySessionCallback：构建会话需要一个 MediaLibraryService.MediaLibrarySessionCallback，它实现实际的域 API 方法。因此，您将重写 MediaLibrarySession.Callback 的方法，而不是重写旧版服务的 API 方法。

     然后使用回调来构建 MediaLibrarySession。

     mediaLibrarySession =
           MediaLibrarySession.Builder(this, player, MySessionCallback())
              .build()
     

     在 API 文档中查找 MediaLibrarySessionCallback 的完整 API。

   • 实现 MediaSession.Callback.onAddMediaItems()：回调 onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) 用于各种当前和旧版 API 方法，这些方法以向后兼容的方式将媒体项添加到播放器以进行播放。这包括 Media3 控制器 MediaController.set/addMediaItems() 方法以及旧版 API 的 TransportControls.prepareFrom*/playFrom* 方法。可以在 会话演示应用的 PlaybackService 中 找到回调的示例实现。

   • AndroidX Media3 使用 androidx.media3.common.MediaItem 而不是 MediaBrowserCompat.MediaItem 和 MediaMetadataCompat。与旧版类相关的代码部分需要相应地更改或映射到 Media3 MediaItem。

   • 一般的异步编程模型更改为 Futures，而不是 MediaBrowserServiceCompat 的可分离 Result 方法。您的服务实现可以返回异步 ListenableFuture，而不是分离结果或 返回立即 Future 以直接返回值。

删除 PlayerNotificationManager

MediaLibraryService 自动支持媒体通知，并且在使用 MediaLibraryService 或 MediaSessionService 时可以删除 PlayerNotificationManager。

应用可以通过在 onCreate() 中设置自定义 MediaNotification.Provider 来自定义通知，该自定义项替换了 DefaultMediaNotificationProvider。然后，MediaLibraryService 会根据需要将服务置于前台。

通过重写 MediaLibraryService.updateNotification()，应用可以进一步完全控制发布通知以及根据需要启动/停止前台服务。

迁移使用 MediaBrowser 的客户端代码

在 AndroidX Media3 中，MediaBrowser 实现 MediaController/Player 接口，除了浏览媒体库外，还可以用于控制媒体播放。如果您必须在旧版环境中创建 MediaBrowserCompat 和 MediaControllerCompat，则只需在 Media3 中使用 MediaBrowser 即可完成相同操作。

MediaBrowser 可以构建并等待与服务的连接建立。

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

查看 在媒体会话中控制播放，了解如何在后台创建 MediaController 以控制播放。

后续步骤和清理

不稳定 API 错误

迁移到 Media3 后，您可能会看到有关不稳定 API 用法的 lint 错误。这些 API 可以安全使用，lint 错误是我们新的二进制兼容性保证的副产品。如果您不需要严格的二进制兼容性，则可以使用 @OptIn 注解安全地抑制这些错误。

背景

ExoPlayer v1 和 v2 都没有提供关于后续版本之间库的二进制兼容性的严格保证。ExoPlayer API 表面在设计上非常庞大，以便允许应用自定义播放的几乎每个方面。ExoPlayer 的后续版本偶尔会引入符号重命名或其他重大更改（例如，接口上的新必需方法）。在大多数情况下，这些中断通过在弃用旧符号的同时引入新符号来缓解，以使开发人员有时间迁移其用法，但这并非总是可能的。

这些重大更改导致 ExoPlayer v1 和 v2 库用户遇到两个问题：

1. 从 ExoPlayer 版本升级可能会导致代码停止编译。
2. 直接和通过中间库依赖于 ExoPlayer 的应用必须确保两个依赖项的版本相同，否则二进制不兼容性可能会导致运行时崩溃。

Media3 中的改进

Media3 保证 API 表面子集的二进制兼容性。不保证二进制兼容性的部分用 @UnstableApi 标记。为了使这种区别更加清晰，除非使用 @OptIn 进行注释，否则不稳定 API 符号的使用会生成 lint 错误。

从 ExoPlayer v2 迁移到 Media3 后，您可能会看到很多不稳定的 API lint 错误。这可能会让您觉得 Media3 比 ExoPlayer v2 “不稳定”。情况并非如此。“不稳定”的 Media3 API 部分具有与 ExoPlayer v2 API 表面的 **整体** 相同的稳定性级别，并且 ExoPlayer v2 完全无法获得稳定的 Media3 API 表面的保证。区别仅仅在于 lint 错误现在会提醒您不同级别的稳定性。

处理不稳定的 API lint 错误

有关如何使用 @OptIn 注释 Java 和 Kotlin 中不稳定 API 的用法的详细信息，请参阅 有关这些 lint 错误的故障排除部分。

已弃用的 API

您可能会注意到 Android Studio 中已弃用的 API 调用被删除线划掉。我们建议使用相应的替代方法替换这些调用。将鼠标悬停在符号上以查看 JavaDoc，该文档说明了要使用哪个 API 代替。

代码示例和演示应用

• AndroidX Media3 会话演示应用（移动设备和 WearOS）
  • 自定义操作
  • 系统 UI 通知、MediaButton/BT
  • Google 助理播放控制
• UAMP：Android 媒体播放器（分支 media3）（移动设备、AutomotiveOS）
  • 系统 UI 通知、MediaButton/BT、播放恢复
  • Google 助理/WearOS 播放控制
  • AutomotiveOS：自定义命令和登录