后台触发Media3播放时出现ForegroundServiceStartNotAllowedException问题

背景 #

使用Media3库播放媒体内容，应用在前台时调用mediaController.play()可正常运行。

业务场景 #

播放列表中的曲目无固定mediaUri（实际.mp3文件链接），需先获取含30首曲目的播放列表，再逐轨获取有效期仅2分钟的临时播放链接。

当前解决方案 #

通过Worker类监听播放器状态流，当状态为STATE_ENDED时，获取下一曲目的临时播放链接，执行mediaController.setMediaItems > prepare() > play()流程播放新曲目。

遇到的问题 #

应用处于后台（息屏）状态时，曲目播放结束后新曲目可正常播放，但会触发ForegroundServiceStartNotAllowedException（无崩溃），且媒体通知图片无法更新。

错误日志 #

Failed to start foreground android.app.ForegroundServiceStartNotAllowedException: Service.startForeground() not allowed due to mAllowStartForeground false: service 'APPNAME.media.MediaService`

已配置权限与Service声明 #

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<application>...
     <service
          android:name=".MediaService"
          android:enabled="true"
          android:exported="false"
          android:foregroundServiceType="mediaPlayback|dataSync">
          <intent-filter>
              <action android:name="androidx.media3.session.MediaSessionService" />
              <action android:name="android.media.browse.MediaBrowserService" />
          </intent-filter>
      </service>
</application>

播放调用函数 #

private fun playAppPlaylist(startAtIndex: Int = 0) {
    val browser = this.browser ?: return
    val items = browser.getChildren(
        Catalog.AppPlaylist.path, 0, Int.MAX_VALUE, null
    )
    items.addListener({
        val result = items.get()
        val children = result.value!!

        browser.setMediaItems(children)
        browser.prepare()
        if (startAtIndex != 0) browser.seekTo(startAtIndex, 0)
        else browser.seekToDefaultPosition()
        browser.play()
    }, MoreExecutors.directExecutor())
}

尝试过的方法 #

曾尝试使用controller.replaceMediaItem()替代play()，但播放器进入Player.STATE_ENDED状态后已暂停，无法启动播放。

核心问题分析 #

错误根源是Android 12+对后台启动前台服务的严格限制：Media3的MediaSessionService在播放状态变更时，如果服务未处于前台，会尝试调用startForeground()，但后台场景下该操作被系统禁止，从而抛出异常。同时通知图片无法更新也是因为服务无法正常更新前台通知。

具体修复步骤 #

1. 让MediaSessionService始终保持前台状态
   在继承MediaSessionService的MediaService中，主动在onCreate()或onGetSession()方法中启动前台服务，不要依赖播放器状态变更自动触发：

   private val NOTIFICATION_ID = 1001
   
   override fun onCreate() {
       super.onCreate()
       // 构建符合媒体播放规范的通知（需包含播放控制按钮、曲目信息等）
       val playbackNotification = createMediaPlaybackNotification()
       // 启动前台服务，指定类型为mediaPlayback
       startForeground(NOTIFICATION_ID, playbackNotification, FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK)
   }
   

   服务启动后一直处于前台，后台切换曲目时不会触发新的startForeground()调用，规避权限限制。

2. 将曲目切换逻辑移至MediaSessionService内部
   不要通过Worker跨组件调用播放器操作，直接在服务内部用Player.Listener监听播放结束事件，减少状态异常：

   player.addListener(object : Player.Listener {
       override fun onPlaybackStateChanged(playbackState: Int) {
           super.onPlaybackStateChanged(playbackState)
           if (playbackState == Player.STATE_ENDED) {
               // 获取下一曲临时链接
               fetchNextTrackUri { uri ->
                   val nextMediaItem = MediaItem.fromUri(uri)
                   player.setMediaItem(nextMediaItem)
                   player.prepare()
                   player.play()
                   // 手动更新通知内容（包括曲目图片）
                   updateMediaNotification(nextMediaItem)
               }
           }
       }
   })
   

3. 手动更新媒体通知
   切换曲目时，手动构建新通知并调用NotificationManager.notify()更新，确保曲目图片、标题等信息同步更新，不要依赖Media3自动处理。

4. 精简Service配置
   移除foregroundServiceType中的dataSync（除非确实需要数据同步），只保留mediaPlayback，避免类型混淆导致系统限制。

内容的提问来源于stack exchange，提问作者hbarn