Oynatıcı Arayüzü

Oynatıcı, uygulamanızda medya öğelerinin oynatılmasını kolaylaştıran bileşendir. Media3 Player arayüzü, genellikle bir oynatıcı tarafından işlenen işlevler için bir ana hat oluşturur. Buna şunlar dahildir:

• Oynat, duraklat ve sarma gibi oynatma kontrollerini etkileme
• Şu anda oynatılan medyanın oynatma konumu gibi özelliklerini sorgulamak
• Medya öğelerinden oluşan bir oynatma listesini/sırayı yönetme
• Karıştırma, tekrarlama, hız ve ses seviyesi gibi oynatma özelliklerini yapılandırma
• Videoyu ekrana oluşturma

Media3, Player arayüzünün ExoPlayer adlı 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ılavuzunu inceleyin.

Bileşenler arasında ortak bir arayüz

Media3'teki çeşitli bileşenler Oynatıcı 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şim kurar. Player ve MediaSession'ünüz, oyuncunuzun kullanıcı arayüzünün bulunduğu Activity veya Fragment'ten ayrı bir Service'deyse MediaController'inizi PlayerView kullanıcı arayüzünüzün oyuncusu olarak atayabilirsiniz. Oynatma ve oynatma listesi yöntemi çağrıları, MediaSession üzerinden Player'ünüze 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ı minimuma indiren bir Player uygulaması. MediaSession'ye bağlamak istediğiniz özel bir oynatıcı kullanırken kullanışlıdır.
ForwardingSimpleBasePlayer	Oynatma işlemlerini başka bir Player öğesine yönlendirmek için tasarlanmış bir SimpleBasePlayer alt sınıfı. Bu 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.
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 bir Player gerektirir. Amacının, diğer işlemlerden veya iş parçalarından Player'e erişim sağlamak olduğunu belirtmek isteriz.

Media3 oynatma mimarisi

Bir Player'e erişiminiz varsa oynatma komutları vermek için doğrudan yöntemlerini ç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 isteklerini göndermeyi kolaylaştıran bir MediaController uygular.

Arka planda medya 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ı, oynatma kontrolü için kullanıcı arayüzünü içeren uygulamanızdaki Etkinlik'ten ayırabilirsiniz. Bu durumda bir medya kumandası kullanmanız gerekebilir.

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

Oyuncu 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 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, 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 (ör. aşağıdakiler):
   • playWhenReady: Kullanıcı, mümkün olduğunda medyanın oynatılmasını mı yoksa duraklatılmasını mı istediğini belirtir.
   • Oynatma engelleme nedeni: playWhenReady true olsa bile oynatmanın neden engellendiğini belirten bir gösterge
   • isPlaying: Oynatıcının şu anda oynatıp oynatmadığını belirtir. Yalnızca oynatma durumu STATE_READY, playWhenReady true ise ve oynatma engellenmemişse true olur.
4. Aşağıdakiler dahil olmak üzere oynatma konumu:
   • Mevcut medya öğesi dizini: Oynatma listesindeki geçerli MediaItem öğesinin dizini.
   • isPlayingAd: Eklenen bir reklamın oynatılıp oynatılmadığını belirtir.
   • Mevcut oynatma konumu: Mevcut MediaItem veya yerleştirilmiş 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şmenize olanak tanır.

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 mevcut komutları kontrol edebilirsiniz.

Değişiklikleri dinleyin

Player'daki değişiklikleri dinlemek için Player.Listener kullanın. Dinleyici oluşturma ve kullanmayla ilgili ayrıntılar için ExoPlayer'ın Oynatıcı etkinlikleri ile ilgili belgelerini inceleyin.

Dinleyici arayüzünün, normal oynatma ilerleme durumunu izlemek için geri çağırma içermediğini unutmayın. Oynatma ilerlemesini 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

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ştirmek ve oynatmayı kontrol etmek için birçok yöntem sunar:

• play(), pause(), prepare() ve stop() gibi temel oynatma kontrolleri
• addMediaItem() veya removeMediaItem() gibi şarkı 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 mevcut komutları kontrol edebilirsiniz.

Özel Player uygulamaları

Özel bir oynatıcı oluşturmak için Media3'e dahil edilen SimpleBasePlayer öğesini genişletebilirsiniz. Bu sınıf, uygulamanız gereken yöntem sayısını minimuma indirmek için Playerarabirimini temel bir şekilde uygular.

getState() yöntemini geçersiz kılarak başlayın. Bu yöntem, çağrıldığında mevcut oyuncu durumunu doldurmalıdır. Şunlar dahildir:

• Kullanılabilir komutlar grubu
• Oynatma durumu STATE_READY olduğunda oynatıcının oynatmaya başlayıp başlamaması, oynatılmakta olan medya öğesinin dizini ve mevcut öğedeki 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 değerinin geçerli bir durum değeri kombinasyonuyla oluşturulmasını zorunlu kılar. Ayrıca dinleyicileri yönetir ve dinleyicileri durum değişiklikleri hakkında bilgilendirir. Durum güncellemesini manuel olarak tetiklemeniz gerekiyorsa invalidateState() numaralı telefondan bizi arayın.

getState() yönteminin yanı sıra, yalnızca oynatıcının kullanılabilir olduğunu beyan ettiği komutlar için kullanılan yöntemleri uygulamanız gerekir. Uygulamak istediğiniz işleve karşılık gelen 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.