Criar e configurar um DefaultPreloadManager

Nesta página, descrevemos como criar um DefaultPreloadManager, que pré-carrega conteúdo de mídia para seu app com base na estratégia escolhida.

Os gerenciadores de pré-carregamento baseados na classe abstrata BasePreloadManager permitem classificar o conteúdo de acordo com os critérios escolhidos. Neste documento, explicamos como usar a classe derivada DefaultPreloadManager, em que cada item de mídia é classificado com um número inteiro que representa o local dele em uma lista (por exemplo, a posição em um carrossel de vídeos). O gerenciador de pré-carregamento prioriza o carregamento dos itens com base na proximidade do item que o usuário está reproduzindo no momento. Dessa forma, se um usuário passar para outro item, o novo item poderá começar a ser reproduzido imediatamente.

Há três etapas para criar uma instância de DefaultPreloadManager:

  • Defina um TargetPreloadStatusControl que o gerenciador de pré-carregamento possa consultar para saber se o item de mídia está pronto para ser carregado e quanto carregar.
  • Crie o builder que será usado para criar o gerenciador de pré-carregamento e os objetos ExoPlayer do app.
  • Use o builder para criar o gerenciador de pré-carregamento chamando o método build() dele.

Criar um controle de status de pré-carregamento de destino

Ao criar o DefaultPreloadManager.Builder, você vai transmitir um objeto de controle de status de pré-carregamento de destino que você definir. Esse objeto implementa a interface TargetPreloadStatusControl. Quando o gerenciador de pré-carregamento está se preparando para pré-carregar mídia, ele chama o método getTargetPreloadStatus() do controle de status para determinar se deve preparar, carregar ou armazenar em cache o conteúdo de um item de mídia. O carregamento pré-carrega os dados de mídia diretamente no buffer na memória de um player, deixando-os prontos para reprodução instantânea, enquanto o armazenamento em cache salva os dados de mídia em um cache em disco permanente para economizar memória do player. O controle de status pode responder com um destes códigos de status:

  • STAGE_SPECIFIED_RANGE_LOADED: o gerenciador de pré-carregamento precisa carregar o conteúdo da posição inicial especificada e pela duração especificada (em milissegundos) no buffer na memória do player.
  • STAGE_SPECIFIED_RANGE_CACHED: o gerenciador de pré-carregamento precisa armazenar em cache o conteúdo da posição inicial especificada e pela duração especificada (em milissegundos) no cache em disco.
  • STAGE_TRACKS_SELECTED: o gerenciador de pré-carregamento precisa carregar e processar as informações da faixa de conteúdo e selecionar as faixas. O gerenciador de pré-carregamento ainda não deve começar a carregar o conteúdo.
  • STAGE_SOURCE_PREPARED: o gerenciador de pré-carregamento precisa preparar a origem do conteúdo. Por exemplo, se os metadados do conteúdo estiverem em um arquivo de manifesto separado, o gerenciador de pré-carregamento poderá buscar e analisar esse manifesto.
  • null: o gerenciador de pré-carregamento não deve carregar nenhum conteúdo ou metadado para esse item de mídia.

Você precisa ter uma estratégia para decidir quanto conteúdo carregar para cada item de mídia. Neste exemplo, mais conteúdo é carregado para os itens mais próximos do que está sendo reproduzido no momento. Se o usuário estiver reproduzindo conteúdo com o índice n, o controlador vai retornar os seguintes códigos:

  • Índice n+1 (o próximo item de mídia): carregue 3.000 ms (3 segundos) da posição inicial padrão.
  • Índice n-1 (o item de mídia anterior): carregue 1.000 ms (1 segundo) da posição inicial padrão.
  • Outros itens de mídia no intervalo n-2 a n+2: retorne PreloadStatus.TRACKS_SELECTED
  • Outros itens de mídia no intervalo n-4 a n+4: retorne PreloadStatus.SOURCE_PREPARED
  • Para todos os outros itens de mídia, retorne null.

class MyTargetPreloadStatusControl(var currentPlayingIndex: Int = 0) :
  TargetPreloadStatusControl<Int, DefaultPreloadManager.PreloadStatus> {

  override fun getTargetPreloadStatus(index: Int): DefaultPreloadManager.PreloadStatus {
    if (index - currentPlayingIndex == 1) { // next track
      // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
      // suggest loading 3000ms from the default start position
      return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
    } else if (index - currentPlayingIndex == -1) { // previous track
      // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
      // suggest loading 3000ms from the default start position
      return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
    } else if (abs(index - currentPlayingIndex) == 2) {
      // return a PreloadStatus that is labelled by STAGE_TRACKS_SELECTED
      return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_TRACKS_SELECTED
    } else if (abs(index - currentPlayingIndex) <= 4) {
      // return a PreloadStatus that is labelled by STAGE_SOURCE_PREPARED
      return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_SOURCE_PREPARED
    }
    return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_NOT_PRELOADED
  }
}

Pontos principais sobre o código

  • Você vai transmitir uma instância de MyTargetPreloadStatusControl para o builder do gerenciador de pré-carregamento ao criá-lo.
  • currentPlayingIndex contém o índice do item de mídia que está sendo reproduzido. É função do app manter esse valor atualizado.
  • Quando o gerenciador de pré-carregamento estiver pronto para carregar o conteúdo, ele vai chamar getTargetPreloadStatus e transmitir as informações de classificação que você especificou para o item de mídia correspondente. No caso de DefaultPreloadManager, essas informações de classificação são um número inteiro que especifica a posição do item em um carrossel. O método escolhe qual código retornar comparando esse índice com o índice do item selecionado no momento.

Criar o gerenciador de pré-carregamento

Para criar o gerenciador de pré-carregamento, você precisa de um DefaultPreloadManager.Builder. Esse builder é configurado com o contexto atual e o controle de status de pré-carregamento de destino do app. É possível criar um gerenciador de pré-carregamento com todas as configurações padrão.

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder = DefaultPreloadManager.Builder(context, targetPreloadStatusControl)
val preloadManager = preloadManagerBuilder.build()

O builder também fornece métodos setter que podem ser usados para definir os componentes personalizados do gerenciador de pré-carregamento.

Por exemplo, é possível personalizar o total de bytes de buffer de destino para todas as origens de mídia de pré-carregamento em DefaultPreloadManager, para que os dados pré-carregados não excedam esse limite. É possível configurar esse limite usando setPlayerTargetBufferBytes(String, int) em um DefaultLoadControl.Builder personalizado com o nome do player "preload" e transmitir essa instância para o builder do gerenciador de pré-carregamento:

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder = DefaultPreloadManager.Builder(context, targetPreloadStatusControl)

preloadManagerBuilder.setLoadControl(
  DefaultLoadControl.Builder()
    .setPlayerTargetBufferBytes("preload", 128 * 1024 * 1024) // 128 MiB
    .build()
)
val preloadManager = preloadManagerBuilder.build()

Embora os métodos setter do builder sejam basicamente opcionais para personalização, se você quiser armazenar em cache itens de mídia no disco, configure o builder com um Cache chamando setCache(). Se nenhum cache estiver configurado, a tentativa de armazenar os itens de mídia em cache vai resultar em um IllegalStateException.

Crie o ExoPlayer para reproduzir o item de mídia pré-carregado.

Além de usar o builder para criar o gerenciador de pré-carregamento, você também o usará para criar os objetos ExoPlayer que seu app usa para reproduzir o conteúdo, de modo que o ExoPlayer compartilhe corretamente os componentes com o gerenciador de pré-carregamento. Ainda é possível definir as configurações específicas de reprodução para o ExoPlayer transmitindo uma instância de ExoPlayer.Builder com essas configurações definidas.

// Direct creation
val exoPlayer = preloadManagerBuilder.buildExoPlayer()

// Creation with custom playback specific configurations
val skipSilenceExoPlayerBuilder = ExoPlayer.Builder(context).setSkipSilenceEnabled(true)
val skipSilenceExoPlayer = preloadManagerBuilder.buildExoPlayer(skipSilenceExoPlayerBuilder)