HLS

ExoPlayer unterstützt HLS mit mehreren Containerformaten. Die enthaltenen Audio- und Videobeispielformate müssen ebenfalls unterstützt werden (siehe den Abschnitt Beispielformate). Wir empfehlen HLS-Content-Produzenten dringend, HLS-Streams in hoher Qualität zu generieren, wie in diesem Blogpost beschrieben.

Funktion Unterstützt Kommentare
Container
MPEG-TS JA
FMP4/CMAF JA
ADTS (AAC) JA
MP3 JA
Untertitel
CEA-608 JA
CEA-708 JA
WebVTT JA
Metadaten
ID3 JA
SCTE-35 NEIN
Inhaltsschutz
AES‑128 JA
Sample AES‑128 NEIN
Widevine JA API 19+ („cenc“-Schema) und 25+ („cbcs“-Schema)
PlayReady SL2000 JA Nur Android TV
Serversteuerung
Delta-Updates JA
Neuladen von Playlists blockieren JA
Laden von Preload-Hinweisen blockieren JA Außer für Bytbereiche mit undefinierten Längen
Anzeigenbereitstellung
Servergesteuerte Anzeigenbereitstellung (Interstitials) Teilweise Nur VOD mit X-ASSET-URI. Livestreams und X-ASSET-LIST werden später hinzugefügt.
Serverseitige und clientseitige IMA-Anzeigen JA Leitfaden für die Anzeigenbereitstellung
Live-Wiedergabe
Regelmäßige Live-Wiedergabe JA
HLS mit niedriger Latenz (Apple) JA
HLS mit niedriger Latenz (Community) NEIN
Common Media Client Data CMCD JA CMCD-Integrationsleitfaden

MediaItem verwenden

Wenn Sie einen HLS-Stream abspielen möchten, müssen Sie das HLS-Modul verwenden.

Kotlin

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

Groovy

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

Anschließend können Sie ein MediaItem für einen HLS-Playlist-URI erstellen und an den Player übergeben.

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

Wenn Ihr URI nicht mit .m3u8 endet, können Sie MimeTypes.APPLICATION_M3U8 an setMimeType von MediaItem.Builder übergeben, um den Typ des Inhalts explizit anzugeben.

Der URI des Media-Elements kann entweder auf eine Media-Playlist oder eine Playlist mit mehreren Varianten verweisen. Wenn der URI auf eine Playlist mit mehreren Varianten verweist, in der mehrere #EXT-X-STREAM-INF-Tags deklariert sind, passt ExoPlayer die Varianten automatisch an, wobei sowohl die verfügbare Bandbreite als auch die Gerätefunktionen berücksichtigt werden.

HlsMediaSource verwenden

Wenn Sie mehr Anpassungsoptionen benötigen, können Sie ein HlsMediaSource erstellen und es direkt an den Player übergeben, anstatt ein 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();

Auf das Manifest zugreifen

Sie können das aktuelle Manifest durch Aufrufen von Player.getCurrentManifest abrufen. Bei HLS sollten Sie das zurückgegebene Objekt in HlsManifest umwandeln. Der onTimelineChanged-Callback von Player.Listener wird auch immer dann aufgerufen, wenn das Manifest geladen wird. Das passiert einmal bei On-Demand-Inhalten und möglicherweise mehrmals bei Liveinhalten. Das folgende Code-Snippet zeigt, wie eine App etwas ausführen kann, wenn das Manifest geladen wird.

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

HLS-Streams mit Interstitials abspielen

In der HLS-Spezifikation werden HLS-Interstitials definiert, mit denen Interstitial-Informationen in eine Medienplaylist aufgenommen werden können. ExoPlayer ignoriert diese Interstitials standardmäßig. Die Unterstützung kann mit HlsInterstitialsAdsLoader hinzugefügt werden. Wir unterstützen nicht alle Funktionen der Spezifikation von Anfang an. Wenn du Unterstützung für deinen Stream vermisst, melde uns das bitte auf GitHub und sende uns die Stream-URI, damit wir Unterstützung für deinen Stream hinzufügen können.

MediaItem mit der Playlist API verwenden

Die einfachste Möglichkeit, HLS-Streams mit Interstitials abzuspielen, ist das Erstellen einer ExoPlayer-Instanz mit einem HlsInterstitialsAdsLoader.AdsMediaSourceFactory. Dadurch kann die MediaItem-basierte Playlist API der Player-Schnittstelle zum Abspielen von HLS-Interstitials verwendet werden.

Die MediaSource.Factory von ExoPlayer kann beim Erstellen der Player-Instanz in den Builder eingefügt werden:

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

Bei einer solchen Player-Einrichtung müssen Sie zum Abspielen von HLS-Interstitials nur ein Media-Element mit einem AdsConfiguration im Player festlegen:

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

API für Media-Quellen verwenden

Alternativ kann die ExoPlayer-Instanz erstellt werden, ohne die Standard-Media-Source-Factory zu überschreiben. Um Interstitials zu unterstützen, kann eine App dann HlsInterstitialsAdsLoader.AdsMediaSourceFactory direkt verwenden, um ein MediaSource zu erstellen und es ExoPlayer über die auf der Media-Quelle basierende Playlist-API bereitzustellen:

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

Auf Anzeigenereignisse warten

Listener kann zu HlsInterstitialsAdsLoader hinzugefügt werden, um Ereignisse im Zusammenhang mit Statusänderungen bei der HLS-Interstitial-Wiedergabe zu überwachen. So kann eine App oder ein SDK nachverfolgen, welche Anzeigen ausgeliefert werden, welche Asset-Listen geladen werden, welche Anzeigen-Media-Quellen vorbereitet werden, und Fehler beim Laden von Asset-Listen und bei der Vorbereitung von Anzeigen erkennen. Außerdem können Metadaten, die von Anzeigenmedienquellen ausgegeben werden, für die detaillierte Überprüfung der Anzeigenwiedergabe oder zur Verfolgung des Fortschritts der Anzeigenwiedergabe empfangen werden.

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

In der JavaDoc von HlsInterstitialsAdsLoader.Listener finden Sie eine detaillierte Dokumentation aller verfügbaren Callbacks.

Der Listener kann dann dem Anzeigen-Loader hinzugefügt werden:

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 Lebenszyklus

Eine Instanz von HlsInterstitialsAdsLoader oder HlsInterstitialsAdsLoader.AdsMediaSourceFactory kann für mehrere Player-Instanzen wiederverwendet werden, die mehrere Media-Quellen erstellen, für die Anzeigen geladen werden müssen.

Eine Instanz kann beispielsweise in der onCreate-Methode eines Activity erstellt und dann für mehrere Player-Instanzen wiederverwendet werden. Das funktioniert, solange es nur von einer Player-Instanz gleichzeitig verwendet wird. Dies ist nützlich für den häufigen Anwendungsfall, wenn die App in den Hintergrund verschoben wird, die Player-Instanz zerstört wird und dann eine neue Instanz erstellt wird, wenn die App wieder in den Vordergrund geholt wird.

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

Im Allgemeinen sollten Sie die alte Player-Instanz freigeben, bevor Sie die nächste Player-Instanz für den Anzeigenladevorgang festlegen. Sobald der Ads Loader selbst freigegeben wurde, kann er nicht mehr verwendet werden.

Wiedergabe anpassen

ExoPlayer bietet mehrere Möglichkeiten, die Wiedergabe an die Anforderungen Ihrer App anzupassen. Beispiele finden Sie auf der Seite zur Anpassung.

Chunkless-Vorbereitung deaktivieren

Standardmäßig verwendet ExoPlayer die chunklose Vorbereitung. Das bedeutet, dass ExoPlayer nur die Informationen in der multivarianten Playlist verwendet, um den Stream vorzubereiten. Das funktioniert, wenn die #EXT-X-STREAM-INF-Tags das Attribut CODECS enthalten.

Möglicherweise müssen Sie diese Funktion deaktivieren, wenn Ihre Media-Segmente gemischte Untertitel-Tracks enthalten, die in der Playlist mit mehreren Varianten nicht mit einem #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS-Tag deklariert sind. Andernfalls werden diese Untertitel-Tracks nicht erkannt und wiedergegeben. Sie können die chunklose Vorbereitung in HlsMediaSource.Factory deaktivieren, wie im folgenden Snippet gezeigt. Dadurch verlängert sich die Startzeit, da ExoPlayer ein Media-Segment herunterladen muss, um diese zusätzlichen Tracks zu erkennen. Es ist daher besser, die Untertitel-Tracks in der Multivariant-Playlist zu deklarieren.

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

Hochwertige HLS-Inhalte erstellen

Damit Sie ExoPlayer optimal nutzen können, gibt es bestimmte Richtlinien, die Sie befolgen können, um Ihre HLS-Inhalte zu verbessern. Eine ausführliche Erläuterung finden Sie in unserem Medium-Beitrag zur HLS-Wiedergabe in ExoPlayer. Die wichtigsten Punkte sind:

  • Genaue Segmentdauern verwenden
  • Verwenden Sie einen kontinuierlichen Media-Stream und vermeiden Sie Änderungen an der Media-Struktur über Segmente hinweg.
  • Verwenden Sie das Tag #EXT-X-INDEPENDENT-SEGMENTS.
  • Bevorzugen Sie demultiplexte Streams gegenüber Dateien, die sowohl Video als auch Audio enthalten.
  • Nehmen Sie alle Informationen, die Sie haben, in die Playlist mit mehreren Varianten auf.

Die folgenden Richtlinien gelten speziell für Livestreams:

  • Verwenden Sie das Tag #EXT-X-PROGRAM-DATE-TIME.
  • Verwenden Sie das Tag #EXT-X-DISCONTINUITY-SEQUENCE.
  • Bieten Sie ein langes Live-Zeitfenster an. Eine Minute oder länger ist ideal.