Pemutaran di latar belakang dengan MediaSessionService

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sering kali Anda ingin 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.

Menggunakan MediaSessionService

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

Saat menghosting pemain di dalam Layanan, 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, tombol media di perangkat periferal, atau perangkat pendamping seperti Wear OS untuk 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 dua metode siklus proses layanan:

• onCreate() dipanggil saat pengontrol pertama akan terhubung dan layanan dibuat instance-nya dan dimulai. Ini adalah tempat terbaik untuk mem-build Player dan MediaSession.
• onDestroy() dipanggil saat layanan dihentikan. Semua resource termasuk pemutar dan sesi harus dirilis.

Secara opsional, Anda dapat mengganti onTaskRemoved(Intent) untuk menyesuaikan hal yang terjadi saat pengguna menutup aplikasi dari tugas terbaru. Secara default, layanan akan tetap berjalan jika pemutaran sedang berlangsung dan akan dihentikan jika tidak.

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

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

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

  // 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, Anda dapat menghentikan layanan kapan saja saat pengguna menutup aplikasi:

override fun onTaskRemoved(rootIntent: Intent?) {
  pauseAllPlayersAndStopSelf()
}

@Override
public void onTaskRemoved(@Nullable Intent rootIntent) {
  pauseAllPlayersAndStopSelf();
}

Untuk penerapan manual onTaskRemoved lainnya, Anda dapat menggunakan isPlaybackOngoing() untuk memeriksa apakah pemutaran dianggap sedang berlangsung dan layanan latar depan dimulai.

Memberikan akses ke sesi media

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

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

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

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 FOREGROUND_SERVICE dan FOREGROUND_SERVICE_MEDIA_PLAYBACK untuk menjalankan layanan latar depan pemutaran:

<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 dan foregroundServiceType yang menyertakan mediaPlayback.

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

Mengontrol pemutaran menggunakan MediaController

Dalam 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 MediaController

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

Notifikasi

MediaSessionService akan otomatis membuat MediaNotification untuk Anda yang akan berfungsi dalam sebagian besar kasus. Secara default, notifikasi yang dipublikasikan adalah notifikasi MediaStyle yang terus diperbarui dengan 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:

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

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

Siklus proses notifikasi

Notifikasi dibuat segera setelah Player memiliki instance MediaItem dalam playlist-nya.

Semua pembaruan notifikasi terjadi secara otomatis berdasarkan status Player dan MediaSession.

Notifikasi tidak dapat dihapus saat layanan latar depan sedang berjalan. Untuk segera menghapus notifikasi, Anda harus memanggil Player.release() atau menghapus playlist menggunakan Player.clearMediaItems().

Jika pemutar dijeda, dihentikan, atau gagal selama lebih dari 10 menit tanpa interaksi pengguna lebih lanjut, layanan akan otomatis ditransisikan dari status layanan latar depan sehingga dapat dihancurkan oleh sistem. Anda dapat menerapkan kelanjutan pemutaran untuk memungkinkan pengguna memulai ulang siklus proses layanan dan melanjutkan pemutaran di lain waktu.

Penyesuaian notifikasi

Metadata tentang item yang sedang diputar dapat disesuaikan dengan mengubah MediaItem.MediaMetadata. Jika ingin memperbarui metadata item yang ada, Anda dapat menggunakan Player.replaceMediaItem untuk memperbarui metadata tanpa mengganggu pemutaran.

Anda juga dapat menyesuaikan beberapa tombol yang ditampilkan dalam notifikasi dengan menetapkan preferensi tombol media kustom untuk kontrol Media Android. Baca selengkapnya tentang cara menyesuaikan kontrol Media Android.

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

Melanjutkan pemutaran

Setelah MediaSessionService dihentikan, dan bahkan setelah perangkat di-reboot, Anda dapat menawarkan kelanjutan pemutaran agar pengguna dapat memulai ulang layanan dan melanjutkan pemutaran dari tempat terakhir yang ditinggalkan. Secara default, kelanjutan pemutaran dinonaktifkan. Artinya, pengguna tidak dapat melanjutkan pemutaran saat layanan Anda tidak berjalan. Untuk mengaktifkan fitur ini, Anda perlu mendeklarasikan penerima tombol media dan menerapkan metode onPlaybackResumption.

Mendeklarasikan penerima tombol media Media3

Mulailah 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>

Menerapkan callback kelanjutan pemutaran

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

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
}

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

Jika Anda telah menyimpan parameter lain seperti kecepatan pemutaran, mode ulang, 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 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 platform Android. Media3 sepenuhnya kompatibel dengan library lama dan menyediakan interoperabilitas dengan API platform Android.

Menggunakan pengontrol notifikasi media

Penting untuk memahami bahwa pengontrol lama dan platform ini memiliki status dan visibilitas yang sama dan tidak dapat disesuaikan oleh pengontrol (misalnya PlaybackState.getActions() dan PlaybackState.getCustomActions() yang tersedia). Anda dapat menggunakan pengontrol notifikasi media untuk mengonfigurasi status yang ditetapkan dalam sesi media platform untuk kompatibilitas dengan pengontrol lama dan platform ini.

Misalnya, aplikasi dapat menyediakan implementasi MediaSession.Callback.onConnect() untuk menetapkan perintah yang tersedia dan preferensi tombol media secara khusus untuk sesi platform sebagai berikut:

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 button preferences and commands to configure the platform session.
    return AcceptedResultBuilder(session)
      .setMediaButtonPreferences(
        ImmutableList.of(
          createSeekBackwardButton(customCommandSeekBackward),
          createSeekForwardButton(customCommandSeekForward))
      )
      .setAvailablePlayerCommands(playerCommands)
      .setAvailableSessionCommands(sessionCommands)
      .build()
  }
  // Default commands with default button preferences for all other controllers.
  return AcceptedResultBuilder(session).build()
}

@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 button preferences and commands to configure the platform session.
    return new AcceptedResultBuilder(session)
        .setMediaButtonPreferences(
            ImmutableList.of(
                createSeekBackwardButton(customCommandSeekBackward),
                createSeekForwardButton(customCommandSeekForward)))
        .setAvailablePlayerCommands(playerCommands)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
  // Default commands with default button preferences for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

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:

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 for all other controllers.
  return AcceptedResultBuilder(session).build()
}

@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 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.