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 | SÌ | |
FMP4/CMAF | SÌ | |
ADTS (AAC) | SÌ | |
MP3 | SÌ | |
Sottotitoli codificati / sottotitoli | ||
CEA-608 | SÌ | |
CEA-708 | SÌ | |
WebVTT | SÌ | |
Metadati | ||
ID3 | SÌ | |
SCTE-35 | NO | |
Protezione dei contenuti | ||
AES-128 | SÌ | |
Esempio AES-128 | NO | |
Widevine | SÌ | API 19+ ("cenc" scheme) e 25+ ("cbcs" scheme) |
PlayReady SL2000 | SÌ | Solo Android TV |
Controllo del server | ||
Aggiornamenti delta | SÌ | |
Blocco del ricaricamento della playlist | SÌ | |
Blocco del caricamento degli indizi di precaricamento | SÌ | 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 | SÌ | Guida all'inserimento degli annunci |
Riproduzione in tempo reale | ||
Riproduzione live normale | SÌ | |
HLS a bassa latenza (Apple) | SÌ | |
HLS a bassa latenza (community) | NO | |
Common Media Client Data CMCD | SÌ | 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.