AndroidX Media3中自定义会话命令的正确使用方式

前言

在开发音乐播放应用时，AndroidX Media3库提供了强大的媒体会话功能，允许开发者实现自定义控制命令。本文将详细介绍如何在Media3中正确实现和使用自定义会话命令(SessionCommand)，避免常见的实现错误。

自定义会话命令的基本实现

在Media3中，自定义会话命令需要通过MediaSessionService来实现。以下是实现的基本步骤：

1. 定义命令常量： 建议使用Kotlin常量来定义命令名称，保持一致性：

   const val LIKE = "like"
   const val DISLIKE = "dislike"
   

2. 在MediaSessionService中注册命令： 需要在onConnect方法中将自定义命令添加到可用会话命令中：

   override fun onConnect(
       session: MediaSession,
       controller: MediaSession.ControllerInfo
   ): MediaSession.ConnectionResult {
       val sessionCommands = MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
           .add(SessionCommand(LIKE, Bundle.EMPTY))
           .add(SessionCommand(DISLIKE, Bundle.EMPTY))
           .build()
       return MediaSession.ConnectionResult.AcceptedResultBuilder(session)
           .setAvailableSessionCommands(sessionCommands)
           .build()
   }
   

3. 处理命令逻辑： 在onCustomCommand方法中处理具体的命令逻辑：

   override fun onCustomCommand(
       session: MediaSession,
       controller: MediaSession.ControllerInfo,
       customCommand: SessionCommand,
       args: Bundle
   ): ListenableFuture<SessionResult> {
       when (customCommand.customAction) {
           LIKE -> {
               // 喜欢逻辑
               return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
           }
           DISLIKE -> {
               // 不喜欢逻辑
               return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
           }
           else -> {
               return Futures.immediateFuture(SessionResult(SessionError.ERROR_BAD_VALUE))
           }
       }
   }
   

从Activity调用自定义命令

要从Activity调用这些自定义命令，需要注意以下几点：

1. 确保命令名称完全一致： 这是最常见的错误来源。命令名称必须与服务端定义的完全一致，包括大小写。

   错误示例：

   // 错误：使用了不同的大小写
   val likeCommand = SessionCommand("LIKE", Bundle.EMPTY)
   

   正确做法：

   // 正确：使用与服务端完全相同的常量
   val likeCommand = SessionCommand(LIKE, Bundle.EMPTY)
   

2. 建立MediaController连接： 需要先建立与MediaSessionService的连接：

   val sessionToken = SessionToken(
       applicationContext, 
       ComponentName(applicationContext, MusicPlayerService::class.java)
   )
   
   val mediacontrollerFuture = MediaController.Builder(applicationContext, sessionToken).buildAsync()
   
   mediacontrollerFuture.addListener({
       player = mediacontrollerFuture.get()
   }, ContextCompat.getMainExecutor(applicationContext))
   

3. 发送自定义命令： 通过MediaController发送命令：

   likeButton.setOnClickListener {
       player?.sendCustomCommand(likeCommand, Bundle.EMPTY)
   }
   

常见问题排查

如果遇到"Controller isn't allowed to call custom session command"警告，请检查：

1. 命令名称是否与服务端注册的完全一致
2. 是否在onConnect方法中正确添加了命令
3. MediaController是否已成功连接到MediaSessionService
4. 是否使用了相同的常量定义命令名称

最佳实践建议

1. 使用常量定义命令名称：避免硬编码字符串，减少拼写错误风险
2. 统一大小写：建议全部使用小写，减少混淆
3. 错误处理：在onCustomCommand中为未知命令添加默认处理
4. 日志记录：添加适当的日志，便于调试命令调用过程

总结

正确实现Media3的自定义会话命令需要注意命令名称的一致性，特别是大小写问题。通过使用常量定义命令名称，并在服务端和客户端使用相同的定义，可以避免大多数调用失败的问题。这种机制为开发者提供了强大的扩展能力，可以灵活地实现各种自定义播放控制功能。