การเล่นขณะล็อกหน้าจอหรือขณะใช้แอปอื่นด้วย MediaSessionService

บ่อยครั้งที่คุณต้องการเล่นสื่อขณะที่แอปไม่ได้อยู่เบื้องหน้า สำหรับ ตัวอย่างเช่น โปรแกรมเล่นเพลงมักจะเล่นเพลงต่อไปเมื่อผู้ใช้ล็อก อุปกรณ์ของตนเองหรือกำลังใช้แอปอื่น ไลบรารี Media3 นำเสนอชุดของ อินเทอร์เฟซที่ช่วยให้คุณรองรับการเล่นขณะล็อกหน้าจอหรือขณะใช้แอปอื่น

ใช้ MediaSessionService

หากต้องการเปิดใช้การเล่นขณะล็อกหน้าจอหรือขณะใช้แอปอื่น คุณควรใส่ Player และ MediaSession ไว้ในบริการแยกต่างหาก วิธีนี้จะช่วยให้อุปกรณ์แสดงสื่อต่อไปได้แม้ว่าแอปของคุณจะไม่ได้อยู่ในส่วนดังกล่าว เบื้องหน้า

MediaSessionService ช่วยให้เซสชันสื่อทำงานแยกจากกิจกรรมของแอปได้
รูปที่ 1: MediaSessionService ช่วยให้สื่อ เซสชันที่จะเรียกใช้แยกต่างหากจากกิจกรรมบนแอป

เมื่อโฮสต์โปรแกรมเล่นภายในบริการ คุณควรใช้ MediaSessionService ในการดำเนินการนี้ ให้สร้างชั้นเรียนที่ขยาย MediaSessionService และสร้าง สื่อภายในเซสชัน

การใช้ MediaSessionService จะช่วยให้ลูกค้าภายนอกอย่างเช่น Google สามารถ Assistant, ตัวควบคุมสื่อของระบบ หรืออุปกรณ์ที่ใช้ร่วมกัน เช่น Wear OS เพื่อสํารวจ บริการ เชื่อมต่อ และควบคุมการเล่นได้โดยไม่ต้องเข้าถึง กิจกรรม UI ของแอปเลย ในความเป็นจริง อาจมีแอปไคลเอ็นต์เชื่อมต่อหลายแอป เป็น MediaSessionService เดียวกันในเวลาเดียวกัน ในแต่ละแอป MediaController

ใช้วงจรการบริการ

คุณต้องติดตั้งใช้งานเมธอดวงจรชีวิตของบริการ 3 รายการ ได้แก่

  • onCreate() จะเรียกใช้เมื่อตัวควบคุมตัวแรกกำลังเชื่อมต่อ และระบบจะสร้างอินสแตนซ์และเริ่มบริการ เพราะเป็นแพลตฟอร์มที่เหมาะสําหรับการสร้าง Player และ MediaSession
  • onTaskRemoved(Intent) จะเรียกใช้เมื่อผู้ใช้ปิดแอปจากงานล่าสุด หากการเล่นดำเนินอยู่ แอปสามารถเลือกที่จะให้บริการทำงานอยู่เบื้องหน้าต่อไปได้ หากโปรแกรมเล่นหยุดชั่วคราว แสดงว่าบริการไม่ได้อยู่ใน เบื้องหน้าและจำเป็นต้องหยุด
  • onDestroy() จะเรียกใช้เมื่อมีการหยุดบริการ คุณต้องปล่อยทรัพยากรทั้งหมด รวมถึงผู้เล่นและเซสชัน

Kotlin

class PlaybackService : MediaSessionService() {
  private var mediaSession: MediaSession? = null

  // Create your player and media session in the onCreate lifecycle event
  override fun onCreate() {
    super.onCreate()
    val player = ExoPlayer.Builder(this).build()
    mediaSession = MediaSession.Builder(this, player).build()
  }

  // The user dismissed the app from the recent tasks
  override fun onTaskRemoved(rootIntent: Intent?) {
    val player = mediaSession?.player!!
    if (!player.playWhenReady
        || player.mediaItemCount == 0
        || player.playbackState == Player.STATE_ENDED) {
      // Stop the service if not playing, continue playing in the background
      // otherwise.
      stopSelf()
    }
  }

  // Remember to release the player and media session in onDestroy
  override fun onDestroy() {
    mediaSession?.run {
      player.release()
      release()
      mediaSession = null
    }
    super.onDestroy()
  }
}

Java

public class PlaybackService extends MediaSessionService {
  private MediaSession mediaSession = null;

  // Create your Player and MediaSession in the onCreate lifecycle event
  @Override
  public void onCreate() {
    super.onCreate();
    ExoPlayer player = new ExoPlayer.Builder(this).build();
    mediaSession = new MediaSession.Builder(this, player).build();
  }

  // The user dismissed the app from the recent tasks
  @Override
  public void onTaskRemoved(@Nullable Intent rootIntent) {
    Player player = mediaSession.getPlayer();
    if (!player.getPlayWhenReady()
        || player.getMediaItemCount() == 0
        || player.getPlaybackState() == Player.STATE_ENDED) {
      // Stop the service if not playing, continue playing in the background
      // otherwise.
      stopSelf();
    }
  }

  // Remember to release the player and media session in onDestroy
  @Override
  public void onDestroy() {
    mediaSession.getPlayer().release();
    mediaSession.release();
    mediaSession = null;
    super.onDestroy();
  }
}

นอกเหนือจากการเล่นอย่างต่อเนื่องในเบื้องหลังแล้ว แอปสามารถหยุดบริการได้ทุกเมื่อที่ผู้ใช้ปิดแอป ดังนี้

Kotlin

override fun onTaskRemoved(rootIntent: Intent?) {
  val player = mediaSession.player
  if (player.playWhenReady) {
    // Make sure the service is not in foreground.
    player.pause()
  }
  stopSelf()
}

Java

@Override
public void onTaskRemoved(@Nullable Intent rootIntent) {
  Player player = mediaSession.getPlayer();
  if (player.getPlayWhenReady()) {
    // Make sure the service is not in foreground.
    player.pause();
  }
  stopSelf();
}

ให้สิทธิ์เข้าถึงเซสชันสื่อ

ลบล้างเมธอด onGetSession() เพื่อให้ไคลเอ็นต์รายอื่นเข้าถึงเซสชันสื่อที่สร้างขึ้นเมื่อสร้างบริการ

Kotlin

class PlaybackService : MediaSessionService() {
  private var mediaSession: MediaSession? = null
  // [...] lifecycle methods omitted

  override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession? =
    mediaSession
}

Java

public class PlaybackService extends MediaSessionService {
  private MediaSession mediaSession = null;
  // [...] lifecycle methods omitted

  @Override
  public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
    return mediaSession;
  }
}

ประกาศบริการในไฟล์ Manifest

แอปต้องการสิทธิ์เพื่อเรียกใช้บริการที่ทำงานอยู่เบื้องหน้า เพิ่ม FOREGROUND_SERVICE สำหรับไฟล์ Manifest และหากคุณกำหนดเป้าหมายเป็น API 34 และ ข้างต้นและ FOREGROUND_SERVICE_MEDIA_PLAYBACK:

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

นอกจากนี้ คุณต้องประกาศคลาส Service ในไฟล์ Manifest ด้วยตัวกรอง Intent ของ MediaSessionService

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

คุณต้องกำหนด foregroundServiceType ที่มี mediaPlayback เมื่อแอปทำงานบนอุปกรณ์ที่ใช้ Android 10 (API ระดับ 29) ขึ้นไป

ควบคุมการเล่นโดยใช้ MediaController

ในกิจกรรมหรือส่วนที่ประกอบด้วย UI ของโปรแกรมเล่น คุณสามารถลิงก์ระหว่าง UI กับเซสชันสื่อได้โดยใช้ MediaController UI ของคุณใช้ ตัวควบคุมสื่อเพื่อส่งคำสั่งจาก UI ของคุณไปยังโปรแกรมเล่นภายใน เซสชัน โปรดดู สร้าง MediaController สำหรับรายละเอียดเกี่ยวกับการสร้างและใช้MediaController

จัดการคําสั่ง UI

MediaSession รับคำสั่งจากตัวควบคุมผ่าน MediaSession.Callback การกำหนดค่าเริ่มต้นของ MediaSession จะสร้างการใช้งาน MediaSession.Callback เริ่มต้นที่จะจัดการคําสั่งทั้งหมดที่ MediaController ส่งไปยังโปรแกรมเล่นโดยอัตโนมัติ

การแจ้งเตือน

MediaSessionService จะสร้าง MediaNotification ให้คุณโดยอัตโนมัติ ซึ่งในกรณีส่วนใหญ่จะใช้งานได้ โดยค่าเริ่มต้น การแจ้งเตือนที่เผยแพร่จะเป็น การแจ้งเตือน MediaStyle ที่อัปเดตอยู่เสมอด้วยข้อมูลล่าสุด จากเซสชันสื่อและแสดงตัวควบคุมการเล่น MediaNotification รับรู้ถึงเซสชันของคุณ และสามารถใช้เพื่อควบคุมการเล่นสำหรับแอปอื่นๆ ได้ ที่เชื่อมต่อกับเซสชันเดียวกัน

ตัวอย่างเช่น แอปสตรีมมิงเพลงที่ใช้ MediaSessionService จะสร้าง MediaNotification ที่แสดงชื่อ ศิลปิน และปกอัลบั้มสำหรับ รายการสื่อปัจจุบันที่กำลังเล่นควบคู่กับส่วนควบคุมการเล่นโดยอิงตาม การกำหนดค่า MediaSession

คุณส่งข้อมูลเมตาที่จำเป็นในสื่อหรือประกาศให้เป็นส่วนหนึ่งของ รายการสื่อดังในข้อมูลโค้ดต่อไปนี้

Kotlin

val mediaItem =
    MediaItem.Builder()
      .setMediaId("media-1")
      .setUri(mediaUri)
      .setMediaMetadata(
        MediaMetadata.Builder()
          .setArtist("David Bowie")
          .setTitle("Heroes")
          .setArtworkUri(artworkUri)
          .build()
      )
      .build()

mediaController.setMediaItem(mediaItem)
mediaController.prepare()
mediaController.play()

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setMediaId("media-1")
        .setUri(mediaUri)
        .setMediaMetadata(
            new MediaMetadata.Builder()
                .setArtist("David Bowie")
                .setTitle("Heroes")
                .setArtworkUri(artworkUri)
                .build())
        .build();

mediaController.setMediaItem(mediaItem);
mediaController.prepare();
mediaController.play();

แอปสามารถปรับแต่งปุ่มคำสั่งของการควบคุม Android Media ได้ อ่านเพิ่มเติมเกี่ยวกับการปรับแต่งการควบคุมสื่อของ Android

การปรับแต่งการแจ้งเตือน

หากต้องการปรับแต่งการแจ้งเตือน ให้สร้าง MediaNotification.Provider ด้วย DefaultMediaNotificationProvider.Builder หรือสร้างการใช้งานอินเทอร์เฟซผู้ให้บริการที่กําหนดเอง เพิ่ม เป็นผู้ให้บริการ MediaSessionService ของคุณกับ setMediaNotificationProvider

การกลับมาเล่นอีกครั้ง

ปุ่มสื่อเป็นปุ่มฮาร์ดแวร์ที่พบในอุปกรณ์ Android และอุปกรณ์ต่อพ่วงอื่นๆ เช่น ปุ่มเล่นหรือหยุดชั่วคราวบนชุดหูฟังบลูทูธ Media3 จัดการอินพุตปุ่มสื่อให้คุณเมื่อบริการทำงานอยู่

ประกาศตัวรับปุ่มสื่อ Media3

Media3 มี API เพื่อให้ผู้ใช้กลับมาทำงานอีกครั้ง การเล่นหลังจากแอปสิ้นสุดลง และแม้ว่า รีสตาร์ทแล้ว การกลับมาเล่นต่อจะปิดอยู่โดยค่าเริ่มต้น ซึ่งหมายความว่าผู้ใช้ ไม่สามารถเล่นต่อได้เมื่อบริการของคุณไม่ทำงาน หากต้องการเลือกใช้ ให้เริ่มโดย โดยประกาศ MediaButtonReceiver ในไฟล์ Manifest

<receiver android:name="androidx.media3.session.MediaButtonReceiver"
  android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
  </intent-filter>
</receiver>

ใช้ Callback ของการกลับมาเล่นอีกครั้ง

เมื่ออุปกรณ์บลูทูธหรือฟีเจอร์การกลับมาเล่นต่อของ UI ระบบ Android ขอให้เล่นต่อ ระบบจะเรียกใช้เมธอดการเรียกกลับ onPlaybackResumption()

Kotlin

override fun onPlaybackResumption(
    mediaSession: MediaSession,
    controller: ControllerInfo
): ListenableFuture<MediaItemsWithStartPosition> {
  val settable = SettableFuture.create<MediaItemsWithStartPosition>()
  scope.launch {
    // Your app is responsible for storing the playlist and the start position
    // to use here
    val resumptionPlaylist = restorePlaylist()
    settable.set(resumptionPlaylist)
  }
  return settable
}

Java

@Override
public ListenableFuture<MediaItemsWithStartPosition> onPlaybackResumption(
    MediaSession mediaSession,
    ControllerInfo controller
) {
  SettableFuture<MediaItemsWithStartPosition> settableFuture = SettableFuture.create();
  settableFuture.addListener(() -> {
    // Your app is responsible for storing the playlist and the start position
    // to use here
    MediaItemsWithStartPosition resumptionPlaylist = restorePlaylist();
    settableFuture.set(resumptionPlaylist);
  }, MoreExecutors.directExecutor());
  return settableFuture;
}

หากคุณจัดเก็บพารามิเตอร์อื่นๆ เช่น ความเร็วในการเล่น โหมดเล่นซ้ำ หรือโหมดสุ่ม onPlaybackResumption() จะเป็นตําแหน่งที่ดีในการกําหนดค่าโปรแกรมเล่นด้วยพารามิเตอร์เหล่านี้ก่อนที่ Media3 จะเตรียมโปรแกรมเล่นและเริ่มเล่นเมื่อการเรียกกลับเสร็จสมบูรณ์

การกำหนดค่าตัวควบคุมขั้นสูงและการทำงานร่วมกันแบบย้อนหลัง

สถานการณ์ทั่วไปคือการใช้ MediaController ใน UI ของแอปเพื่อควบคุม เล่นและแสดงเพลย์ลิสต์ ในขณะเดียวกัน เซสชันจะแสดงต่อไคลเอ็นต์ภายนอก เช่น การควบคุมสื่อของ Android และ Assistant บนอุปกรณ์เคลื่อนที่หรือทีวี, Wear OS สำหรับนาฬิกา และ Android Auto ในรถยนต์ แอปเดโมเซสชันของ Media3 เป็นตัวอย่างของแอปที่ใช้สถานการณ์ดังกล่าว

ไคลเอ็นต์ภายนอกเหล่านี้อาจใช้ API เช่น MediaControllerCompat ของไลบรารี AndroidX รุ่นเดิมหรือ android.media.session.MediaController ของเฟรมเวิร์ก Android Media3 สามารถเข้ากันได้กับไลบรารีเดิมโดยสมบูรณ์และ จะทำงานร่วมกับ API เฟรมเวิร์ก Android

ใช้ตัวควบคุมการแจ้งเตือนสื่อ

สิ่งสำคัญคือต้องเข้าใจว่าเครื่องมือควบคุมแบบเดิมหรือเฟรมเวิร์กเหล่านี้อ่าน ค่าเดียวกันจากเฟรมเวิร์ก PlaybackState.getActions() และ PlaybackState.getCustomActions() ถ้าต้องการระบุการกระทำและการกระทำที่กำหนดเองของ เซสชันเฟรมเวิร์ก แอปจะใช้ตัวควบคุมการแจ้งเตือนสื่อได้ และตั้งค่าคำสั่งที่ใช้ได้และเลย์เอาต์ที่กำหนดเอง บริการจะเชื่อมต่อตัวควบคุมการแจ้งเตือนสื่อกับเซสชันของคุณ และเซสชันจะใช้ ConnectionResult ที่ onConnect() ของคอลแบ็กแสดงผลเพื่อกําหนดค่าการดําเนินการและการดําเนินการที่กำหนดเองของเซสชันเฟรมเวิร์ก

สำหรับสถานการณ์บนอุปกรณ์เคลื่อนที่เท่านั้น แอปสามารถให้บริการ MediaSession.Callback.onConnect() เพื่อตั้งค่าคำสั่งที่ใช้ได้และ เลย์เอาต์ที่กำหนดเองสำหรับเซสชันเฟรมเวิร์กโดยเฉพาะ ดังนี้

Kotlin

override fun onConnect(
  session: MediaSession,
  controller: MediaSession.ControllerInfo
): ConnectionResult {
  if (session.isMediaNotificationController(controller)) {
    val sessionCommands =
      ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
        .add(customCommandSeekBackward)
        .add(customCommandSeekForward)
        .build()
    val playerCommands =
      ConnectionResult.DEFAULT_PLAYER_COMMANDS.buildUpon()
        .remove(COMMAND_SEEK_TO_PREVIOUS)
        .remove(COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
        .remove(COMMAND_SEEK_TO_NEXT)
        .remove(COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
        .build()
    // Custom layout and available commands to configure the legacy/framework session.
    return AcceptedResultBuilder(session)
      .setCustomLayout(
        ImmutableList.of(
          createSeekBackwardButton(customCommandSeekBackward),
          createSeekForwardButton(customCommandSeekForward))
      )
      .setAvailablePlayerCommands(playerCommands)
      .setAvailableSessionCommands(sessionCommands)
      .build()
  }
  // Default commands with default custom layout for all other controllers.
  return AcceptedResultBuilder(session).build()
}

Java

@Override
public ConnectionResult onConnect(
    MediaSession session, MediaSession.ControllerInfo controller) {
  if (session.isMediaNotificationController(controller)) {
    SessionCommands sessionCommands =
        ConnectionResult.DEFAULT_SESSION_COMMANDS
            .buildUpon()
            .add(customCommandSeekBackward)
            .add(customCommandSeekForward)
            .build();
    Player.Commands playerCommands =
        ConnectionResult.DEFAULT_PLAYER_COMMANDS
            .buildUpon()
            .remove(COMMAND_SEEK_TO_PREVIOUS)
            .remove(COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
            .remove(COMMAND_SEEK_TO_NEXT)
            .remove(COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
            .build();
    // Custom layout and available commands to configure the legacy/framework session.
    return new AcceptedResultBuilder(session)
        .setCustomLayout(
            ImmutableList.of(
                createSeekBackwardButton(customCommandSeekBackward),
                createSeekForwardButton(customCommandSeekForward)))
        .setAvailablePlayerCommands(playerCommands)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
  // Default commands without default custom layout for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

ให้สิทธิ์ Android Auto ส่งคําสั่งที่กําหนดเอง

เมื่อใช้ MediaLibraryService และเพื่อรองรับ Android Auto ด้วยแอปบนอุปกรณ์เคลื่อนที่ ตัวควบคุม Android Auto ต้องใช้คำสั่งที่เหมาะสม มิเช่นนั้น Media3 จะปฏิเสธคำสั่งที่กำหนดเองขาเข้าจากตัวควบคุมนั้น

Kotlin

override fun onConnect(
  session: MediaSession,
  controller: MediaSession.ControllerInfo
): ConnectionResult {
  val sessionCommands =
    ConnectionResult.DEFAULT_SESSION_AND_LIBRARY_COMMANDS.buildUpon()
      .add(customCommandSeekBackward)
      .add(customCommandSeekForward)
      .build()
  if (session.isMediaNotificationController(controller)) {
    // [...] See above.
  } else if (session.isAutoCompanionController(controller)) {
    // Available session commands to accept incoming custom commands from Auto.
    return AcceptedResultBuilder(session)
      .setAvailableSessionCommands(sessionCommands)
      .build()
  }
  // Default commands with default custom layout for all other controllers.
  return AcceptedResultBuilder(session).build()
}

Java

@Override
public ConnectionResult onConnect(
    MediaSession session, MediaSession.ControllerInfo controller) {
  SessionCommands sessionCommands =
      ConnectionResult.DEFAULT_SESSION_COMMANDS
          .buildUpon()
          .add(customCommandSeekBackward)
          .add(customCommandSeekForward)
          .build();
  if (session.isMediaNotificationController(controller)) {
    // [...] See above.
  } else if (session.isAutoCompanionController(controller)) {
    // Available commands to accept incoming custom commands from Auto.
    return new AcceptedResultBuilder(session)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
  // Default commands without default custom layout for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

แอปสาธิตเซสชันมีโมดูลยานยนต์ซึ่งแสดงการรองรับ Automotive OS ที่ต้องแยก APK ต่างหาก