HLS

ExoPlayer admite HLS con varios formatos de contenedor. También se deben admitir los formatos de muestras de audio y video incluidos (consulta la sección de formatos de muestras para obtener más detalles). Recomendamos a los productores de contenido de HLS que generen transmisiones de HLS de alta calidad, como se describe en esta entrada de blog.

Función Compatible Comentarios
Contenedores
MPEG-TS
FMP4/CMAF
ADTS (AAC)
MP3
Subtítulos
CEA-608
CEA-708
WebVTT
Metadatos
ID3
SCTE-35 NO
Protección de contenido
AES-128
Muestra de AES-128 NO
Widevine API 19+ (esquema "cenc") y 25+ (esquema "cbcs")
PlayReady SL2000 Únicamente para Android TV
Control del servidor
Actualizaciones delta
Se bloqueó la recarga de la playlist
Bloquea la carga de las sugerencias de precarga Excepto para los rangos de bytes con longitudes indefinidas
Inserción de anuncios
Inserción de anuncios guiada por el servidor (anuncios intersticiales) Parcialmente Solo VOD con X-ASSET-URI. Las transmisiones en vivo y X-ASSET-LIST se agregarán más adelante.
Anuncios de IMA del servidor y del cliente Guía de inserción de anuncios
Reproducción en vivo
Reproducción en vivo normal
HLS de baja latencia (Apple)
HLS de baja latencia (comunidad) NO
Common Media Client Data CMCD Guía de integración de CMCD

Cómo usar MediaItem

Para reproducir una transmisión HLS, debes depender del módulo HLS.

Kotlin

implementation("androidx.media3:media3-exoplayer-hls:1.7.1")

Groovy

implementation "androidx.media3:media3-exoplayer-hls:1.7.1"

Luego, puedes crear un objeto MediaItem para un URI de playlist HLS y pasarlo al reproductor.

Kotlin

// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri(hlsUri))
// Prepare the player.
player.prepare()

Java

// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri(hlsUri));
// Prepare the player.
player.prepare();

Si tu URI no termina con .m3u8, puedes pasar MimeTypes.APPLICATION_M3U8 a setMimeType de MediaItem.Builder para indicar de forma explícita el tipo de contenido.

El URI del elemento multimedia puede apuntar a una playlist de medios o a una playlist multivariante. Si el URI apunta a una playlist multivariante que declara varias etiquetas #EXT-X-STREAM-INF, ExoPlayer se adaptará automáticamente entre las variantes, teniendo en cuenta el ancho de banda disponible y las capacidades del dispositivo.

Cómo usar HlsMediaSource

Para obtener más opciones de personalización, puedes crear un objeto HlsMediaSource y pasarlo directamente al reproductor en lugar de un objeto MediaItem.

Kotlin

// Create a data source factory.
val dataSourceFactory: DataSource.Factory = DefaultHttpDataSource.Factory()
// Create a HLS media source pointing to a playlist uri.
val hlsMediaSource =
  HlsMediaSource.Factory(dataSourceFactory).createMediaSource(MediaItem.fromUri(hlsUri))
// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the HLS media source as the playlist with a single media item.
player.setMediaSource(hlsMediaSource)
// Prepare the player.
player.prepare()

Java

// Create a data source factory.
DataSource.Factory dataSourceFactory = new DefaultHttpDataSource.Factory();
// Create a HLS media source pointing to a playlist uri.
HlsMediaSource hlsMediaSource =
    new HlsMediaSource.Factory(dataSourceFactory).createMediaSource(MediaItem.fromUri(hlsUri));
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the HLS media source as the playlist with a single media item.
player.setMediaSource(hlsMediaSource);
// Prepare the player.
player.prepare();

Cómo acceder al manifiesto

Puedes recuperar el manifiesto actual llamando a Player.getCurrentManifest. En el caso de HLS, debes convertir el objeto que se muestra en HlsManifest. La devolución de llamada onTimelineChanged de Player.Listener también se llama cada vez que se carga el manifiesto. Esto sucederá una vez para el contenido a pedido y, posiblemente, muchas veces para el contenido en vivo. En el siguiente fragmento de código, se muestra cómo una app puede hacer algo cada vez que se carga el manifiesto.

Kotlin

player.addListener(
  object : Player.Listener {
    override fun onTimelineChanged(timeline: Timeline, @TimelineChangeReason reason: Int) {
      val manifest = player.currentManifest
      if (manifest is HlsManifest) {
        // Do something with the manifest.
      }
    }
  }
)

Java

player.addListener(
    new Player.Listener() {
      @Override
      public void onTimelineChanged(
          Timeline timeline, @Player.TimelineChangeReason int reason) {
        Object manifest = player.getCurrentManifest();
        if (manifest != null) {
          HlsManifest hlsManifest = (HlsManifest) manifest;
          // Do something with the manifest.
        }
      }
    });

Reproduce transmisiones de HLS con anuncios intersticiales

La especificación de HLS define los intersticiales de HLS que se pueden usar para incluir información de intersticiales en una playlist multimedia. De forma predeterminada, ExoPlayer ignora estos anuncios intersticiales. Puedes agregar compatibilidad con HlsInterstitialsAdsLoader. No admitimos todas las funciones de la especificación desde el principio. Si no encuentras compatibilidad con tu transmisión, informa el problema en GitHub y envíanos el URI de la transmisión para que podamos agregar compatibilidad.

Usa un MediaItem con la API de Playlist

La forma más conveniente de reproducir transmisiones HLS con anuncios intercalados es compilar una instancia de ExoPlayer con un HlsInterstitialsAdsLoader.AdsMediaSourceFactory. Esto permite usar la API de playlist basada en MediaItem de la interfaz de Player para reproducir anuncios intersticiales HLS.

El MediaSource.Factory de ExoPlayer se puede insertar en el compilador cuando se compila la instancia del reproductor:

Kotlin

hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context)
// Create a MediaSource.Factory for HLS streams with interstitials.
var hlsMediaSourceFactory =
  HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
    hlsInterstitialsAdsLoader,
    playerView,
    DefaultMediaSourceFactory(context),
  )

// Build player with interstitials media source factory
player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(hlsMediaSourceFactory)
    .build()

// Set the player on the ads loader.
hlsInterstitialsAdsLoader.setPlayer(player)
playerView.setPlayer(player)

Java

hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Create a MediaSource.Factory for HLS streams with interstitials.
MediaSource.Factory hlsMediaSourceFactory =
      new HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
          hlsInterstitialsAdsLoader, playerView, new DefaultMediaSourceFactory(context));

// Build player with interstitials media source factory
player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(hlsMediaSourceFactory)
        .build();

// Set the player on the ads loader.
hlsInterstitialsAdsLoader.setPlayer(player);
playerView.setPlayer(player);

Con esta configuración del reproductor, reproducir anuncios intersticiales de HLS solo requiere establecer un elemento multimedia con un AdsConfiguration en el reproductor:

Kotlin

player.setMediaItem(
  MediaItem.Builder()
    .setUri("https://www.example.com/media.m3u8")
    .setAdsConfiguration(
      AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
        .setAdsId("ad-tag-0") // must be unique within playlist
        .build())
    .build())

player.prepare();
player.play();

Java

player.setMediaItem(
    new MediaItem.Builder()
        .setUri("https://www.example.com/media.m3u8")
        .setAdsConfiguration(
            new AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
                .setAdsId("ad-tag-0") // must be unique within playlist
                .build())
        .build());
player.prepare();
player.play();

Usa la API basada en la fuente de medios

Como alternativa, la instancia de ExoPlayer se puede compilar sin anular el factor de fuentes de medios predeterminado. Para admitir anuncios intersticiales, una app puede usar HlsInterstitialsAdsLoader.AdsMediaSourceFactory directamente para crear un MediaSource y proporcionarlo a ExoPlayer con la API de playlist basada en la fuente de medios:

Kotlin

hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context)
// Create a MediaSource.Factory for HLS streams with interstitials.
var hlsMediaSourceFactory =
  HlsInterstitialsAdsLoader.AdsMediaSourceFactory(hlsInterstitialsAdsLoader, playerView, context)

// Build player with default media source factory.
player = new ExoPlayer.Builder(context).build();

// Create an media source from an HLS media item with ads configuration.
val mediaSource =
  hlsMediaSourceFactory.createMediaSource(
    MediaItem.Builder()
      .setUri("https://www.example.com/media.m3u8")
      .setAdsConfiguration(
        MediaItem.AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
          .setAdsId("ad-tag-0")
          .build()
      )
      .build()
  )

// Set the media source on the player.
player.setMediaSource(mediaSource)
player.prepare()
player.play()

Java

HlsInterstitialsAdsLoader hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Create a MediaSource.Factory for HLS streams with interstitials.
MediaSource.Factory hlsMediaSourceFactory =
    new HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
      hlsInterstitialsAdsLoader, playerView, context);

// Build player with default media source factory.
player = new ExoPlayer.Builder(context).build();

// Create an media source from an HLS media item with ads configuration.
MediaSource mediaSource =
    hlsMediaSourceFactory.createMediaSource(
      new MediaItem.Builder()
        .setUri("https://www.example.com/media.m3u8")
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
                .setAdsId("ad-tag-0")
                .build())
        .build());

// Set the media source on the player.
exoPlayer.setMediaSource(mediaSource);
exoPlayer.prepare();
exoPlayer.play();

Cómo detectar eventos de anuncios

Se puede agregar un Listener a HlsInterstitialsAdsLoader para supervisar eventos relacionados con los cambios de estado de la reproducción de anuncios intersticiales de HLS. Esto permite que una app o un SDK hagan un seguimiento de los anuncios que se publicaron, las listas de recursos que se cargaron, las fuentes de medios de anuncios que se prepararon o detecten errores de carga de listas de recursos y de preparación de anuncios. Además, se pueden recibir metadatos emitidos por las fuentes de medios de anuncios para realizar una verificación detallada de la reproducción de anuncios o para hacer un seguimiento del progreso de la reproducción de anuncios.

Kotlin

class AdsLoaderListener : HlsInterstitialsAdsLoader.Listener {

  override fun onStart(mediaItem: MediaItem, adsId: Any, adViewProvider: AdViewProvider) {
    // Do something when HLS media item with interstitials is started.
  }

  override fun onMetadata(
    mediaItem: MediaItem,
    adsId: Any,
    adGroupIndex: Int,
    adIndexInAdGroup: Int,
    metadata: Metadata,
  ) {
    // Do something with metadata that is emitted by the ad media source of the given ad.
  }

  override fun onAdCompleted(
    mediaItem: MediaItem,
    adsId: Any,
    adGroupIndex: Int,
    adIndexInAdGroup: Int,
  ) {
    // Do something when ad completed playback.
  }

  // ... See JavaDoc for further callbacks of HlsInterstitialsAdsLoader.Listener.

  override fun onStop(mediaItem: MediaItem, adsId: Any, adPlaybackState: AdPlaybackState) {
    // Do something with the resulting ad playback state when stopped.
  }
}

Java

private class AdsLoaderListener
    implements HlsInterstitialsAdsLoader.Listener {

  // implement HlsInterstitialsAdsLoader.Listener

  @Override
  public void onStart(MediaItem mediaItem, Object adsId, AdViewProvider adViewProvider) {
    // Do something when HLS media item with interstitials is started.
  }

  @Override
  public void onMetadata(
      MediaItem mediaItem,
      Object adsId,
      int adGroupIndex,
      int adIndexInAdGroup,
      Metadata metadata) {
    // Do something with metadata that is emitted by the ad media source of the given ad.
  }

  @Override
  public void onAdCompleted(
      MediaItem mediaItem, Object adsId, int adGroupIndex, int adIndexInAdGroup) {
    // Do something when ad completed playback.
  }

  // ... See JavaDoc for further callbacks

  @Override
  public void onStop(MediaItem mediaItem, Object adsId, AdPlaybackState adPlaybackState) {
    // Do something with the resulting ad playback state when stopped.
  }
}

Consulta el JavaDoc de HlsInterstitialsAdsLoader.Listener para obtener la documentación detallada de todas las devoluciones de llamada disponibles.

Luego, se puede agregar el objeto de escucha al cargador de anuncios:

Kotlin

var listener  = AdsLoaderListener();
// Add the listener to the ads loader to receive ad loader events.
hlsInterstitialsAdsLoader.addListener(listener);

Java

AdsLoaderListener listener = new AdsLoaderListener();
// Add the listener to the ads loader to receive ad loader events.
hlsInterstitialsAdsLoader.addListener(listener);

Ciclo de vida de HlsInterstitialsAdsLoader

Se puede reutilizar una instancia de HlsInterstitialsAdsLoader o HlsInterstitialsAdsLoader.AdsMediaSourceFactory para varias instancias del reproductor que crean varias fuentes de medios para las que se deben cargar anuncios.

Por ejemplo, se puede crear una instancia en el método onCreate de un Activity y, luego, volver a usarla para varias instancias de jugador. Esto funciona siempre y cuando una sola instancia de jugador lo esté usando al mismo tiempo. Esto es útil para el caso de uso común en el que la app pasa a segundo plano, se destruye la instancia del reproductor y, luego, se crea una nueva instancia cuando la app vuelve a primer plano.

Kotlin

// Create the ads loader instance (for example onCreate).
hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context);

// Build a player and set it on the ads loader (for example onStart).
player = ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Build another player and set it on the ads loader (for example onStart).
player = ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Release the ads loader when not used anymore  (for example onDestroy).
hlsInterstitialsAdsLoader.release();

Java

// Create the ads loader instance (for example onCreate).
hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);

// Build a player and set it on the ads loader (for example onStart).
player = new ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Build another player and set it on the ads loader (for example onStart).
player = new ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);

// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);

// Release the ads loader when not used anymore  (for example onDestroy).
hlsInterstitialsAdsLoader.release();

En general, asegúrate de liberar la instancia del reproductor anterior antes de configurar la siguiente instancia del reproductor en el cargador de anuncios. Una vez que se libera el cargador de anuncios, ya no se puede usar.

Cómo personalizar la reproducción

ExoPlayer te ofrece varias formas de personalizar la experiencia de reproducción según las necesidades de tu app. Consulta la página de personalización para ver ejemplos.

Cómo inhabilitar la preparación sin fragmentos

De forma predeterminada, ExoPlayer usará la preparación sin fragmentos. Esto significa que ExoPlayer solo usará la información de la playlist multivariante para preparar la transmisión, lo que funciona si las etiquetas #EXT-X-STREAM-INF contienen el atributo CODECS.

Es posible que debas inhabilitar esta función si tus segmentos de medios contienen pistas de subtítulos codificados multiplexados que no se declaran en la playlist multivariante con una etiqueta #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS. De lo contrario, no se detectarán ni reproducirán estos segmentos de subtítulos. Puedes inhabilitar la preparación sin fragmentos en HlsMediaSource.Factory, como se muestra en el siguiente fragmento. Ten en cuenta que esto aumentará el tiempo de inicio, ya que ExoPlayer necesita descargar un segmento de medios para descubrir estos segmentos adicionales, y es preferible declarar los segmentos de subtítulos en la playlist multivariante.

Kotlin

val hlsMediaSource =
  HlsMediaSource.Factory(dataSourceFactory)
    .setAllowChunklessPreparation(false)
    .createMediaSource(MediaItem.fromUri(hlsUri))

Java

HlsMediaSource hlsMediaSource =
    new HlsMediaSource.Factory(dataSourceFactory)
        .setAllowChunklessPreparation(false)
        .createMediaSource(MediaItem.fromUri(hlsUri));

Cómo crear contenido HLS de alta calidad

Para aprovechar al máximo ExoPlayer, puedes seguir ciertos lineamientos para mejorar tu contenido de HLS. Lee nuestra entrada de Medium sobre la reproducción de HLS en ExoPlayer para obtener una explicación completa. Los puntos principales son los siguientes:

  • Usa duraciones de segmentos precisas.
  • Usa un flujo de medios continuo y evita cambios en la estructura de los medios entre los segmentos.
  • Usa la etiqueta #EXT-X-INDEPENDENT-SEGMENTS.
  • Prefiere los flujos demuxados en lugar de los archivos que incluyen video y audio.
  • Incluye toda la información que puedas en la playlist multivariante.

Los siguientes lineamientos se aplican específicamente a las transmisiones en vivo:

  • Usa la etiqueta #EXT-X-PROGRAM-DATE-TIME.
  • Usa la etiqueta #EXT-X-DISCONTINUITY-SEQUENCE.
  • Proporciona una ventana de transmisión en vivo prolongada. Un minuto o más es excelente.