CastPlayer'ı kullanmaya başlama

CastPlayer, hem yerel oynatmayı hem de uzak Cast özellikli bir cihaza yayınlamayı destekleyen bir Jetpack Media3 Player uygulamasıdır. CastPlayer Uygulamanıza yayın işlevi eklemeyi kolaylaştırır ve yerel ile uzaktan oynatma arasında sorunsuz geçiş yapmanızı sağlayan zengin özellikler sunar. Bu kılavuzda, CastPlayer'i medya uygulamanıza nasıl entegre edeceğiniz gösterilmektedir.

Cast'i diğer platformlarla entegre etmek için Cast SDK'ya bakın.

Cast özellikli bir cihaz edinme

CastPlayer özelliğini test etmek için Cast özellikli bir cihaz gerekir. Android TV, Chromecast, akıllı hoparlörler ve akıllı ekranlar bu seçenekler arasındadır. Cihazınızın, keşif için geliştirme mobil cihazınızla aynı kablosuz ağa bağlı ve ayarlanmış olduğunu doğrulayın.

Derleme bağımlılıkları ekleme

CastPlayer kullanmaya başlamak için AndroidX Media3 ve CastPlayer bağımlılıklarını uygulama modülünüzün build.gradle dosyasına ekleyin.

Kotlin

implementation("androidx.media3:media3-exoplayer:1.9.2")
implementation("androidx.media3:media3-ui:1.9.2")
implementation("androidx.media3:media3-session:1.9.2")
implementation("androidx.media3:media3-cast:1.9.2")

Groovy

implementation "androidx.media3:media3-exoplayer:1.9.2"
implementation "androidx.media3:media3-ui:1.9.2"
implementation "androidx.media3:media3-session:1.9.2"
implementation "androidx.media3:media3-cast:1.9.2"

CastPlayer'ınızı yapılandırma

CastPlayer yapılandırmak için AndroidManifest.xml dosyanızı bir seçenek sağlayıcıyla güncelleyin.

Seçenek sağlayıcı

CastPlayer, davranışını yapılandırmak için bir seçenek sağlayıcı gerektirir. Temel kurulum için AndroidManifest.xml dosyanıza ekleyerek DefaultCastOptionsProvider kullanabilirsiniz. Bu işlem için varsayılan alıcı uygulaması da dahil olmak üzere varsayılan ayarlar kullanılır.

<application>
  ...
  <meta-data
    android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
    android:value="androidx.media3.cast.DefaultCastOptionsProvider" />
  ...
</application>

Yapılandırmayı özelleştirmek için kendi özel OptionsProvider'nizi uygulayın. Bunun nasıl yapılacağını öğrenmek için CastOptions kılavuzuna bakın.

Medya aktarımları için alıcı ekleme

Manifest dosyanıza MediaTransferReceiver eklediğinizde, sistem kullanıcı arayüzü ağdaki Cast özellikli cihazları keşfedebilir ve uygulama etkinliğini açmadan medyayı yeniden yönlendirebilir. Örneğin, bir kullanıcı uygulamanızın medya içeriğini oynatan cihazı medya bildiriminden değiştirebilir.

<application>
  ...
  <receiver android:name="androidx.mediarouter.media.MediaTransferReceiver" />
  ...
</application>

CastPlayer oluşturma

Cast ile uzaktan oynatma için uygulamanız, kullanıcı uygulamanızdaki bir Etkinlik ile etkileşimde bulunmadığında bile (ör. sistem medya bildirimi aracılığıyla) oynatmayı yönetebilmelidir. Bu nedenle, MediaSessionService veya MediaLibraryService gibi bir hizmette ExoPlayer (yerel oynatma için) ve CastPlayer (uzaktan oynatma için) örneklerinizi oluşturmanız gerekir. Öncelikle ExoPlayer örneğinizi oluşturun ve ardından CastPlayer örneğinizi oluştururken yerel oyuncu örneği olarak ExoPlayer öğesini ayarlayın. Ardından, medya bildiriminden veya kilit ekranı bildiriminden medya oynatmayı mobil cihazınız ile Cast özellikli cihaz arasında değiştirebilirsiniz. Media3, çıkış rotası yerelden uzağa veya uzaktan yerel olarak değiştiğinde oynatıcı aktarımlarını yönetmek için Output Switcher özelliğini kullanır.

Bildirimlerdeki Çıkış Değiştirici kullanıcı arayüzünü gösteren ekran görüntüsü.
Şekil 1: (a) Medya bildirimindeki cihaz çipi (b) Cihaz çipine dokunulduğunda gösterilen Cast özellikli cihazlar (c) Kilit ekranı bildirimindeki cihaz çipi

Kotlin

override fun onCreate() {
  super.onCreate()

  val exoPlayer = ExoPlayer.Builder(context).build()
  val castPlayer = CastPlayer.Builder(context)
      .setLocalPlayer(exoPlayer)
      .build()

  mediaSession = MediaSession.Builder(context, castPlayer).build()
}

Java

@Override
public void onCreate() {
  super.onCreate();

  ExoPlayer exoPlayer = new ExoPlayer.Builder(context).build();
  CastPlayer castPlayer = new CastPlayer.Builder(context)
      .setLocalPlayer(exoPlayer)
      .build();

  mediaSession = new MediaSession.Builder(
    /* context= */ context, /* player= */ castPlayer).build();
}

Kullanıcı arayüzü öğeleri ekleme

Uygulamanızın kullanıcı arayüzüne MediaRouteButton ekleyin. MediaRouteButton simgesine dokunduğunuzda, ağda kullanılabilen Cast özellikli cihazların listesini gösteren bir iletişim kutusu açılır. Kullanıcı bir cihaz seçtiğinde medya oynatma işlemi mobil cihazdan seçilen alıcı cihaza aktarılır. Bu bölümde, oynatma yerel ve uzak cihazlar arasında değiştiğinde kullanıcı arayüzünüzü güncellemek için düğmeyi nasıl ekleyeceğiniz ve etkinlikleri nasıl dinleyeceğiniz gösterilmektedir.

MediaRouteButton'ı ayarlama

MediaRouteButton simgesini etkinliğinizin kullanıcı arayüzüne eklemenin dört yolu vardır. En iyi seçim, uygulamanızın tasarımına ve gereksinimlerine bağlıdır.

  • Compose kullanıcı arayüzü: Düğme oluşturulabilir öğesi ekleyin.
  • Görüntüleme sayısı kullanıcı arayüzü:
    • Düğmeyi uygulama çubuğu menüsüne ekleyin.
    • Düğmeyi PlayerView içine ekleyin.
    • Düğmeyi standart View olarak ekleyin.
Kullanıcı arayüzünde MediaRouteButton&#39;ı gösteren ekran görüntüsü.
Şekil 2: (a) Menü çubuğundaki MediaRouteButton, (b) Görünüm olarak, (c) PlayerView'da ve (d) Cast özellikli cihazların iletişim kutusu.

Oynatıcıya Composable MediaRouteButton ekleme

MediaRouteButton Composable'ı oynatıcınızın kullanıcı arayüzüne ekleyebilirsiniz. Daha fazla bilgi için Oluşturma kılavuzuna bakın.

Kotlin

import androidx.compose.animation.AnimatedVisibility
import androidx.compose.animation.fadeIn
import androidx.compose.animation.fadeOut
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.media3.cast.MediaRouteButton

@Composable
fun PlayerComposeView(player: Player, modifier: Modifier = Modifier) {
  var controlsVisible by remember { mutableStateOf(false) }

  Box(
    modifier = modifier.clickable { controlsVisible = true },
    contentAlignment = Alignment.Center,
  ) {
    PlayerSurface(player = player, modifier = modifier)
    AnimatedVisibility(visible = controlsVisible, enter = fadeIn(), exit = fadeOut()) {
      Box(modifier = Modifier.fillMaxSize()) {
        MediaRouteButton(modifier = Modifier.align(Alignment.TopEnd))
        PrimaryControls(player = player, modifier = Modifier.align(Alignment.Center))
      }
    }
  }
}

@Composable
fun PrimaryControls(player: Player, modifier: Modifier = Modifier) {
  ...
}

MediaRouteButton öğesini PlayerView'a ekleyin.

MediaRouteButton simgesini doğrudan PlayerView'in kullanıcı arayüzü kontrollerine ekleyebilirsiniz. MediaController'ı PlayerView için oynatıcı olarak ayarladıktan sonra, oynatıcıda Cast düğmesini göstermek için MediaRouteButtonViewProvider sağlayın.

Kotlin

override fun onStart() {
  super.onStart()

  playerView.player = mediaController
  playerView.setMediaRouteButtonViewProvider(MediaRouteButtonViewProvider())
}

Java

@Override
public void onStart() {
  super.onStart();

  playerView.setPlayer(mediaController);
  playerView.setMediaRouteButtonViewProvider(new MediaRouteButtonViewProvider());
}

Uygulama çubuğu menüsüne MediaRouteButton simgesini ekleme

Uygulama çubuğu menüsünde MediaRouteButton ayarlamak için bir XML menüsü oluşturun ve Activity'nizde onCreateOptionsMenu öğesini geçersiz kılın.

<menu xmlns:android="http://schemas.android.com/apk/res/android"
         xmlns:app="http://schemas.android.com/apk/res-auto">
  <item android:id="@+id/media_route_menu_item"
    android:title="@string/media_route_menu_title"
    app:showAsAction="always"
    app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"/>
</menu>

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    ...
    menuInflater.inflate(R.menu.sample_media_route_button_menu, menu)
    val menuItemFuture: ListenableFuture<MenuItem> =
        MediaRouteButtonFactory.setUpMediaRouteButton(
            context, menu, R.id.media_route_menu_item)
    Futures.addCallback(
        menuItemFuture,
        object : FutureCallback<MenuItem> {
            override fun onSuccess(menuItem: MenuItem?) {
                // Do something with the menu item.
            }

            override fun onFailure(t: Throwable) {
                // Handle the failure.
            }
        },
        executor)
    ...
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    ...
    getMenuInflater().inflate(R.menu.sample_media_route_button_menu, menu);
    ListenableFuture<MenuItem> menuItemFuture =
        MediaRouteButtonFactory.setUpMediaRouteButton(
          context, menu, R.id.media_route_menu_item);
    Futures.addCallback(
        menuItemFuture,
        new FutureCallback<MenuItem>() {
          @Override
          public void onSuccess(MenuItem menuItem) {
            // Do something with the menu item.
          }

          @Override
          public void onFailure(Throwable t) {
            // Handle the failure.
          }
        },
        executor);
    ...
}

MediaRouteButton öğesini Görünüm olarak ekleme

Etkinlik düzeninizde layout.xml MediaRouteButton oluşturabilirsiniz.

  <androidx.mediarouter.app.MediaRouteButton
      android:id="@+id/media_route_button"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      app:mediaRouteButtonTint="@android:color/white" />

MediaRouteButton kurulumunu tamamlamak için Activity kodunuzda Media3 Cast'i MediaRouteButtonFactory kullanın.

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  findViewById<MediaRouteButton>(R.id.media_route_button)?.also {
    val unused = MediaRouteButtonFactory.setUpMediaRouteButton(context, it)
  }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    ...
    MediaRouteButton button = findViewById(R.id.media_route_button);
    ListenableFuture<Void> setUpFuture =
        MediaRouteButtonFactory.setUpMediaRouteButton(context, button);
}

Etkinlik Dinleyici

Medya oynatma konumundaki değişiklikleri dinlemek için Activity içinde Player.Listener oluşturun. playbackType PLAYBACK_TYPE_LOCAL ile PLAYBACK_TYPE_REMOTE arasında değiştiğinde kullanıcı arayüzünüzü gerektiği gibi ayarlayabilirsiniz. Bellek sızıntılarını önlemek ve dinleyici etkinliğini yalnızca uygulamanız görünür durumdayken sınırlandırmak için dinleyiciyi onStart içinde kaydedin ve onStop içinde kaydını silin:

Kotlin

import androidx.media3.common.DeviceInfo
import androidx.media3.common.Player

private val playerListener: Player.Listener =
  object : Player.Listener {
    override fun onDeviceInfoChanged(deviceInfo: DeviceInfo) {
      if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_LOCAL) {
        // Add UI changes for local playback.
      } else if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_REMOTE) {
        // Add UI changes for remote playback.
      }
    }
  }

override fun onStart() {
  super.onStart()
  mediaController.addListener(playerListener)
}

override fun onStop() {
  super.onStop()
  mediaController.removeListener(playerListener)
}

Java

import androidx.media3.common.DeviceInfo;
import androidx.media3.common.Player;

private Player.Listener playerListener =
    new Player.Listener() {
      @Override
      public void onDeviceInfoChanged(DeviceInfo deviceInfo) {
        if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_LOCAL) {
          // Add UI changes for local playback.
        } else if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_REMOTE) {
          // Add UI changes for remote playback.
        }
      }
    };

@Override
protected void onStart() {
  super.onStart();
  mediaController.addListener(playerListener);
}

@Override
protected void onStop() {
  super.onStop();
  mediaController.removeListener(playerListener);
}

Oynatma etkinliklerini dinleme ve bunlara yanıt verme hakkında daha fazla bilgi için oynatıcı etkinlikleri kılavuzuna bakın.