HLS

‫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 בלבד
שליטה בשרת
עדכוני דלתא כן
חסימת טעינה מחדש של פלייליסט כן
חסימה של טעינת רמזים לטעינה מראש כן חוץ מטווחים של בייטים עם אורכים לא מוגדרים
הצגת מודעות
הוספת מודעות בהנחיית השרת (מודעות מעברון) באופן חלקי רק תוכן 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.7.1")

מגניב

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

אחר כך אפשר ליצור 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, שאפשר להשתמש בהן כדי לכלול מידע על מודעות מעבר בפלייליסט של מדיה. כברירת מחדל, ExoPlayer מתעלם מהמודעות האלה. אפשר להוסיף תמיכה באמצעות HlsInterstitialsAdsLoader. אנחנו לא תומכים בכל התכונות של המפרט מההתחלה. אם חסרה תמיכה בסטרימינג שלכם, אפשר לדווח על בעיה ב-GitHub ולשלוח לנו את ה-URI של הסטרימינג כדי שנוסיף תמיכה בסטרימינג שלכם.

שימוש ב-MediaItem עם Playlist API

הדרך הנוחה ביותר להפעיל שידורים בפרוטוקול HLS עם מודעות מעברון היא ליצור מופע של ExoPlayer עם HlsInterstitialsAdsLoader.AdsMediaSourceFactory. כך אפשר להשתמש ב-playlist API של ממשק PlayerMediaItem כדי להפעיל מודעות מעבר בפורמט 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 אפשר למצוא תיעוד מפורט של כל הקריאות החוזרות (callback) שזמינות.

לאחר מכן אפשר להוסיף את מאזין האירועים ל-ads loader:

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

באופן כללי, חשוב לשחרר את מופע הנגן הישן לפני שמגדירים את מופע הנגן הבא בטוען המודעות. אחרי שהטעינה של המודעות עצמה תופסק, לא יהיה יותר אפשר להשתמש בטעינת המודעות.

התאמה אישית של ההפעלה

‫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.
  • עדיף להשתמש בסטרימינג של קבצים מפורקים, ולא בקבצים שכוללים גם וידאו וגם אודיו.
  • כדאי לכלול בפלייליסט עם הווריאציות כמה שיותר מידע.

ההנחיות הבאות רלוונטיות לשידורים חיים בלבד:

  • משתמשים בתג #EXT-X-PROGRAM-DATE-TIME.
  • משתמשים בתג #EXT-X-DISCONTINUITY-SEQUENCE.
  • חלון הפעילות צריך להיות ארוך. דקה אחת או יותר זה מצוין.