HLS

ExoPlayer supporta HLS con più formati contenitore. Devono essere supportati anche i formati audio e video di esempio contenuti (per maggiori dettagli, consulta la sezione Formati di esempio). Consigliamo vivamente ai produttori di contenuti HLS di generare stream HLS di alta qualità, come descritto in questo post del blog.

Funzionalità Supportato Commenti
Container
MPEG-TS
FMP4/CMAF
ADTS (AAC)
MP3
Sottotitoli codificati / sottotitoli
CEA-608
CEA-708
WebVTT
Metadati
ID3
SCTE-35 NO
Protezione dei contenuti
AES-128
Esempio di AES-128 NO
Widevine API 19+ (schema "cenc") e 25+ (schema "cbcs")
PlayReady SL2000 Solo Android TV
Controllo del server
Aggiornamenti delta
Blocco del ricaricamento della playlist
Blocco del caricamento dei suggerimenti di precaricamento Ad eccezione degli intervalli di byte con lunghezze non definite
Inserimento degli annunci
Inserimento di annunci guidato dal server (interstitial) In parte Solo VOD con X-ASSET-URI. I live streaming e X-ASSET-LIST verranno aggiunti in un secondo momento.
Annunci lato server e lato client IMA Guida all'inserimento degli annunci
Riproduzione live
Riproduzione live regolare
HLS a bassa latenza (Apple)
HLS a bassa latenza (community) NO
Common Media Client Data CMCD Guida all'integrazione di CMCD

Utilizzo di MediaItem

Per riprodurre uno stream HLS, devi utilizzare il modulo HLS.

Kotlin

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

Groovy

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

Puoi quindi creare un MediaItem per un URI di playlist HLS e passarlo al player.

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

Se l'URI non termina con .m3u8, puoi passare MimeTypes.APPLICATION_M3U8 a setMimeType di MediaItem.Builder per indicare esplicitamente il tipo di contenuto.

L'URI dell'elemento multimediale può puntare a una playlist multimediale o a una playlist multivariante. Se l'URI punta a una playlist multivariante che dichiara più tag #EXT-X-STREAM-INF, ExoPlayer si adatterà automaticamente tra le varianti, tenendo conto sia della larghezza di banda disponibile sia delle funzionalità del dispositivo.

Utilizzo di HlsMediaSource

Per ulteriori opzioni di personalizzazione, puoi creare un HlsMediaSource e passarlo direttamente al player anziché un 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();

Accedere al manifest

Puoi recuperare il manifest corrente chiamando Player.getCurrentManifest. Per HLS, devi eseguire il cast dell'oggetto restituito su HlsManifest. Il callback onTimelineChanged di Player.Listener viene chiamato anche ogni volta che viene caricato il manifest. Ciò avverrà una volta per i contenuti on demand e possibilmente molte volte per i contenuti live. Il seguente snippet di codice mostra come un'app può fare qualcosa ogni volta che viene caricato il manifest.

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

Riprodurre stream HLS con interstitial

La specifica HLS definisce gli interstitial HLS che possono essere utilizzati per includere informazioni sugli interstitial in una playlist multimediale. Per impostazione predefinita, ExoPlayer ignora questi interstiziali. Il supporto può essere aggiunto utilizzando HlsInterstitialsAdsLoader. Non supportiamo tutte le funzionalità della specifica fin dall'inizio. Se non trovi il supporto per il tuo stream, comunicacelo segnalando un problema su GitHub e inviandoci l'URI dello stream, in modo che possiamo aggiungere il supporto per il tuo stream.

Utilizzare un MediaItem con l'API playlist

Il modo più comodo per riprodurre stream HLS con interstitial è creare un'istanza ExoPlayer con un HlsInterstitialsAdsLoader.AdsMediaSourceFactory. Ciò consente di utilizzare l'API playlist basata su MediaItem dell'interfaccia Player per riprodurre gli interstitial HLS.

MediaSource.Factory di ExoPlayer può essere inserito nel builder durante la creazione dell'istanza del player:

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 una configurazione del lettore di questo tipo, la riproduzione degli interstitial HLS consiste semplicemente nell'impostazione di un elemento multimediale con un AdsConfiguration sul lettore:

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

Utilizzare l'API basata sull'origine media

In alternativa, l'istanza ExoPlayer può essere creata senza eseguire l'override della fabbrica di origini media predefinita. Per supportare gli interstitial, un'app può quindi utilizzare HlsInterstitialsAdsLoader.AdsMediaSourceFactory direttamente per creare un MediaSource e fornirlo a ExoPlayer utilizzando l'API playlist basata sull'origine media:

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

Ascolta gli eventi degli annunci

Un Listener può essere aggiunto a HlsInterstitialsAdsLoader per monitorare gli eventi relativi alle modifiche di stato riguardanti la riproduzione degli interstitial HLS. In questo modo, un'app o un SDK può monitorare gli annunci riprodotti, gli elenchi di asset caricati, le origini media degli annunci preparate o rilevare errori di caricamento dell'elenco di asset e di preparazione degli annunci. Inoltre, i metadati emessi dalle origini multimediali degli annunci possono essere ricevuti per la verifica della riproduzione degli annunci con granularità fine o per monitorare l'avanzamento della riproduzione degli annunci.

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 il JavaDoc di HlsInterstitialsAdsLoader.Listener per la documentazione dettagliata di tutti i callback disponibili.

Il listener può quindi essere aggiunto al caricatore di annunci:

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

HlsInterstitialsAdsLoader ciclo di vita

Un'istanza di HlsInterstitialsAdsLoader o HlsInterstitialsAdsLoader.AdsMediaSourceFactory può essere riutilizzata per più istanze del player che creano più origini media per le quali devono essere caricati gli annunci.

Un'istanza può essere creata, ad esempio, nel metodo onCreate di un Activity e poi riutilizzata per più istanze del giocatore. Funziona se viene utilizzato da una sola istanza del player alla volta. Ciò è utile per il caso d'uso comune in cui l'app viene portata in background, l'istanza del player viene eliminata e poi viene creata una nuova istanza quando l'app viene riportata in primo piano.

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

In generale, assicurati di rilasciare la vecchia istanza del player prima di impostare la successiva sul caricatore di annunci. Una volta rilasciato il caricatore di annunci, quest'ultimo non potrà più essere utilizzato.

Personalizzare la riproduzione

ExoPlayer offre diversi modi per personalizzare l'esperienza di riproduzione in base alle esigenze della tua app. Per esempi, consulta la pagina Personalizzazione.

Disattivazione della preparazione senza chunk

Per impostazione predefinita, ExoPlayer utilizzerà la preparazione senza chunk. Ciò significa che ExoPlayer utilizzerà solo le informazioni nella playlist multivariante per preparare lo stream, il che funziona se i tag #EXT-X-STREAM-INF contengono l'attributo CODECS.

Potresti dover disattivare questa funzionalità se i segmenti multimediali contengono tracce di sottotitoli codificati che non sono dichiarate nella playlist multivariante con un tag #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS. In caso contrario, queste tracce di sottotitoli codificati non verranno rilevate e riprodotte. Puoi disattivare la preparazione senza blocchi in HlsMediaSource.Factory come mostrato nello snippet seguente. Tieni presente che questo aumenterà il tempo di avvio poiché ExoPlayer deve scaricare un segmento multimediale per rilevare queste tracce aggiuntive ed è preferibile dichiarare le tracce di sottotitoli codificati nella 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));

Creare contenuti HLS di alta qualità

Per ottenere il massimo da ExoPlayer, puoi seguire alcune linee guida per migliorare i tuoi contenuti HLS. Per una spiegazione completa, leggi il nostro post di Medium sulla riproduzione HLS in ExoPlayer. I punti principali sono:

  • Utilizza durate dei segmenti precise.
  • Utilizza un flusso multimediale continuo; evita modifiche alla struttura dei contenuti multimediali tra i segmenti.
  • Utilizza il tag #EXT-X-INDEPENDENT-SEGMENTS.
  • Preferisci gli stream demuxati, anziché i file che includono sia video che audio.
  • Includi tutte le informazioni possibili nella playlist multivariante.

Le seguenti linee guida si applicano in modo specifico ai live streaming:

  • Utilizza il tag #EXT-X-PROGRAM-DATE-TIME.
  • Utilizza il tag #EXT-X-DISCONTINUITY-SEQUENCE.
  • Fornire una finestra live lunga. Un minuto o più è l'ideale.