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 | 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 di AES-128 | NO | |
Widevine | SÌ | API 19+ (schema "cenc") e 25+ (schema "cbcs") |
PlayReady SL2000 | SÌ | Solo Android TV |
Controllo del server | ||
Aggiornamenti delta | SÌ | |
Blocco del ricaricamento della playlist | SÌ | |
Blocco del caricamento dei suggerimenti di precaricamento | SÌ | 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 | SÌ | Guida all'inserimento degli annunci |
Riproduzione live | ||
Riproduzione live regolare | SÌ | |
HLS a bassa latenza (Apple) | SÌ | |
HLS a bassa latenza (community) | NO | |
Common Media Client Data CMCD | SÌ | 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.