Introdução ao CastPlayer

O CastPlayer é uma implementação do Player do Jetpack Media3 que oferece suporte a reprodução local e à transmissão para um dispositivo remoto compatível com o Cast. CastPlayer simplifica a adição da funcionalidade de transmissão ao seu app e oferece recursos avançados para alternar entre a reprodução local e remota. Este guia mostra como integrar CastPlayer ao seu app de mídia.

Para integrar o Cast a outras plataformas, consulte o SDK do Cast.

Ter um dispositivo compatível com o Cast

Para testar CastPlayer, você precisa de um dispositivo compatível com o Cast. As opções incluem Android TV, Chromecast, alto-falantes inteligentes e telas inteligentes. Verifique se o dispositivo está configurado e conectado à mesma rede Wi-Fi do seu dispositivo móvel de desenvolvimento para descoberta.

Adicionar dependências de compilação

Para começar a usar o CastPlayer, adicione as dependências do AndroidX Media3 e do CastPlayer ao arquivo build.gradle do módulo do app.

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

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

Configurar o CastPlayer

Para configurar o CastPlayer, atualize o arquivo AndroidManifest.xml com um provedor de opções.

Provedor de opções

O CastPlayer exige um provedor de opções para configurar o comportamento dele. Para uma configuração básica, adicione o DefaultCastOptionsProvider ao seu AndroidManifest.xml arquivo. Isso usa as configurações padrão, incluindo o aplicativo receptor padrão.

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

Para personalizar a configuração, implemente seu próprio OptionsProvider personalizado. Consulte o guia CastOptions para saber como.

Adicionar um receptor para transferências de mídia

A adição de um MediaTransferReceiver ao manifesto permite que a interface do sistema descubra dispositivos compatíveis com o Cast na rede e redirecione a mídia sem abrir a atividade do app. Por exemplo, um usuário pode mudar o dispositivo que reproduz a mídia do seu app na notificação de mídia.

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

Criar um CastPlayer

Para reprodução remota com o Cast, seu app precisa ser capaz de gerenciar a reprodução mesmo quando o usuário não está interagindo com uma Activity do app, como pela notificação de mídia do sistema. Por esse motivo, crie instâncias de ExoPlayer (para reprodução local) e CastPlayer (para reprodução remota) em um serviço, como MediaSessionService ou MediaLibraryService. Primeiro, crie a instância do ExoPlayer e, ao criar a instância do CastPlayer, defina o ExoPlayer como a instância do player local. Em seguida, você pode alternar a reprodução de mídia entre o dispositivo móvel e o dispositivo compatível com o Cast na notificação de mídia ou na notificação da tela de bloqueio. O Media3 usa o recurso Seletor de saída para processar transferências de player quando a rota de saída muda de local para remota ou de remota para local.

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()
}
CreateCastPlayer.kt

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

Adicionar elementos da interface

Adicione um MediaRouteButton à interface do app. Tocar no MediaRouteButton abre uma caixa de diálogo mostrando uma lista de dispositivos compatíveis com o Cast disponíveis na rede. Quando o usuário seleciona um dispositivo, a reprodução de mídia é transferida do dispositivo móvel para o dispositivo receptor selecionado. Esta seção mostra como adicionar o botão e detectar eventos para atualizar a interface quando a reprodução muda entre dispositivos locais e remotos.

Definir o MediaRouteButton

Há quatro maneiras de adicionar o MediaRouteButton à interface da atividade. A melhor opção depende do design e dos requisitos do seu app.

• Interface do Compose: adicione um elemento combinável de botão.
• Interface de visualizações:
  • Adicione o botão ao menu da barra de apps.
  • Adicione o botão dentro de PlayerView.
  • Adicione o botão como uma View padrão.

Adicionar um MediaRouteButton combinável ao player

Você pode adicionar o MediaRouteButton combinável à interface do player. Para mais informações, consulte o guia do Compose.

@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) {
  // ...
}
CreateCastPlayer.kt

Adicionar o MediaRouteButton ao PlayerView

Você pode adicionar o MediaRouteButton diretamente nos PlayerView's UI controls. Depois de definir o MediaController como o player do PlayerView, forneça um MediaRouteButtonViewProvider para mostrar o botão "Transmitir" no player.

override fun onStart() {
  super.onStart()

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

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

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

Adicionar o MediaRouteButton ao menu da barra de apps

Para configurar um MediaRouteButton no menu da barra de apps, crie um menu XML e substitua onCreateOptionsMenu na sua 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,
  )
  // ...
  return true
}
CreateCastPlayer.kt

@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);
  // ...
  return true;
}
CreateCastPlayer.java

Adicionar o MediaRouteButton como uma visualização

Você pode configurar um MediaRouteButton no layout.xml da atividade.

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

Para concluir a configuração do MediaRouteButton, use o Media3 Cast MediaRouteButtonFactory no código da Activity.

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

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

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

Listener de atividade

Crie um Player.Listener na sua Activity para detectar mudanças no local da visualização de mídia. Quando o playbackType muda entre PLAYBACK_TYPE_LOCAL e PLAYBACK_TYPE_REMOTE, você pode ajustar a interface conforme necessário. Para evitar vazamentos de memória e confinar a atividade do listener apenas quando o app estiver visível, registre o listener em onStart e cancele o registro dele em onStop:

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

private final 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);
}
CreateCastPlayer.java

Para mais informações sobre como detectar e responder a eventos de reprodução, consulte o guia de eventos do player.