Pemutaran di latar belakang dengan MediaSessionService

Sering kali diinginkan untuk memutar media saat aplikasi tidak berada di latar depan. Misalnya, pemutar musik umumnya terus memutar musik saat pengguna mengunci perangkat atau menggunakan aplikasi lain. Library Media3 menyediakan serangkaian antarmuka yang memungkinkan Anda mendukung pemutaran di latar belakang.

Catatan: Petunjuk berikut untuk MediaSessionService juga berlaku untuk MediaLibraryService.

Menggunakan MediaSessionService

Untuk mengaktifkan pemutaran di latar belakang, Anda harus memuat Player dan MediaSession di dalam Layanan terpisah. Hal ini memungkinkan perangkat untuk terus menyajikan media meskipun aplikasi tidak berada di latar depan.

Gambar 1: MediaSessionService memungkinkan sesi media berjalan secara terpisah dari aktivitas aplikasi

Saat menghosting pemain di dalam Service, Anda harus menggunakan MediaSessionService. Untuk melakukannya, buat class yang memperluas MediaSessionService dan buat sesi media di dalamnya.

Penggunaan MediaSessionService memungkinkan klien eksternal seperti Asisten Google, kontrol media sistem, atau perangkat pendamping seperti Wear OS menemukan layanan Anda, terhubung ke layanan tersebut, dan mengontrol pemutaran, semuanya tanpa mengakses aktivitas UI aplikasi Anda sama sekali. Bahkan, beberapa aplikasi klien dapat terhubung ke MediaSessionService yang sama secara bersamaan, dengan setiap aplikasi menggunakan MediaController-nya sendiri.

Mengimplementasikan siklus proses layanan

Anda perlu menerapkan tiga metode siklus proses layanan Anda:

• onCreate() dipanggil saat pengontrol pertama akan terhubung dan layanan dibuat instance-nya dan dimulai. Ini adalah tempat terbaik untuk mem-build Player dan MediaSession.
• onTaskRemoved(Intent) dipanggil saat pengguna menutup aplikasi dari tugas terbaru. Jika pemutaran sedang berlangsung, aplikasi dapat memilih untuk terus menjalankan layanan di latar depan. Jika pemutar dijeda, layanan tidak berada di latar depan dan perlu dihentikan.
• onDestroy() dipanggil saat layanan dihentikan. Semua resource termasuk pemutar dan sesi harus dirilis.

Catatan: Aplikasi dapat menerapkan kelanjutan pemutaran untuk memungkinkan pengguna memulai ulang siklus proses layanan dan melanjutkan pemutaran dari tempat terakhir diputar.

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();
  }
}

Sebagai alternatif untuk terus melanjutkan pemutaran di latar belakang, aplikasi dapat menghentikan layanan dalam kasus apa pun saat pengguna menutup aplikasi:

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();
}

Memberikan akses ke sesi media

Ganti metode onGetSession() untuk memberi klien lain akses ke sesi media Anda yang dibuat saat layanan dibuat.

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;
  }
}

Mendeklarasikan layanan dalam manifes

Aplikasi memerlukan izin untuk menjalankan layanan latar depan. Tambahkan izin FOREGROUND_SERVICE ke manifes, dan jika Anda menargetkan API 34 dan di atas, tambahkan juga FOREGROUND_SERVICE_MEDIA_PLAYBACK:

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

Anda juga harus mendeklarasikan class Service dalam manifes dengan filter intent MediaSessionService.

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

Anda harus menentukan foregroundServiceType yang menyertakan mediaPlayback saat aplikasi berjalan di perangkat dengan Android 10 (API level 29) dan yang lebih tinggi.

Catatan: Jika Anda ingin MediaLibraryService kompatibel dengan versi sebelumnya dengan aplikasi klien yang menggunakan MediaBrowserService lama, Anda harus menyertakan <action android:name="android.media.browse.MediaBrowserService"/> di elemen intent-filter yang diberikan di atas.

Mengontrol pemutaran menggunakan MediaController

Di Aktivitas atau Fragmen yang berisi UI pemutar, Anda dapat membuat link antara UI dan sesi media menggunakan MediaController. UI Anda menggunakan pengontrol media untuk mengirim perintah dari UI ke pemutar dalam sesi. Lihat panduan Membuat MediaController untuk mengetahui detail tentang cara membuat dan menggunakan MediaController.

Menangani perintah UI

MediaSession menerima perintah dari pengontrol melalui MediaSession.Callback-nya. Memulai MediaSession akan membuat implementasi default MediaSession.Callback yang secara otomatis menangani semua perintah yang dikirim MediaController ke pemutar Anda.

Catatan: MediaSession.ControllerInfo diteruskan sebagai argumen ke fungsi dalam antarmuka MediaSession.Callback. Hal ini memungkinkan Anda melihat paket pemanggil dengan controllerInfo.packageName dan menyesuaikan reaksi aplikasi Anda dengan tepat. Misalnya, Anda mungkin ingin menangani perintah secara berbeda jika berasal dari Android Auto atau headset Bluetooth (com.android.bluetooth).

Notifikasi

MediaSessionService akan otomatis membuat MediaNotification untuk Anda yang seharusnya berfungsi dalam sebagian besar kasus. Secara default, notifikasi yang dipublikasikan adalah notifikasi MediaStyle yang terus mengikuti informasi terbaru dari sesi media Anda dan menampilkan kontrol pemutaran. MediaNotification mengetahui sesi Anda dan dapat digunakan untuk mengontrol pemutaran untuk aplikasi lain yang terhubung ke sesi yang sama.

Misalnya, aplikasi streaming musik yang menggunakan MediaSessionService akan membuat MediaNotification yang menampilkan judul, artis, dan karya seni album untuk item media saat ini yang diputar bersama kontrol pemutaran berdasarkan konfigurasi MediaSession Anda.

Metadata yang diperlukan dapat diberikan dalam media atau dideklarasikan sebagai bagian dari item media seperti dalam cuplikan berikut:

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();

Aplikasi dapat menyesuaikan tombol perintah kontrol Media Android. Baca selengkapnya tentang menyesuaikan kontrol Media Android.

Penyesuaian notifikasi

Untuk menyesuaikan notifikasi, buat MediaNotification.Provider dengan DefaultMediaNotificationProvider.Builder atau dengan membuat implementasi kustom antarmuka penyedia. Tambahkan penyedia Anda ke MediaSessionService dengan setMediaNotificationProvider.

Catatan: Mulai API 33, notifikasi UI Sistem diisi dari data dalam sesi. Oleh karena itu, penyesuaian MediaNotification.Provider hanya berlaku sebelum API 33.

Melanjutkan pemutaran

Tombol media adalah tombol hardware yang ditemukan di perangkat Android dan perangkat periferal lainnya, seperti tombol putar atau jeda pada headset Bluetooth. Media3 menangani input tombol media untuk Anda saat layanan berjalan.

Mendeklarasikan penerima tombol media Media3

Media3 menyertakan API untuk memungkinkan pengguna melanjutkan pemutaran setelah aplikasi dihentikan dan bahkan setelah perangkat dimulai ulang. Secara default, melanjutkan pemutaran dinonaktifkan. Artinya, pengguna tidak dapat melanjutkan pemutaran saat layanan Anda tidak berjalan. Untuk ikut serta, mulai dengan mendeklarasikan MediaButtonReceiver dalam manifes Anda:

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

Penting: Jika menambahkan MediaButtonReceiver, Anda harus mengimplementasikan MediaSession.Callback.onPlaybackresumption() sebagai langkah kedua.

Menerapkan callback kelanjutan pemutaran

Saat melanjutkan pemutaran diminta oleh perangkat Bluetooth atau fitur melanjutkan UI Sistem Android, metode callback onPlaybackResumption() akan dipanggil.

Catatan: Notifikasi kelanjutan UI Sistem Android hanya tersedia jika Anda menerapkan MediaLibraryService.

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;
}

Penting: Anda harus berusaha menyelesaikan ListenableFuture secepat mungkin agar latensi startup tetap rendah.

Jika Anda telah menyimpan parameter lain seperti kecepatan pemutaran, mode pengulangan, atau mode acak, onPlaybackResumption() adalah tempat yang tepat untuk mengonfigurasi pemutar dengan parameter ini sebelum Media3 menyiapkan pemutar dan memulai pemutaran saat callback selesai.

Konfigurasi pengontrol lanjutan dan kompatibilitas mundur

Skenario yang umum adalah menggunakan MediaController di UI aplikasi untuk mengontrol pemutaran dan menampilkan playlist. Pada saat yang sama, sesi diekspos ke klien eksternal seperti kontrol media Android dan Asisten di perangkat seluler atau TV, Wear OS untuk smartwatch, dan Android Auto di mobil. Aplikasi demo sesi Media3 adalah contoh aplikasi yang menerapkan skenario tersebut.

Klien eksternal ini dapat menggunakan API seperti MediaControllerCompat dari library AndroidX lama atau android.media.session.MediaController dari framework Android. Media3 sepenuhnya kompatibel dengan library lama dan menyediakan interoperabilitas dengan API framework Android.

Menggunakan pengontrol notifikasi media

Penting untuk dipahami bahwa pengontrol lama atau framework ini membaca nilai yang sama dari PlaybackState.getActions() dan PlaybackState.getCustomActions() framework. Untuk menentukan tindakan dan tindakan kustom sesi framework, aplikasi dapat menggunakan pengontrol notifikasi media serta menetapkan perintah dan tata letak kustom yang tersedia. Layanan ini menghubungkan pengontrol notifikasi media ke sesi Anda, dan sesi menggunakan ConnectionResult yang ditampilkan oleh onConnect() callback Anda untuk mengonfigurasi tindakan dan tindakan kustom sesi framework.

Dengan skenario khusus seluler, aplikasi dapat menyediakan implementasi MediaSession.Callback.onConnect() untuk menetapkan perintah yang tersedia dan tata letak kustom khusus untuk sesi framework sebagai berikut:

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();
}

Perhatian: Menolak upaya pengontrol notifikasi media untuk terhubung, akan menyebabkan aplikasi Anda tidak berfungsi dengan benar.

Memberi otorisasi Android Auto untuk mengirim perintah kustom

Saat menggunakan MediaLibraryService dan untuk mendukung Android Auto dengan aplikasi seluler, pengontrol Android Auto memerlukan perintah yang tersedia dan sesuai. Jika tidak, Media3 akan menolak perintah kustom yang masuk dari pengontrol tersebut:

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();
}

Aplikasi demo sesi memiliki modul otomotif, yang menunjukkan dukungan untuk Automotive OS yang memerlukan APK terpisah.