HLS

ExoPlayer supporta HLS con più formati di contenitore. Devono essere supportati anche i formati dei sample audio e video contenuti (per maggiori dettagli, consulta la sezione Formati dei sample). 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 AES-128 NO
Widevine API 19+ ("cenc" scheme) e 25+ ("cbcs" scheme)
PlayReady SL2000 Solo Android TV
Controllo del server
Aggiornamenti delta
Blocco del ricaricamento della playlist
Blocco del caricamento degli indizi di precaricamento Ad eccezione degli intervalli di byte con lunghezze non definite
Inserimento degli annunci
Inserzione di annunci guidata dal server (annunci interstitial) In parte Solo VOD con X-ASSET-URI. I live streaming e X-ASSET-LIST verranno aggiunti in un secondo momento.
Annunci IMA lato server e lato client Guida all'inserimento degli annunci
Riproduzione in tempo reale
Riproduzione live normale
HLS a bassa latenza (Apple)
HLS a bassa latenza (community) NO
Common Media Client Data CMCD Guida all'integrazione di CCMD

Utilizzo di MediaItem

Per riprodurre uno stream HLS, devi fare affidamento sul modulo HLS.

Kotlin

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

Groovy

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

Puoi quindi creare un MediaItem per un URI di playlist HLS e passarlo al media 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ò fare riferimento a una playlist multimediale o a una playlist con più varianti. Se l'URI rimanda 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 altre 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();

Accesso al manifest

Puoi recuperare il manifest corrente chiamando Player.getCurrentManifest. Per HLS, devi eseguire il casting dell'oggetto restituito in HlsManifest. Il callback onTimelineChanged di Player.Listener viene chiamato anche ogni volta che viene caricato il manifest. Questo accade una volta per i contenuti on-demand e possibly molte volte per i contenuti dal vivo. Il seguente snippet di codice mostra come un'app può eseguire un'azione 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 gli interstitial

La specifica HLS definisce gli annunci interstitial HLS che possono essere utilizzati per includere informazioni sugli interstitial in una playlist multimediale. Per impostazione predefinita, ExoPlayer ignora questi annunci interstitial. L'assistenza può essere aggiunta utilizzando HlsInterstitialsAdsLoader. Non supportiamo tutte le funzionalità della specifica fin dall'inizio. Se non è supportato il tuo stream, comunicacelo segnalando un problema su GitHub e inviaci l'URI dello stream in modo da poter aggiungere il supporto.

Utilizzare un MediaItem con l'API playlist

Il modo più pratico per riprodurre stream HLS con annunci intermedi è creare un'istanza ExoPlayer con un HlsInterstitialsAdsLoader.AdsMediaSourceFactory. In questo modo, puoi utilizzare l'API playlist basata su MediaItem dell'interfaccia Player per riprodurre gli interstitial HLS.

Il 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 questa configurazione del player, la riproduzione degli interstitial HLS consiste semplicemente nell'impostare un elemento multimediale con un AdsConfiguration sul player:

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 sulle sorgenti multimediali

In alternativa, l'istanza ExoPlayer può essere compilata senza eseguire l'override della factory di origini multimediali predefinite. Per supportare gli interstitial, un'app può quindi utilizzare HlsInterstitialsAdsLoader.AdsMediaSourceFactory direttamente per creare unMediaSource e fornirlo a ExoPlayer utilizzando l'API MediaSourceBasedPlaylist:

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 correlati agli annunci

A Listener è possibile aggiungere un HlsInterstitialsAdsLoader per monitorare gli eventi relativi alle modifiche dello stato relative alla riproduzione degli interstitial HLS. In questo modo, un'app o un SDK può monitorare gli annunci riprodotti, i listini di asset caricati, le origini media degli annunci in fase di preparazione o rilevare errori di caricamento dei listini di asset e di preparazione degli annunci. Inoltre, i metadati emessi dalle origini media degli annunci possono essere ricevuti per la verifica accurata della riproduzione dell'annuncio o per monitorare l'avanzamento della riproduzione dell'annuncio.

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

L'ascoltatore può quindi essere aggiunto al caricatore degli 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 di 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 di player. Questo funziona a condizione che sia in uso contemporaneamente da una singola istanza del player. Questo è utile per il caso d'uso comune quando l'app viene spostata in background, l'istanza del player viene distrutta e viene creata una nuova istanza quando l'app viene nuovamente messa 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 genere, assicurati di rilasciare l'istanza del vecchio player prima di impostare l'istanza del prossimo player nel caricatore di annunci. Una volta rilasciato, il caricatore di annunci non può 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 multivariata 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 codificate con sottotitoli codificati che non sono dichiarate nella playlist multivariata con un tag #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS. In caso contrario, questi canali con sottotitoli codificati non verranno rilevati e riprodotti. Puoi disattivare la preparazione senza chunk in HlsMediaSource.Factory come mostrato nello snippet seguente. Tieni presente che questo incrementerà il tempo di avvio poiché ExoPlayer deve scaricare un segmento multimediale per scoprire queste tracce aggiuntive ed è preferibile dichiarare le tracce con sottotitoli codificati nella playlist multivariata.

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, esistono alcune linee guida che puoi seguire 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 uno stream multimediale continuo ed evita modifiche alla struttura dei contenuti multimediali nei vari segmenti.
  • Utilizza il tag #EXT-X-INDEPENDENT-SEGMENTS.
  • Preferisci gli stream demuxed rispetto ai file che includono sia video che audio.
  • Includi tutte le informazioni possibili nella playlist multivariante.

Le seguenti linee guida si applicano specificamente ai live streaming:

  • Utilizza il tag #EXT-X-PROGRAM-DATE-TIME.
  • Utilizza il tag #EXT-X-DISCONTINUITY-SEQUENCE.
  • Fornisci una finestra live lunga. Uno o più minuti sono perfetti.