Oynatıcı Arayüzü

Oynatıcı, uygulamanızın medya öğelerinin oynatılmasını sağlayan bileşenidir. Media3 Player arayüzü genellikle bir oynatıcı tarafından işlenen işlevselliğin ana hatlarını belirler. Bu kapsamda şunlar yer alır:

• Oynatma, duraklatma ve arama gibi oynatma kontrollerini etkileme
• Şu anda oynatılan medyanın oynatma konumu gibi özelliklerini sorgulama
• Oynatma listesini/medya öğeleri sırasını yönetme
• Karıştırma, tekrarlama, hız ve ses gibi oynatma özelliklerini yapılandırma
• Videoyu ekranda oluşturma

Media3 ayrıca Player arayüzünün bir uygulamasını da sağlar. Bu uygulama ExoPlayer olarak adlandırılır.

İpucu: ExoPlayer kullanarak bir medya oynatıcı uygulaması oluşturmak istiyorsanız Media3 ExoPlayer kullanarak temel bir medya oynatıcı uygulaması oluşturma rehberine 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	Bir medya oynatıcı API'si ve Player arayüzünün varsayılan uygulaması.
MediaController	Oynatma komutları göndermek için MediaSession ile etkileşimde bulunur. Player ve MediaSession, oyuncunuzun kullanıcı arayüzünün bulunduğu Activity veya Fragment'den Service ayrı bir konumdaysa MediaController öğenizi PlayerView kullanıcı arayüzünüzün oynatıcısı olarak atayabilirsiniz. Oynatma ve oynatma listesi yöntemi çağrıları, MediaSession aracılığıyla Player cihazınıza gönderilir.
MediaBrowser	Bir MediaController tarafından sunulan işlevlere ek olarak, mevcut medya içeriklerine göz atmak için bir MediaLibrarySession ile etkileşimde bulunur.
SimpleBasePlayer	Uygulanacak yöntem sayısını minimuma indiren bir Player uygulaması. MediaSession'ya bağlamak istediğiniz özel bir oynatıcı kullanırken faydalıdır.
ForwardingSimpleBasePlayer	Oynatma işlemlerini başka bir Player öğesine yönlendirirken SimpleBasePlayer ile aynı tutarlı davranış özelleştirmelerine izin vermek için tasarlanmış bir SimpleBasePlayer alt sınıfı. Belirli oynatma işlemlerini bastırmak veya değiştirmek için bu sınıfı kullanın.
CastPlayer	Cast alıcı uygulamasıyla iletişim kuran bir Player uygulaması. Davranış, temel Cast oturumuna bağlıdır.

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 oynatma işleminizin reklamını yapabilir 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.

Medya arka planda oynatılı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ızdaki oynatma kontrolü için kullanıcı arayüzünü içeren etkinlikten ayırabilirsiniz. Bu durumda bir medya denetleyicisi kullanmanız gerekebilir.

Şekil 1: Player arayüzü, Media3'ün 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ğeri STATE_IDLE, STATE_BUFFERING, STATE_READY ve STATE_ENDED'dir.
2. Medya öğelerinin oynatma listesi
   • Oynatma için MediaItem örneği dizisi.
   • getCurrentTimeline() ile alma
   • Player örnekleri, oynatma listesi işlemleri için MediaItem ekleme veya kaldırma gibi yöntemler ve getCurrentMediaItem() gibi kolaylık sağlayan yöntemler sunabilir.
3. Aşağıdakiler gibi oynatma/duraklatma özellikleri:
   • playWhenReady: Kullanıcının, mümkün olduğunda medyanın oynatılmasını mı yoksa duraklatılmış kalmasını mı istediğini gösterir.
   • Oynatma engelleme nedeni: Oynatmanın neden engellendiğini gösterir. playWhenReady değeri true olsa bile geçerlidir.
   • isPlaying: Oynatıcının şu anda oynatıp oynatmadığını gösterir. Bu değer yalnızca oynatma durumu STATE_READY ise, playWhenReady değeri true ise ve oynatma engellenmemişse true olur.
4. Aşağıdakiler dahil olmak üzere oynatma konumu:
   • Geçerli medya öğesi dizini: Oynatma listesindeki geçerli MediaItem öğesinin dizini.
   • isPlayingAd: Yerleştirilen 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ü, mevcut parçalara, medya meta verilerine, oynatma hızına, ses seviyesine 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ılmasına izin verildiğini görmek için kullanılabilir komutları inceleyebilirsiniz.

Değişiklikleri dinleme

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 ExoPlayer belgelerindeki Player events (Oynatıcı etkinlikleri) bölümünü inceleyin.

Dinleyici arayüzünde, normal oynatma ilerlemesini izlemek için geri çağırma işlevlerinin bulunmadığını unutmayın. Oynatma ilerlemesini sürekli olarak izlemek için (ör. ilerleme çubuğu kullanıcı arayüzü ayarlamak) geçerli konumu uygun aralıklarla sorgulamanız gerekir.

Kotlin

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

Java

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

Oynatma seçeneklerini kontrol etme

Player arayüzü, durumu değiştirip oynatmayı kontrol etmek için birçok yöntem sunar:

• Temel oynatma kontrolleri ör. play(), pause(), prepare() ve stop().
• addMediaItem() veya removeMediaItem() gibi oynatma listesi işlemleri
• Mevcut öğeyi veya konumu değiştirmek için arama.
• Tekrarlama modlarını ve karıştırma 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ılmasına izin verildiğini görmek için kullanılabilir komutları inceleyebilirsiniz.

Özel Player uygulamaları

Özel bir oynatıcı oluşturmak için Media3'te yer alan SimpleBasePlayer öğesini genişletebilirsiniz. Bu sınıf, uygulamanız gereken yöntem sayısını en aza 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 mevcut oyuncu durumunu aşağıdaki bilgilerle doldurmalıdır:

• Kullanılabilir komutlar kümesi
• Oynatıcının oynatma durumu STATE_READY olduğunda oynatmaya başlayıp başlamaması, şu anda oynatılan medya öğesinin dizini ve geçerli öğe içindeki oynatma konumu gibi oynatma özellikleri

Kotlin

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // 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()
  }
}

Java

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

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // 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();
  }
}

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

getState() yönteminin yanı sıra yalnızca oynatıcınızın kullanılabilir olduğunu bildirdiği komutlar için kullanılan yöntemleri uygulamanız gerekir. Geçersiz kılınabilir işleyici yöntemini bulun. Bu yöntem, uygulamak istediğiniz işlevle eşleşmelidir. Ö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 ayrıntılı bilgi için Özelleştirme sayfası ile ilgili kılavuza bakın.