📚 课程目录第2章 MediaSessionService定义

MediaSessionService 定义：服务声明、生命周期方法、绑定方式

MediaSessionService 是 Android 媒体后台调度的核心容器，本质上是一个继承自 Service 的组件，负责创建并管理 MediaSession，同时对外提供 MediaBrowser 协议接口。开发者必须在 AndroidManifest.xml 中显式声明该服务，并根据业务场景选择合适的生命周期实现与绑定方式。

2. ActivityManager 调度 Service 创建
3. Service 内部创建 MediaSession
4. onBind 返回 MediaBrowserService.Binder
5. 客户端获得 Binder 后可发起媒体控制

1. 服务声明

在 AndroidManifest.xml 的 <application> 内部添加 <service> 元素。关键属性说明：

属性	推荐值	说明
android:name	.MediaPlaybackService	指向具体 Service 子类
android:exported	true	允许外部应用通过 MediaBrowser 连接
android:permission	android.permission.BIND_MEDIA_BROWSER_SERVICE	系统级权限，保障安全性
android:foregroundServiceType	mediaPlayback / mediaProjection	Android 9+ 必须声明前台服务类型

<service
    android:name=".MediaPlaybackService"
    android:exported="true"
    android:permission="android.permission.BIND_MEDIA_BROWSER_SERVICE"
    android:foregroundServiceType="mediaPlayback">
    <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

⚠️ 权限声明陷阱：若省略 BIND_MEDIA_BROWSER_SERVICE 权限，系统在 Android 12+ 可能抛出 SecurityException；若 exported 为 false，第三方音乐应用将无法发现你的服务。

2. 生命周期方法

推荐继承 MediaBrowserServiceCompat（AndroidX），其生命周期回调如下表：

方法	触发时机	关键动作
`onCreate()`	服务首次创建	初始化 MediaSession、通知渠道、前台服务 Notification
`onStartCommand(Intent, int, int)`	每次显式 startService	返回 `START_STICKY` 确保进程重启后恢复
`onBind(Intent)`	客户端调用 bindService	返回 `onGetRoot()` 生成的 Binder 实例
`onUnbind(Intent)`	所有客户端解除绑定	返回 `true` 表示后续可调用 `onRebind`
`onRebind(Intent)`	曾绑定过的客户端再次绑定	重新关联 Binder
`onDestroy()`	服务被销毁	释放 MediaSession、停止前台通知、注销广播

public class MediaPlaybackService extends MediaBrowserServiceCompat {
    private MediaSessionCompat mediaSession;
    private MediaSessionCallback callback;

    @Override
    public void onCreate() {
        super.onCreate();
        mediaSession = new MediaSessionCompat(this, "MediaPlaybackService");
        callback = new MediaSessionCallback();
        mediaSession.setCallback(callback);
        setSessionToken(mediaSession.getSessionToken());
        // 创建通知渠道并启动前台服务
        startForeground(NOTIFICATION_ID, buildNotification());
    }

    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        // 确保服务在后台存活
        return START_STICKY;
    }

    @Override
    public BrowserRoot onGetRoot(@NonNull String clientPackageName,
                                  int clientUid,
                                  @Nullable Bundle rootHints) {
        // 验证客户端包名，允许所有或指定应用访问
        return new BrowserRoot(MEDIA_ROOT_ID, null);
    }

    @Override
    public void onLoadChildren(@NonNull String parentId,
                               @NonNull Result<List<MediaBrowserCompat.MediaItem>> result) {
        // 加载媒体树，异步返回
        result.sendResult(buildMediaItems());
    }

    @Override
    public void onDestroy() {
        mediaSession.release();
        super.onDestroy();
    }
}

3. 绑定方式

客户端使用 MediaBrowserCompat 连接服务，无需手动创建 ServiceConnection。推荐方式如下：

// 客户端代码片段
MediaBrowserCompat mediaBrowser = new MediaBrowserCompat(context,
        new ComponentName(context, MediaPlaybackService.class),
        new MediaBrowserCompat.ConnectionCallback() {
            @Override
            public void onConnected() {
                // 获取 MediaSession. 并连接控制器
                MediaSessionCompat.  = mediaBrowser.getSessionToken();
                MediaControllerCompat controller = new MediaControllerCompat(context, );
                MediaControllerCompat.setMediaController((Activity) context, controller);
            }

            @Override
            public void onConnectionFailed() {
                // 重试或提示用户
            }
        }, null);
mediaBrowser.connect();

如果需要深度定制绑定逻辑（如直接获取 Binder 调用自定义方法），可手动实现 ServiceConnection，但注意同时维护 MediaBrowser 的生命周期。

4. 调试方法

日志标签：在服务类中定义 private static final String TAG = "MediaService";，在生命周期回调中打印 Log.d(TAG, "onCreate")。
ADB 命令：adb shell dumpsys media_session 查看当前活跃的 MediaSession 列表；adb shell dumpsys activity services 检查服务进程状态。
前台服务测试：使用 adb shell dumpsys notification 确认前台通知是否正常展示。
绑定状态验证：在客户端 onServiceConnected 时打印 Binder 类名，确认返回类型正确。

5. 常见错误与避坑指南

错误现象	原因	解决方案
bindService 返回 false	服务未声明或 `exported=false`	检查 Manifest 中 `<service>` 和 `<intent-filter>`
onGetRoot 抛出 SecurityException	未正确处理包名校验	添加白名单或返回非 null 的 BrowserRoot
MediaSession 无法接收回调	setCallback 在 setSessionToken 之前调用	先创建 session，再 setCallback，最后 setSessionToken
服务频繁被杀死	未使用前台服务或 `START_STICKY`	在 onCreate 中调用 `startForeground()`，返回 `START_STICKY`
通知渠道无效（Android 8+）	未创建 NotificationChannel	在 Application 或 Service 初始化时创建渠道

6. 性能与稳定性优化

💡 优化策略：

前台服务优先级：始终在 onCreate 后立即调用 startForeground()，避免系统在后台资源紧张时杀死服务。
延迟初始化：在 onCreate 中只创建最核心的 MediaSession 和 Notification，耗时的媒体库扫描放到异步线程或 onLoadChildren 中处理。
Binder 线程池设计：onLoadChildren 默认在 Binder 线程池中执行，若数据处理较慢应使用 result.detach() 再异步发送，避免阻塞连接。
内存泄漏防范：在 onDestroy 中释放 MediaSession、置空回调引用、取消未完成的异步任务。
多进程场景：若服务运行在独立进程，注意跨进程传递 MediaSession. 时使用 Bundle 序列化，避免 ServiceConnection 回调中的类加载问题。