ExoPlayer תומך ב-HLS עם כמה פורמטים של קונטיינרים. בנוסף, צריכה להיות תמיכה בפורמטים של קטעי האודיו והווידאו שכלולים במודעה (פרטים מופיעים בקטע פורמטים של קטעי טעימות). אנחנו ממליצים מאוד ליוצרים של תוכן HLS ליצור שידורי HLS באיכות גבוהה, כפי שמתואר בפוסט הזה בבלוג.
תכונה | נתמך | תגובות |
---|---|---|
קונטיינרים | ||
MPEG-TS | כן | |
FMP4/CMAF | כן | |
ADTS (AAC) | כן | |
MP3 | כן | |
כתוביות סגורות / כתוביות | ||
CEA-608 | כן | |
CEA-708 | כן | |
WebVTT | כן | |
מטא-נתונים | ||
ID3 | כן | |
SCTE-35 | לא | |
הגנה על תוכן | ||
AES-128 | כן | |
דוגמה ל-AES-128 | לא | |
Widevine | כן | API מגרסה 19 ואילך (סכימת 'cenc') ומגרסה 25 ואילך (סכימת 'cbcs') |
PlayReady SL2000 | כן | Android TV בלבד |
שליטה בשרת | ||
עדכוני Delta | כן | |
חסימה של טעינת מחדש של פלייליסט | כן | |
חסימה של טעינת רמזים לטעינה מראש | כן | מלבד טווחי בייטים עם אורך לא מוגדר |
הוספת מודעות | ||
הטמעת מודעות מבוקרת על ידי שרת (מודעות מעברון) | באופן חלקי | רק VOD עם X-ASSET-URI .
שידורים חיים וX-ASSET-LIST יתווספו בהמשך. |
מודעות IMA בצד השרת ובצד הלקוח | כן | מדריך להוספת מודעות |
הפעלה בשידור חי | ||
הפעלה רגילה בשידור חי | כן | |
HLS עם זמן אחזור קצר (Apple) | כן | |
HLS בזמן אחזור קצר (קהילתי) | לא | |
Common Media Client Data CMCD | כן | מדריך להטמעת CMCD |
שימוש ב-MediaItem
כדי להפעיל שידור בפרוטוקול HLS, צריך להסתמך על מודול HLS.
Kotlin
implementation("androidx.media3:media3-exoplayer-hls:1.6.0")
Groovy
implementation "androidx.media3:media3-exoplayer-hls:1.6.0"
לאחר מכן תוכלו ליצור MediaItem
עבור URI של פלייליסט HLS ולהעביר אותו לנגן.
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();
אם כתובת ה-URI לא מסתיימת ב-.m3u8
, אפשר להעביר את MimeTypes.APPLICATION_M3U8
אל setMimeType
של MediaItem.Builder
כדי לציין במפורש את סוג התוכן.
ה-URI של פריט המדיה עשוי להפנות לפלייליסט מדיה או לפלייליסט עם וריאנטים מרובים. אם ה-URI מפנה לפלייליסט עם כמה וריאנטים שמוצהרים בו כמה תגי #EXT-X-STREAM-INF
, המערכת של ExoPlayer תתאים את עצמה באופן אוטומטי בין הווריאנטים, תוך התחשבות ברוחב הפס הזמין וביכולות המכשיר.
שימוש ב-HlsMediaSource
לאפשרויות התאמה אישית נוספות, אפשר ליצור HlsMediaSource
ולהעביר אותו ישירות לנגן במקום 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();
גישה למניפסט
אפשר לאחזר את המניפסט הנוכחי באמצעות קריאה ל-Player.getCurrentManifest
.
עבור HLS, צריך להמיר את האובייקט המוחזר ל-HlsManifest
. הקריאה החוזרת onTimelineChanged
של Player.Listener
נקראת גם בכל פעם שהמניפסט נטען. הדבר יקרה פעם אחת לגבי תוכן על פי דרישה, וייתכן שהוא יקרה הרבה פעמים לגבי תוכן בשידור חי. קטע הקוד הבא מראה איך אפליקציה יכולה לבצע פעולה כלשהי בכל פעם שהמניפסט נטען.
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 עם מודעות מעברון
במפרט HLS מוגדר שימוש במודעות HLS מסוג מודעות מעברון (interstitial) שאפשר להשתמש בהן כדי לכלול מידע על מודעות מעברון בפלייליסט מדיה. כברירת מחדל, מערכת ExoPlayer מתעלמת מהמודעות האלה. אפשר להוסיף תמיכה באמצעות HlsInterstitialsAdsLoader
. אנחנו לא תומכים בכל התכונות של המפרט מההתחלה. אם אין תמיכה בשידור שלכם, תוכלו לדווח על בעיה ב-GitHub ולשלוח לנו את מזהה ה-URI של השידור כדי שנוכל להוסיף תמיכה בשידור.
שימוש ב-MediaItem
עם Playlist API
הדרך הנוחה ביותר להפעיל שידורי HLS עם מודעות מעברון היא ליצור מכונה של ExoPlayer עם HlsInterstitialsAdsLoader.AdsMediaSourceFactory
.
כך אפשר להשתמש ב-playlist API שמבוסס על MediaItem
בממשק Player
כדי להפעיל מודעות ביניים מסוג HLS.
אפשר להחדיר את MediaSource.Factory
של ExoPlayer
ל-builder בזמן יצירה של מכונה של נגן:
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);
כשהנגן מוגדר כך, כדי להפעיל מודעות ביניים מסוג HLS צריך רק להגדיר בנגן פריט מדיה עם AdsConfiguration
:
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 שמבוסס על מקור המדיה
לחלופין, אפשר ליצור מכונה של ExoPlayer בלי לשנות את המפעל שמוגדר כברירת מחדל למקורות מדיה. כדי לתמוך במודעות מעברון, האפליקציה יכולה להשתמש ישירות ב-HlsInterstitialsAdsLoader.AdsMediaSourceFactory
כדי ליצור MediaSource
ולספק אותו ל-ExoPlayer באמצעות ה-API של הפלייליסט שמבוסס על מקור המדיה:
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();
האזנה לאירועים של מודעות
אפשר להוסיף Listener
ל-HlsInterstitialsAdsLoader
כדי לעקוב אחרי אירועים שקשורים לשינויים בסטטוס של הפעלת מודעות HLS מעברון. כך אפליקציה או SDK יכולים לעקוב אחרי מודעות שמוצגות, רשימות נכסים שמועמדות לטעינת, מקורות מדיה של מודעות שמוכנים או לזהות שגיאות בחיוב של רשימות נכסים ובהכנת מודעות. בנוסף, אפשר לקבל מטא-נתונים שמופקים ממקורות של מדיה של מודעות כדי לאמת את ההפעלה של המודעות ברמת פירוט גבוהה או כדי לעקוב אחר התקדמות ההפעלה של המודעות.
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.
}
}
בJavaDoc של HlsInterstitialsAdsLoader.Listener
מפורטת כל התיעוד של כל פונקציות ה-callbacks הזמינות.
לאחר מכן אפשר להוסיף את המאזין למטען המודעות:
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
מחזור חיים
אפשר לעשות שימוש חוזר במופע של HlsInterstitialsAdsLoader
או HlsInterstitialsAdsLoader.AdsMediaSourceFactory
במספר מופעים של נגן שיוצרים כמה מקורות מדיה שצריך לטעון אליהם מודעות.
אפשר ליצור מכונה, למשל, בשיטה onCreate
של Activity
, ואז להשתמש בה שוב במספר מכונות של שחקנים. הפתרון הזה פועל כל עוד מופע אחד של הנגן משתמש בו בו-זמנית. האפשרות הזו שימושית בתרחיש לדוגמה שכיח: כשהאפליקציה מועברת לרקע, מופע הנגן נהרס ולאחר מכן נוצר מופע חדש כשהאפליקציה חוזרת לחזית.
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();
באופן כללי, חשוב לשחרר את מופע הנגן הישן לפני שמגדירים את מופע הנגן הבא ב-Ads Loader. אחרי שהטעינה של המודעות תפורסם, לא תוכלו להשתמש בה יותר.
התאמה אישית של ההפעלה
ב-ExoPlayer יש כמה דרכים להתאים אישית את חוויית ההפעלה לצרכים של האפליקציה. דוגמאות מופיעות בדף ההתאמה האישית.
השבתת הכנה ללא קטעים
כברירת מחדל, ExoPlayer ישתמש בהכנה ללא קטעים. המשמעות היא ש-ExoPlayer ישתמש במידע ברשימת ההשמעה עם הווריאציות השונות רק כדי להכין את הסטרימינג. הפעולה הזו תתבצע אם התגים #EXT-X-STREAM-INF
מכילים את המאפיין CODECS
.
יכול להיות שתצטרכו להשבית את התכונה הזו אם קטעי המדיה שלכם מכילים טראקים של כתוביות מעורבבות שלא הוגדרו בפלייליסט עם וריאנטים מרובים באמצעות תג #EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS
. אחרת, הטראקים של הכתוביות לא יזוהו ולא יופעלו. אפשר להשבית את ההכנה ללא קטעים ב-HlsMediaSource.Factory
, כפי שמתואר בקטע הקוד הבא. חשוב לזכור שהפעולה הזו תגדיל את זמן ההפעלה, כי ExoPlayer צריך להוריד קטע מדיה כדי לזהות את הטראקים הנוספים האלה. לכן, עדיף להצהיר על הטראקים של הכתוביות בפלייליסט עם הווריאנטים השונים.
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));
יצירת תוכן HLS באיכות גבוהה
כדי להפיק את המקסימום מ-ExoPlayer, יש הנחיות מסוימות שאפשר לפעול לפיהן כדי לשפר את תוכן ה-HLS. בפוסט שלנו ב-Medium על הפעלת HLS ב-ExoPlayer מוסבר בהרחבה על הנושא. הנקודות העיקריות הן:
- להשתמש באורך מדויק של פלחים.
- שימוש בזרם מדיה רציף. הימנעות משינויים במבנה המדיה בין קטעים.
- משתמשים בתג
#EXT-X-INDEPENDENT-SEGMENTS
. - עדיף להשתמש בשידורים שהופרדו (demuxed) במקום בקבצים שכוללים גם וידאו וגם אודיו.
- מומלץ לכלול את כל המידע האפשרי בפלייליסט עם וריאציות מרובות.
ההנחיות הבאות רלוונטיות במיוחד לשידורים חיים:
- משתמשים בתג
#EXT-X-PROGRAM-DATE-TIME
. - משתמשים בתג
#EXT-X-DISCONTINUITY-SEQUENCE
. - לספק חלון זמן ארוך לשידור החי. דקה אחת או יותר הן מצוינות.