شروع کار با CastPlayer

CastPlayer یک پیاده‌سازی Jetpack Media3 Player است که از پخش محلی و پخش به یک دستگاه از راه دور با قابلیت پخش Cast پشتیبانی می‌کند. CastPlayer افزودن قابلیت پخش به برنامه شما را ساده می‌کند و ویژگی‌های غنی را برای جابجایی یکپارچه بین پخش محلی و از راه دور ارائه می‌دهد. این راهنما به شما نشان می‌دهد که چگونه CastPlayer در برنامه رسانه‌ای خود ادغام کنید.

برای ادغام Cast با سایر پلتفرم‌ها، به Cast SDK مراجعه کنید.

CastPlayer را به عنوان یک وابستگی اضافه کنید

برای شروع استفاده از CastPlayer، وابستگی‌های AndroidX Media3 و CastPlayer مورد نیاز خود را در فایل build.gradle ماژول برنامه خود اضافه کنید.

کاتلین 

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

گرووی 

implementation "androidx.media3:media3-exoplayer:1.9.0-alpha01"
implementation "androidx.media3:media3-ui:1.9.0-alpha01"
implementation "androidx.media3:media3-session:1.9.0-alpha01"
implementation "androidx.media3:media3-cast:1.9.0-alpha01"

برای یافتن آخرین نسخه آلفا و ادغام CastPlayer با برنامه خود، به یادداشت‌های انتشار Jetpack Media مراجعه کنید. همه ماژول‌ها باید از یک نسخه باشند.

برای اطلاعات بیشتر در مورد ماژول‌های کتابخانه‌ای موجود، به صفحه Google Maven AndroidX Media3 مراجعه کنید.

CastPlayer خود را پیکربندی کنید

برای پیکربندی CastPlayer ، فایل AndroidManifest.xml خود را با یک ارائه‌دهنده گزینه به‌روزرسانی کنید.

ارائه دهنده گزینه ها

CastPlayer برای پیکربندی رفتار خود به یک ارائه‌دهنده‌ی گزینه‌ها نیاز دارد. برای یک تنظیم اولیه، می‌توانید با افزودن ارائه‌دهنده‌ی گزینه‌های پیش‌فرض به فایل AndroidManifest.xml خود، از آن استفاده کنید. این از تنظیمات پیش‌فرض، از جمله برنامه‌ی گیرنده‌ی پیش‌فرض، استفاده می‌کند.

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

برای سفارشی‌سازی پیکربندی، OptionsProvider سفارشی خود را پیاده‌سازی کنید. برای یادگیری نحوه‌ی انجام این کار، به راهنمای CastOptions مراجعه کنید.

یک گیرنده برای انتقال رسانه اضافه کنید

افزودن یک MediaTransferReceiver به مانیفست شما، رابط کاربری سیستم را قادر می‌سازد تا بدون باز کردن اکتیویتی برنامه، رسانه را مجدداً مسیریابی کند. به عنوان مثال، کاربر می‌تواند دستگاهی را که رسانه برنامه شما را پخش می‌کند، از طریق اعلان رسانه تغییر دهد.

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

ساخت یک پخش‌کننده‌ی کاست

برای پخش از راه دور با Cast، برنامه شما باید بتواند پخش را حتی زمانی که کاربر با یک Activity از برنامه شما در تعامل نیست، مانند اعلان رسانه سیستم، مدیریت کند. به همین دلیل، باید نمونه‌های ExoPlayer (برای پخش محلی) و CastPlayer (برای پخش از راه دور) خود را در یک سرویس، مانند MediaSessionService یا MediaLibraryService ، ایجاد کنید. ابتدا، نمونه ExoPlayer خود را ایجاد کنید و سپس هنگام ساخت نمونه CastPlayer خود، ExoPlayer را به عنوان نمونه پخش کننده محلی تنظیم کنید. سپس Media3 قادر خواهد بود انتقال پخش کننده را هنگامی که مسیر خروجی از محلی به راه دور یا از راه دور به محلی تغییر می‌کند، مدیریت کند.

کاتلین 

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()
}

جاوا 

@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();
}

اضافه کردن عناصر رابط کاربری

یک MediaRouteButton به رابط کاربری برنامه خود اضافه کنید تا کاربران بتوانند دستگاه Cast را انتخاب کنند. این بخش به شما نشان می‌دهد که چگونه دکمه را اضافه کنید و به رویدادهایی گوش دهید تا رابط کاربری شما هنگام تغییر پخش بین دستگاه‌های محلی و راه دور به‌روزرسانی شود.

دکمه MediaRoute را تنظیم کنید

چهار روش ممکن برای افزودن دکمه MediaRouteButton به رابط کاربری اکتیویتی شما جهت تعامل کاربران وجود دارد. انتخاب روش به این بستگی دارد که می‌خواهید رابط کاربری اکتیویتی پخش‌کننده شما چگونه به نظر برسد و چگونه کار کند.

یک دکمه مسیر رسانه‌ای قابل ترکیب به پخش‌کننده اضافه کنید

شما می‌توانید دکمه‌ی ترکیبی MediaRouteButton به رابط کاربری پخش‌کننده‌ی خود اضافه کنید. برای اطلاعات بیشتر، به راهنمای ایجاد دکمه مراجعه کنید.

کاتلین 

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) {
  ...
}

دکمه مسیر رسانه را به PlayerView اضافه کنید

می‌توانید MediaRouteButton مستقیماً درون کنترل‌های رابط کاربری PlayerView اضافه کنید. پس از تنظیم MediaController به عنوان پخش‌کننده برای PlayerView ، یک MediaRouteButtonViewProvider برای نمایش دکمه Cast روی Player ارائه دهید.

کاتلین 

override fun onStart() {
  super.onStart()

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

جاوا 

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

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

دکمه مسیر رسانه را به منوی نوار برنامه اضافه کنید

این متد یک دکمه مسیر رسانه در منوی نوار برنامه تنظیم می‌کند. برای نمایش این سبک دکمه، به‌روزرسانی‌هایی در فایل مانیفست و Activity لازم است. 

<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>

کاتلین 

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)
    ...
}

جاوا 

@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);
    ...
}

دکمه مسیر رسانه را به عنوان یک View اضافه کنید

به عنوان یک روش جایگزین، می‌توانید یک MediaRouteButton در فایل layout.xml مربوط به activity خود تنظیم کنید. برای تکمیل تنظیمات مربوط به MediaRouteButton ، از Media3 Cast MediaRouteButtonFactory در کد Activity خود استفاده کنید.

کاتلین 

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

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

جاوا 

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

شنونده فعالیت

یک Player.Listener در Activity خود ایجاد کنید تا به تغییرات در محل پخش رسانه گوش دهد. وقتی playbackType بین PLAYBACK_TYPE_LOCAL و PLAYBACK_TYPE_REMOTE تغییر می‌کند، می‌توانید رابط کاربری خود را در صورت نیاز تنظیم کنید. برای جلوگیری از نشت حافظه و محدود کردن فعالیت شنونده فقط به زمانی که برنامه شما قابل مشاهده است، شنونده را در onStart ثبت کنید و آن را در onStop لغو ثبت کنید:

کاتلین 

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)
}

جاوا 

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);
}

برای اطلاعات بیشتر در مورد گوش دادن و پاسخ دادن به رویدادهای پخش، به راهنمای رویدادهای پخش‌کننده مراجعه کنید.