Oynatıcı Arayüzü

Oynatıcı, uygulamanızın medya öğelerinin oynatılmasını kolaylaştıran bileşenidir. Media3 Player arayüzü, genellikle bir oynatıcı tarafından gerçekleştirilen işlevler için bir taslak oluşturur. Bu kapsamda şunlar yer alır:

• Oynatma, duraklatma ve sarmak gibi oynatma kontrollerini etkileme
• Oynatılmakta olan medyanın özelliklerini (ör. oynatma konumu) sorgulama
• Medya öğelerinden oluşan bir oynatma listesini/sırayı yönetme
• Karışık çalma, tekrarlama, hız ve ses düzeyi gibi oynatma özelliklerini yapılandırma
• Video ekranda oluşturuluyor

Media3, ExoPlayer adlı Player arayüzünün bir uygulamasını da sağlar.

İpucu: ExoPlayer'ı kullanarak bir medya oynatıcı uygulaması uygulamak istiyorsanız Media3 ExoPlayer'ı kullanarak temel bir medya oynatıcı uygulaması oluşturma kılavuzuna göz atın.

Bileşenler arasında ortak bir arayüz

Media3'teki çeşitli bileşenler Player arayüzünü uygular. Örneğin:

Bileşen	Açıklama ve davranış notları
ExoPlayer	Medya oynatıcı API'si ve Player arayüzünün varsayılan uygulaması.
MediaController	Oynatma komutları göndermek için MediaSession ile etkileşim kurar. Player ve MediaSession öğeleriniz, oynatıcınızın kullanıcı arayüzünün bulunduğu Activity veya Fragment öğesinden ayrı bir Service öğesindeyse MediaController öğenizi, PlayerView veya Player Composable gibi kullanıcı arayüzü bileşeniniz için oynatıcı olarak atayabilirsiniz. Oynatma ve oynatma listesi yöntem çağrıları, MediaSession üzerinden Player cihazınıza gönderilir.
MediaBrowser	MediaController tarafından sunulan işlevlere ek olarak, mevcut medya içeriğine göz atmak için MediaLibrarySession ile etkileşim kurar.
SimpleBasePlayer	Uygulanacak yöntem sayısını en aza indiren bir Player uygulaması. Bir MediaSession öğesine bağlamak istediğiniz özel bir oynatıcı kullanırken faydalıdır.
ForwardingSimpleBasePlayer	Oynatma işlemlerini başka bir Player sınıfına yönlendirmek için tasarlanmış bir SimpleBasePlayer alt sınıfı. SimpleBasePlayer ile aynı tutarlı davranış özelleştirmelerine olanak tanır. Belirli oynatma işlemlerini engellemek veya değiştirmek için bu sınıfı kullanın.
RemoteCastPlayer	Uzak bir Cast alıcı uygulamasında oynatmayı kontrol eden Player uygulaması.
CastPlayer	Hem yerel hem de uzaktan Cast oynatmayı kontrol etmek için bir Player uygulaması.

MediaSession, Player arayüzünü uygulamasa da oluşturulurken Player gerektirir. Amacı, diğer işlemlerden veya iş parçacıklarından Player erişim sağlamaktır.

Media3 oynatma mimarisi

Player erişiminiz varsa oynatma komutları vermek için yöntemlerini doğrudan çağırmanız gerekir. MediaSession uygulayarak oynatmanızı tanıtabilir ve harici kaynaklara oynatma kontrolü verebilirsiniz. Bu harici kaynaklar, medya oturumuna bağlanmayı ve oynatma komutu istekleri göndermeyi kolaylaştıran bir MediaController uygular.

Medyayı arka planda oynatırken medya oturumunuzu ve oynatıcınızı ön plan hizmeti olarak çalışan bir MediaSessionService veya MediaLibraryService içinde barındırmanız gerekir. Bunu yaparsanız oynatıcınızı, uygulamanızda oynatma kontrolü için kullanıcı arayüzünü içeren etkinlikten ayırabilirsiniz. Bu durumda medya kumandası kullanmanız gerekebilir.

Şekil 1: Player arayüzü, Media3 mimarisinde önemli bir rol oynar.

Oynatıcı durumu

Player arayüzünü uygulayan bir medya oynatıcının durumu temel olarak 4 bilgi kategorisinden oluşur:

1. Oynatma durumu
   • getPlaybackState() ile alın.
   • Arayüz tarafından tanımlanan durum değerleri şunlardır: STATE_IDLE, STATE_BUFFERING, STATE_READY, ve STATE_ENDED.
2. Medya öğelerinin oynatma listesi
   • Oynatma için MediaItem örnekten oluşan bir dizi.
   • getCurrentTimeline() ile alma
   • Player örnekleri, MediaItem ekleme veya kaldırma gibi oynatma listesi işlem yöntemleri ve getCurrentMediaItem() gibi kolaylık yöntemleri sağlayabilir.
3. Oynatma/duraklatma özellikleri, örneğin:
   • playWhenReady: Kullanıcının, medyanın mümkün olduğunda oynatılmasını mı yoksa duraklatılmış olarak kalmasını mı istediğini gösterir.
   • Oynatmayı engelleme nedeni: playWhenReady, true olsa bile oynatmanın neden engellendiğini gösterir (varsa).
   • isPlaying: Oynatıcının şu anda oynatılıp oynatılmadığını gösterir. Yalnızca oynatma durumu STATE_READY, playWhenReady true olduğunda ve oynatma engellenmediğinde true olur.
4. Oynatma konumu, aşağıdakiler dahil:
   • Mevcut medya öğesi dizini: Oynatma listesindeki mevcut MediaItem öğesinin dizini.
   • isPlayingAd: Eklenen bir reklamın oynatılıp oynatılmadığını gösterir.
   • Mevcut oynatma konumu: Mevcut MediaItem veya eklenen reklamdaki mevcut oynatma konumu.

Ayrıca Player arayüzü; kullanılabilir parçalara, medya meta verilerine, oynatma hızına, ses düzeyine ve oynatmanın diğer yardımcı özelliklerine erişim sağlar.

Not: Player örneklerinin, arayüzün tüm özelliklerini desteklemesi gerekmez. Hangi özelliğin desteklendiğini ve hangi yöntemin çağrılabileceğini görmek için kullanılabilir komutları kontrol edebilirsiniz.

Değişiklikleri dinleme

Bir Player içindeki değişiklikleri dinlemek için Player.Listener kullanın. Dinleyici oluşturma ve kullanma hakkında ayrıntılı bilgi için Oynatıcı etkinlikleri ile ilgili ExoPlayer belgelerine bakın.

Dinleyici arayüzünün, normal oynatma ilerlemesini izlemek için herhangi bir geri çağırma içermediğini unutmayın. Oynatma ilerleme durumunu sürekli olarak izlemek için (ör. ilerleme çubuğu kullanıcı arayüzü oluşturmak için) mevcut konumu uygun aralıklarla sorgulamanız gerekir.

Kotlin

fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs,
  )
Player.kt

Java

boolean checkPlaybackPosition(long delayMs) {
  return handler.postDelayed(
      () -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
      },
      delayMs);
}
Player.java

Oynatma seçeneklerini kontrol etme

Player arayüzü, durumu değiştirmenin ve oynatmayı kontrol etmenin birçok yolunu sunar:

• play(), pause(), prepare() ve stop() gibi temel oynatma kontrolleri.
• addMediaItem() veya removeMediaItem() gibi oynatma listesi işlemleri.
• Mevcut öğeyi veya konumu değiştirmek için arama.
• Tekrar modlarını ve karışık modunu ayarlayın.
• Parça seçimi tercihlerini güncelleyin.
• Oynatma hızını ayarlayın.

Not: Player örneklerinin, arayüzün tüm özelliklerini desteklemesi gerekmez. Hangi özelliğin desteklendiğini ve hangi yöntemin çağrılabileceğini görmek için kullanılabilir komutları kontrol edebilirsiniz.

Özel Player uygulamaları

Özel bir oynatıcı oluşturmak için Media3'te bulunan SimpleBasePlayer sınıfını genişletebilirsiniz. Bu sınıf, uygulamanız gereken yöntemlerin sayısını minimuma indirmek için Player arayüzünün temel bir uygulamasını sağlar.

getState() yöntemini geçersiz kılarak başlayın. Bu yöntem çağrıldığında, aşağıdakiler dahil olmak üzere mevcut oyuncu durumunu doldurmalıdır:

• Kullanılabilir komutlar kümesi
• Oynatma durumu STATE_READY olduğunda oynatıcının oynatmaya başlayıp başlamayacağı, oynatılmakta olan medya öğesinin dizini ve mevcut öğedeki oynatma konumu gibi oynatma özellikleri

Kotlin

class CustomPlayer(looper: Looper) : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(Commands.EMPTY) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}
Player.kt

Java

private static final class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
        .setAvailableCommands(Commands.EMPTY) // Set which playback commands the player can handle
        // Configure additional playback properties
        .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
        .setCurrentMediaItemIndex(0)
        .setContentPositionMs(0)
        .build();
  }
}
Player.java

SimpleBasePlayer, State öğesinin geçerli bir durum değerleri kombinasyonuyla oluşturulmasını zorunlu kılar. Ayrıca dinleyicileri ve dinleyicileri durum değişiklikleri hakkında bilgilendirmeyi de yönetir. Bir durum güncellemesini manuel olarak tetiklemeniz gerekiyorsa invalidateState() yöntemini çağırın.

getState() yönteminin yanı sıra, yalnızca oynatıcınızın kullanılabilir olduğunu beyan ettiği komutlar için kullanılan yöntemleri uygulamanız gerekir. Uygulamak istediğiniz işlevle ilgili geçersiz kılınabilir işleyici yöntemini bulun. Örneğin, COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM ve COMMAND_SEEK_TO_NEXT_MEDIA_ITEM gibi işlemleri desteklemek için handleSeek() yöntemini geçersiz kılın.

Player uygulamalarını değiştirme

Tamamen özel bir Player oluşturmak yerine, mevcut bir Player öğesinin durumunu ve davranışını değiştirmek için ForwardingSimpleBasePlayer kullanabilirsiniz. Daha fazla bilgi için Özelleştirme sayfası ile ilgili kılavuza bakın.