התאמה אישית

בליבת ספריית ExoPlayer נמצא ממשק Player. ‫Player חושף פונקציונליות מסורתית של נגן מדיה ברמה גבוהה, כמו היכולת לבצע באפרינג למדיה, להפעיל, להשהות ולחפש. ההטמעה שמוגדרת כברירת מחדל ExoPlayer מתוכננת כך שתתבסס על מעט הנחות לגבי סוג המדיה שמופעלת (ולכן תטיל מעט הגבלות עליה), לגבי האופן והמקום שבהם היא מאוחסנת ולגבי האופן שבו היא מוצגת. במקום להטמיע את הטעינה והעיבוד של מדיה ישירות, הטמעות של ExoPlayer מעבירות את העבודה הזו לרכיבים שמוזרקים כשיוצרים נגן או כשמעבירים מקורות מדיה חדשים לנגן. הרכיבים שמשותפים לכל ההטמעות של ExoPlayer הם:

• ‫MediaSource instances שמגדירים את המדיה להפעלה, טוענים את המדיה, ומאפשרים לקרוא את המדיה הטעונה. מופע של MediaSource נוצר מתוך MediaItem על ידי MediaSource.Factory בתוך הנגן. אפשר גם להעביר אותם ישירות לנגן באמצעות media source based playlist API.
• מופע של MediaSource.Factory שממיר MediaItem ל-MediaSource. ה-MediaSource.Factory מוזרק כשהנגן נוצר.
• Renderer מקרים שבהם רכיבים בודדים של המדיה מוצגים. הם מוזרקים כשהנגן נוצר.
• TrackSelector שבוחר רצועות שסופקו על ידי MediaSource לצריכה על ידי כל Renderer זמין. TrackSelector מוזרק כשהנגן נוצר.
• ‫LoadControl שקובע מתי MediaSource מאגר המדיה יטען עוד מדיה, וכמה מדיה תיטען. הערך LoadControl מוזרק כשהשחקן נוצר.
• LivePlaybackSpeedControl ששולט במהירות ההפעלה במהלך שידורים חיים כדי לאפשר לנגן להישאר קרוב להיסטוריית השידור החי שהוגדרה. ‫A LivePlaybackSpeedControl מוזרק כשהשחקן נוצר.

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

התאמה אישית של הנגן

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

הגדרת מחסנית הרשת

יש לנו דף בנושא התאמה אישית של מחסנית הרשת שבה נעשה שימוש ב-ExoPlayer.

שמירת נתונים שנטענו מהרשת במטמון

אפשר לעיין במדריכים בנושא שמירת מטמון זמנית תוך כדי תנועה והורדת מדיה.

התאמה אישית של אינטראקציות עם השרת

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

בדוגמה הבאה אפשר לראות איך מטמיעים את ההתנהגויות האלה על ידי הוספה של DataSource.Factory בהתאמה אישית ל-DefaultMediaSourceFactory:

Kotlin

val dataSourceFactory =
  DataSource.Factory {
    val dataSource = httpDataSourceFactory.createDataSource()
    // Set a custom authentication request header.
    dataSource.setRequestProperty("Header", "Value")
    dataSource
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)
    )
    .build()
Customization.kt

Java

DataSource.Factory dataSourceFactory =
    () -> {
      HttpDataSource dataSource = httpDataSourceFactory.createDataSource();
      // Set a custom authentication request header.
      dataSource.setRequestProperty("Header", "Value");
      return dataSource;
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory))
        .build();
Customization.java

בקטע הקוד שלמעלה, הרכיב HttpDataSource שמוזרק כולל את הכותרת "Header: Value" בכל בקשת HTTP. ההתנהגות הזו קבועה בכל אינטראקציה עם מקור HTTP.

כדי להשתמש בגישה מפורטת יותר, אפשר להוסיף התנהגות בזמן אמת באמצעות ResolvingDataSource. בקטע הקוד הבא אפשר לראות איך להוסיף כותרות של בקשות ממש לפני אינטראקציה עם מקור HTTP:

Kotlin

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time request headers.
    dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri))
  }
Customization.kt

Java

DataSource.Factory dataSourceFactory =
    new ResolvingDataSource.Factory(
        httpDataSourceFactory,
        // Provide just-in-time request headers.
        dataSpec -> dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri)));
Customization.java

אפשר גם להשתמש ב-ResolvingDataSource כדי לבצע שינויים ב-URI בזמן אמת, כמו שמוצג בקטע הקוד הבא:

Kotlin

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time URI resolution logic.
    dataSpec.withUri(resolveUri(dataSpec.uri))
  }
Customization.kt

Java

DataSource.Factory dataSourceFactory =
    new ResolvingDataSource.Factory(
        httpDataSourceFactory,
        // Provide just-in-time URI resolution logic.
        dataSpec -> dataSpec.withUri(resolveUri(dataSpec.uri)));
Customization.java

התאמה אישית של טיפול בשגיאות

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

Kotlin

val loadErrorHandlingPolicy: LoadErrorHandlingPolicy =
  object : DefaultLoadErrorHandlingPolicy() {
    override fun getRetryDelayMsFor(
      loadErrorInfo: LoadErrorHandlingPolicy.LoadErrorInfo
    ): Long {
      // Implement custom back-off logic here.
      return 0
    }
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setLoadErrorHandlingPolicy(loadErrorHandlingPolicy)
    )
    .build()
Customization.kt

Java

LoadErrorHandlingPolicy loadErrorHandlingPolicy =
    new DefaultLoadErrorHandlingPolicy() {
      @Override
      public long getRetryDelayMsFor(LoadErrorHandlingPolicy.LoadErrorInfo loadErrorInfo) {
        // Implement custom back-off logic here.
        return 0;
      }
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setLoadErrorHandlingPolicy(loadErrorHandlingPolicy))
        .build();
Customization.java

הארגומנט LoadErrorInfo מכיל מידע נוסף על הטעינה שנכשלה, כדי להתאים אישית את הלוגיקה על סמך סוג השגיאה או הבקשה שנכשלה.

התאמה אישית של סימוני מחלץ

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

Kotlin

val extractorsFactory =
  DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING)
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(DefaultMediaSourceFactory(context, extractorsFactory))
    .build()
Customization.kt

Java

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING);

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(new DefaultMediaSourceFactory(context, extractorsFactory))
        .build();
Customization.java

הפעלה של חיפוש קצב העברת נתונים קבוע

בסטרימינג של MP3, ‏ ADTS ו-AMR, אפשר להפעיל חיפוש משוער באמצעות הנחה של קצב העברת נתונים קבוע עם דגלי FLAG_ENABLE_CONSTANT_BITRATE_SEEKING. אפשר להגדיר את הדגלים האלה לחולצי נתונים ספציפיים באמצעות השיטות DefaultExtractorsFactory.setXyzExtractorFlags individual, כפי שמתואר למעלה. כדי להפעיל חיפוש קבוע של קצב העברת נתונים לכל כלי החילוץ שתומכים בו, משתמשים ב-DefaultExtractorsFactory.setConstantBitrateSeekingEnabled.

Kotlin

val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)
Customization.kt

Java

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true);
Customization.java

אחר כך אפשר להחדיר את ExtractorsFactory דרך DefaultMediaSourceFactory כמו שמתואר למעלה לגבי התאמה אישית של דגלי חילוץ.

הפעלה של תור אסינכרוני של מאגרי נתונים

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

התכונה 'הוספה אסינכרונית לתור של מאגרים' מופעלת כברירת מחדל במכשירים עם Android 12 (רמת API‏ 31) ומעלה, ואפשר להפעיל אותה באופן ידני החל מ-Android 6.0 (רמת API‏ 23). כדאי להפעיל את התכונה במכשירים ספציפיים שבהם אתם מבחינים בפריימים שנשמטים או בבעיות באודיו, במיוחד כשמפעילים תוכן שמוגן על ידי DRM או תוכן עם קצב פריימים גבוה.

במקרה הפשוט ביותר, צריך להוסיף DefaultRenderersFactory לנגן באופן הבא:

Kotlin

val renderersFactory =
  DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing()
val exoPlayer = ExoPlayer.Builder(context, renderersFactory).build()
Customization.kt

Java

DefaultRenderersFactory renderersFactory =
    new DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing();
ExoPlayer exoPlayer = new ExoPlayer.Builder(context, renderersFactory).build();
Customization.java

אם אתם יוצרים מופעים של רכיבי render ישירות, צריך להעביר את new DefaultMediaCodecAdapter.Factory(context).forceEnableAsynchronous() ל-constructors של MediaCodecVideoRenderer ושל MediaCodecAudioRenderer.

התאמה אישית של פעולות באמצעות ForwardingSimpleBasePlayer

אפשר להתאים אישית חלק מההתנהגות של מופע Player על ידי הוספתו למחלקת משנה של ForwardingSimpleBasePlayer. המחלקה הזו מאפשרת לכם ליירט 'פעולות' ספציפיות, במקום להטמיע ישירות שיטות של Player. כך אפשר להבטיח התנהגות עקבית של, לדוגמה, play(), ‏ pause() ו-setPlayWhenReady(boolean). הוא גם מוודא שכל השינויים במצב מועברים בצורה נכונה למופעים רשומים של Player.Listener. ברוב התרחישים לדוגמה של התאמה אישית, עדיף להשתמש ב-ForwardingSimpleBasePlayer במקום ב-ForwardingPlayer, כי הוא פחות מועד לשגיאות.

לדוגמה, כדי להוסיף לוגיקה מותאמת אישית כשמתחילים או מפסיקים את ההפעלה:

Kotlin

class PlayerWithCustomPlay(player: Player) : ForwardingSimpleBasePlayer(player) {
  override fun handleSetPlayWhenReady(playWhenReady: Boolean): ListenableFuture<*> {
    // Add custom logic
    return super.handleSetPlayWhenReady(playWhenReady)
  }
}
Customization.kt

Java

public static final class PlayerWithCustomPlay extends ForwardingSimpleBasePlayer {

  public PlayerWithCustomPlay(Player player) {
    super(player);
  }

  @Override
  protected ListenableFuture<?> handleSetPlayWhenReady(boolean playWhenReady) {
    // Add custom logic
    return super.handleSetPlayWhenReady(playWhenReady);
  }
}
Customization.java

או כדי לא לאפשר את הפקודה SEEK_TO_NEXT (ולוודא ש-Player.seekToNext היא פעולה שלא עושה כלום):

Kotlin

class PlayerWithoutSeekToNext(player: Player) : ForwardingSimpleBasePlayer(player) {
  override fun getState(): State {
    val state = super.getState()
    return state
      .buildUpon()
      .setAvailableCommands(
        state.availableCommands.buildUpon().remove(COMMAND_SEEK_TO_NEXT).build()
      )
      .build()
  }

  // We don't need to override handleSeek, because it is guaranteed not to be called for
  // COMMAND_SEEK_TO_NEXT since we've marked that command unavailable.
}
Customization.kt

Java

public static final class PlayerWithoutSeekToNext extends ForwardingSimpleBasePlayer {

  public PlayerWithoutSeekToNext(Player player) {
    super(player);
  }

  @Override
  protected State getState() {
    State state = super.getState();
    return state
        .buildUpon()
        .setAvailableCommands(
            state.availableCommands.buildUpon().remove(COMMAND_SEEK_TO_NEXT).build())
        .build();
  }

  // We don't need to override handleSeek, because it is guaranteed not to be called for
  // COMMAND_SEEK_TO_NEXT since we've marked that command unavailable.
}
Customization.java

התאמה אישית של MediaSource

בדוגמאות שלמעלה מוזרקים רכיבים מותאמים אישית לשימוש במהלך ההפעלה של כל האובייקטים מסוג MediaItem שמועברים לנגן. במקרים שבהם נדרשת התאמה אישית ברמה גבוהה, אפשר גם להחדיר רכיבים בהתאמה אישית למופעים ספציפיים של MediaSource, שאפשר להעביר ישירות לנגן. בדוגמה שלמטה מוסבר איך להתאים אישית ProgressiveMediaSource כדי להשתמש בDataSource.Factory, בExtractorsFactory ובLoadErrorHandlingPolicy בהתאמה אישית:

Kotlin

val mediaSource =
  ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
    .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
    .createMediaSource(MediaItem.fromUri(streamUri))
Customization.kt

Java

ProgressiveMediaSource mediaSource =
    new ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
        .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
        .createMediaSource(MediaItem.fromUri(streamUri));
Customization.java

יצירת רכיבים מותאמים אישית

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

• ‫Renderer – יכול להיות שתרצו להטמיע Renderer מותאם אישית כדי לטפל בסוג מדיה שלא נתמך על ידי הטמעות ברירת המחדל שסופקו על ידי הספרייה.
• ‫TrackSelector – הטמעה של TrackSelector בהתאמה אישית מאפשרת למפתחי אפליקציות לשנות את האופן שבו נבחרים טראקים שנחשפים על ידי MediaSource לצריכה על ידי כל אחד מה-Renderer הזמינים.
• ‫LoadControl – הטמעה של LoadControl בהתאמה אישית מאפשרת למפתחי אפליקציות לשנות את מדיניות החיץ של הנגן.
• ‫Extractor – אם אתם צריכים לתמוך בפורמט של קונטיינר שלא נתמך כרגע בספרייה, כדאי להטמיע מחלקה מותאמת אישית של Extractor.
• ‫MediaSource – הטמעה של מחלקה מותאמת אישית MediaSource יכולה להתאים אם רוצים לקבל דוגמאות של מדיה כדי להזין אותן לרכיבי עיבוד בדרך מותאמת אישית, או אם רוצים להטמיע התנהגות מותאמת אישית של MediaSource שילוב.
• ‫MediaSource.Factory – הטמעה של MediaSource.Factory מותאם אישית מאפשרת לאפליקציה להתאים אישית את האופן שבו נוצר MediaSource מתוך MediaItem.
• ‫DataSource – חבילת ה-upstream של ExoPlayer כבר מכילה מספר הטמעות של DataSource לתרחישי שימוש שונים. אפשר להטמיע מחלקה משלכם DataSource כדי לטעון נתונים בדרך אחרת, למשל באמצעות פרוטוקול מותאם אישית, באמצעות מחסנית HTTP מותאמת אישית או ממטמון מותאם אישית מתמשך.

כשיוצרים רכיבים בהתאמה אישית, מומלץ:

• אם רכיב מותאם אישית צריך לדווח על אירועים בחזרה לאפליקציה, מומלץ לעשות זאת באמצעות אותו מודל כמו רכיבי ExoPlayer קיימים, למשל באמצעות מחלקות EventDispatcher או העברת Handler יחד עם מאזין לקונסטרוקטור של הרכיב.
• מומלץ שרכיבים מותאמים אישית ישתמשו באותו מודל כמו רכיבי ExoPlayer קיימים, כדי לאפשר לאפליקציה להגדיר מחדש את ההגדרות במהלך ההפעלה. כדי לעשות את זה, רכיבים מותאמים אישית צריכים להטמיע את PlayerMessage.Target ולקבל שינויים בהגדרות בשיטה handleMessage. קוד האפליקציה צריך להעביר שינויים בהגדרות על ידי קריאה לשיטה createMessage של ExoPlayer, הגדרת ההודעה ושליחתה לרכיב באמצעות PlayerMessage.send. שליחת הודעות להצגה בשרשור ההפעלה מבטיחה שהן יבוצעו לפי הסדר עם כל פעולה אחרת שמבוצעת בנגן.