Media3 ExoPlayer kullanarak temel bir medya oynatıcı uygulaması oluşturma

Jetpack Media3, video ve ses dosyalarının oynatılması için temel işlevleri özetleyen bir Player arayüzü tanımlar. ExoPlayer, Media3'teki bu arayüzün varsayılan uygulamasıdır. Çoğu oynatma kullanım alanını kapsayan kapsamlı bir özellik seti sunduğu ve sahip olabileceğiniz ek kullanım alanlarını işlemek için özelleştirilebildiği için ExoPlayer'ı kullanmanızı öneririz. ExoPlayer ayrıca cihaz ve işletim sistemi parçalanmasını soyutlayarak kodunuzun tüm Android ekosisteminde tutarlı bir şekilde çalışmasını sağlar. ExoPlayer'da şunlar bulunur:

Bu sayfada, oynatma uygulaması oluşturmayla ilgili bazı önemli adımlar açıklanmaktadır. Daha fazla bilgi için Media3 ExoPlayer ile ilgili tam kılavuzlarımıza göz atabilirsiniz.

Başlarken

Başlamak için Jetpack Media3'ün ExoPlayer, UI ve Common modüllerine bağımlılık ekleyin:

implementation "androidx.media3:media3-exoplayer:1.8.0"
implementation "androidx.media3:media3-ui:1.8.0"
implementation "androidx.media3:media3-common:1.8.0"

Kullanım alanınıza bağlı olarak, DASH biçimindeki akışları oynatmak için Media3'ten exoplayer-dash gibi ek modüller de gerekebilir.

1.8.0 yerine tercih ettiğiniz kitaplık sürümünü kullandığınızdan emin olun. En son sürümü görmek için sürüm notlarına bakabilirsiniz.

Medya oynatıcı oluşturma

Media3 ile Player arayüzünün ExoPlayer dahil edilmiş uygulamasını kullanabilir veya kendi özel uygulamanızı oluşturabilirsiniz.

ExoPlayer oluşturma

ExoPlayer örneği oluşturmanın en basit yolu şöyledir:

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

Medya oynatıcınızı, bulunduğu Activity, Fragment veya Service'nin onCreate() yaşam döngüsü yönteminde oluşturabilirsiniz.

Builder, aşağıdakiler gibi ilginizi çekebilecek çeşitli özelleştirme seçenekleri içerir:

Media3, uygulamanızın düzen dosyasına ekleyebileceğiniz bir PlayerView kullanıcı arayüzü bileşeni sağlar. Bu bileşen, oynatma kontrolleri için PlayerControlView, altyazıları göstermek için SubtitleView ve videoyu oluşturmak için Surface öğesini kapsar.

Oynatıcıyı hazırlama

setMediaItem() ve addMediaItem() gibi yöntemlerle oynatmak için oynatma listesine medya öğeleri ekleyin. Ardından, medya yüklemeye başlamak ve gerekli kaynakları edinmek için prepare() numarasını arayın.

Bu adımları, uygulama ön plana gelmeden önce gerçekleştirmemelisiniz. Oynatıcınız Activity veya Fragment durumundaysa bu, oynatıcıyı API düzeyi 24 ve üzeri sürümlerde onStart() yaşam döngüsü yönteminde, API düzeyi 23 ve önceki sürümlerde ise onResume() yaşam döngüsü yönteminde hazırlamak anlamına gelir. Service içinde olan bir oyuncu için onCreate() içinde hazırlayabilirsiniz. Yaşam döngüsü yöntemlerinin nasıl uygulanacağına dair bir örnek için Exoplayer codelab'ini inceleyin.

Oynatıcıyı kontrol etme

Oynatıcı hazırlandıktan sonra, oynatıcıda aşağıdaki gibi yöntemleri çağırarak oynatmayı kontrol edebilirsiniz:

PlayerView veya PlayerControlView gibi kullanıcı arayüzü bileşenleri, bir oynatıcıya bağlandığında buna göre güncellenir.

Oyuncuyu serbest bırakma

Oynatma, video kod çözücüler gibi sınırlı sayıda bulunan kaynaklar gerektirebilir. Bu nedenle, oynatıcıya artık ihtiyaç duyulmadığında kaynakları serbest bırakmak için oynatıcınızda release() işlevini çağırmanız önemlidir.

Oynatıcınız Activity veya Fragment durumundaysa oynatıcıyı API düzeyi 24 ve üzeri sürümlerde onStop() yaşam döngüsü yönteminde, API düzeyi 23 ve önceki sürümlerde ise onPause() yönteminde yayınlayın. Service içinde bulunan bir oyuncuyu onDestroy() içinde serbest bırakabilirsiniz. Yaşam döngüsü yöntemlerinin nasıl uygulanacağına dair bir örnek için Exoplayer codelab'ini inceleyin.

Medya oturumuyla oynatmayı yönetme

Android'de medya oturumları, süreç sınırları içinde bir medya oynatıcıyla etkileşim kurmak için standartlaştırılmış bir yol sağlar. Bir medya oturumunu oynatıcınıza bağlamak, medya oynatımınızın harici olarak reklamını yapmanıza ve harici kaynaklardan oynatma komutları almanıza olanak tanır. Örneğin, mobil ve büyük ekranlı cihazlarda sistem medya kontrolleriyle entegrasyon için.

Medya oturumlarını kullanmak için Media3 Session modülüne bağımlılık ekleyin:

implementation "androidx.media3:media3-session:1.8.0"

Medya oturumu oluşturma

Bir oynatıcıyı aşağıdaki şekilde başlatarak MediaSession oluşturabilirsiniz:

Kotlin

val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();

Media3, Player durumunu MediaSession durumuyla otomatik olarak senkronize eder. Bu özellik, ExoPlayer, CastPlayer veya özel uygulama dahil olmak üzere tüm Player uygulamalarıyla çalışır.

Diğer istemcilere kontrol izni verme

İstemci uygulamaları, medya oturumunuzun oynatılmasını kontrol etmek için medya denetleyicisi uygulayabilir. Bu istekleri almak için MediaSession oluştururken bir geri çağırma nesnesi ayarlayın.

Bir kumanda medya oturumunuza bağlanmak üzereyken onConnect() yöntemi çağrılır. İsteği kabul edeceğinize veya reddedeceğinize karar vermek için sağlanan ControllerInfo bilgileri kullanabilirsiniz. Bunun bir örneğini Media3 Session demo uygulamasında görebilirsiniz.

Bağlandıktan sonra denetleyici, oturuma oynatma komutları gönderebilir. Oturum daha sonra bu komutları oynatıcıya devreder. Player arayüzünde tanımlanan oynatma ve oynatma listesi komutları, oturum tarafından otomatik olarak işlenir.

Diğer geri çağırma yöntemleri, örneğin özel oynatma komutları ve oynatma listesini değiştirme isteklerini işlemenize olanak tanır. Bu geri çağırmalar da benzer şekilde bir ControllerInfo nesnesi içerir. Böylece, erişim denetimini istek bazında belirleyebilirsiniz.

Medya içeriklerini arka planda oynatma

Uygulamanız ön planda değilken medyayı oynatmaya devam etmek için (ör. kullanıcı uygulamanızı açık tutmasa bile müzik, sesli kitap veya podcast oynatmak için) Player ve MediaSession, ön plan hizmeti içinde kapsüllenmelidir. Media3, bu amaçla MediaSessionService arayüzünü sağlar.

MediaSessionService uygulama

MediaSessionService sınıfını genişleten bir sınıf oluşturun ve onCreate() yaşam döngüsü yönteminde MediaSession öğenizi oluşturun.

Kotlin

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

    // Create your Player and MediaSession 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()
    }
}

Java

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

    @Override
    public void onCreate() {
        super.onCreate();
        ExoPlayer player = new ExoPlayer.Builder(this).build();
        mediaSession = new MediaSession.Builder(this, player).build();
    }

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

Manifest dosyanızda, Service sınıfınızı MediaSessionService intent filtresiyle ekleyin ve ön plan hizmeti çalıştırmak için FOREGROUND_SERVICE iznini isteyin:

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

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

Son olarak, oluşturduğunuz sınıfta onGetSession() yöntemini geçersiz kılarak medya oturumunuza istemci erişimini kontrol edin. Bağlantı isteğini kabul etmek için MediaSession, isteği reddetmek için null döndürün.

Kotlin

// This example always accepts the connection request
override fun onGetSession(
    controllerInfo: MediaSession.ControllerInfo
): MediaSession? = mediaSession

Java

@Override
public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
  // This example always accepts the connection request
  return mediaSession;
}

Kullanıcı arayüzünüze bağlanma

Medya oturumunuz artık oynatıcı kullanıcı arayüzünüzün bulunduğu Activity veya Fragment'dan Service ayrı olduğu için bunları birbirine bağlamak için MediaController kullanabilirsiniz. onStart() yöntemiyle Activity veya Fragment ile SessionToken oluşturun. Ardından, SessionToken'ı kullanarak MediaController oluşturun.MediaSession MediaController oluşturma işlemi eşzamansız olarak gerçekleşir.

Kotlin

override fun onStart() {
  val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java))
  val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync()
  controllerFuture.addListener(
    {
        // Call controllerFuture.get() to retrieve the MediaController.
        // MediaController implements the Player interface, so it can be
        // attached to the PlayerView UI component.
        playerView.setPlayer(controllerFuture.get())
      },
    MoreExecutors.directExecutor()
  )
}

Java

@Override
public void onStart() {
  SessionToken sessionToken =
    new SessionToken(this, new ComponentName(this, PlaybackService.class));
  ListenableFuture<MediaController> controllerFuture =
    new MediaController.Builder(this, sessionToken).buildAsync();
  controllerFuture.addListener(() -> {
    // Call controllerFuture.get() to retrieve the MediaController.
    // MediaController implements the Player interface, so it can be
    // attached to the PlayerView UI component.
    playerView.setPlayer(controllerFuture.get());
  }, MoreExecutors.directExecutor())
}

MediaController, Player arayüzünü uyguladığından oynatmayı kontrol etmek için play() ve pause() gibi aynı yöntemleri kullanabilirsiniz. Diğer bileşenlerde olduğu gibi, artık ihtiyaç duyulmadığında MediaController öğesini serbest bırakmayı unutmayın. Örneğin, Activity öğesinin onStop() yaşam döngüsü yöntemini MediaController.releaseFuture() çağırarak serbest bırakabilirsiniz.

Bildirim yayınlama

Ön plan hizmetlerinin, etkin durumdayken bildirim yayınlaması gerekir. A MediaSessionService, MediaNotification şeklinde MediaStyle bildirimini sizin için otomatik olarak oluşturur. Özel bildirim sağlamak için DefaultMediaNotificationProvider.Builder ile MediaNotification.Provider oluşturun veya sağlayıcı arayüzünün özel bir uygulamasını oluşturun. setMediaNotificationProvider ile sağlayıcınızı MediaSession cihazınıza ekleyin.

İçerik kitaplığınızın reklamını yapma

MediaLibraryService, istemci uygulamalarının uygulamanız tarafından sağlanan medya içeriğine göz atmasına izin vererek MediaSessionService üzerine kurulur. İstemci uygulamaları, MediaLibraryService ile etkileşim kurmak için MediaBrowser uygular.

MediaLibraryService uygulamak, MediaSessionService uygulamaya benzer. Tek fark, onGetSession() içinde MediaSession yerine MediaLibrarySession döndürmeniz gerektiğidir. MediaSession.Callback ile karşılaştırıldığında MediaLibrarySession.Callback, tarayıcı istemcisinin kitaplık hizmetiniz tarafından sunulan içerikte gezinmesine olanak tanıyan ek yöntemler içerir.

MediaSessionService'ya benzer şekilde, manifest dosyanızda MediaLibraryService'ı bildirin ve ön plan hizmeti çalıştırmak için FOREGROUND_SERVICE iznini isteyin:

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

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

Yukarıdaki örnekte hem MediaLibraryService hem de geriye dönük uyumluluk için eski MediaBrowserService öğesiyle ilgili bir amaç filtresi yer almaktadır. Ek amaç filtresi, MediaBrowserCompat API'sini kullanan istemci uygulamalarının Service'nizi tanımasını sağlar.

MediaLibrarySession, içerik kitaplığınızı tek bir kök MediaItem ile ağaç yapısında sunmanıza olanak tanır. Ağaçtaki her MediaItem öğesinin istediğiniz sayıda alt MediaItem düğümü olabilir. İstemci uygulamasının isteğine bağlı olarak farklı bir kök veya farklı bir ağaç sunabilirsiniz. Örneğin, önerilen medya öğelerinin listesini arayan bir istemciye döndürdüğünüz ağaç yalnızca kök MediaItem ve tek bir çocuk düğümü MediaItem seviyesi içerebilirken farklı bir istemci uygulamasına döndürdüğünüz ağaç daha eksiksiz bir içerik kitaplığını temsil edebilir.

MediaLibrarySession oluşturma

MediaLibrarySession, içeriklere göz atma API'leri eklemek için MediaSession API'sini genişletir. MediaSession geri çağırmayla karşılaştırıldığında, MediaLibrarySession geri çağırma aşağıdaki gibi yöntemler ekler:

  • onGetLibraryRoot() Bir istemci, içerik ağacının MediaItem kökünü istediğinde
  • onGetChildren() Bir istemci, içerik ağacında MediaItem öğesinin alt öğelerini istediğinde
  • onGetSearchResult() Bir istemci, belirli bir sorgu için içerik ağacından arama sonuçları istediğinde

İlgili geri çağırma yöntemleri, bir istemci uygulamasının ilgilendiği içerik ağacı türüyle ilgili ek sinyaller içeren bir LibraryParams nesnesi içerecektir.