ממשק הנגן

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

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

‫Media3 מספקת גם הטמעה של הממשק Player, שנקרא ExoPlayer.

ממשק משותף בין רכיבים

כמה רכיבים ב-Media3 מטמיעים את ממשק Player, למשל:

למרות ש-MediaSession לא מטמיע את הממשק Player, הוא דורש Player כשיוצרים אותו. המטרה שלו היא לספק גישה ל-Player מתהליכים או משרשורים אחרים.

ארכיטקטורה של הפעלת מדיה ב-Media3

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

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

מצב הנגן

המצב של נגן מדיה שמטמיע את הממשק Player מורכב בעיקר מ-4 קטגוריות של מידע:

1. מצב ההפעלה
   • אפשר לאחזר באמצעות getPlaybackState().
   • ערכי המצב שמוגדרים על ידי הממשק הם STATE_IDLE,‏ STATE_BUFFERING,‏ STATE_READY ו-STATE_ENDED.
2. פלייליסט של פריטי מדיה
   • רצף של MediaItem מקרים להפעלה.
   • שחזור באמצעות getCurrentTimeline()
   • ‫Player instances יכולים לספק שיטות להפעלת פלייליסטים כמו הוספה או הסרה של MediaItem ושיטות נוחות כמו getCurrentMediaItem().
3. מאפייני הפעלה/השהיה, כמו:
   • ‫playWhenReady: האם המשתמש רוצה שהמדיה תופעל כשאפשר או שתישאר בהשהיה
   • הסיבה להשבתת ההפעלה: ציון הסיבה להשבתת ההפעלה, אם רלוונטי, גם אם הערך של playWhenReady הוא true
   • ‫isPlaying: אינדיקציה אם הנגן פועל כרגע, שתהיה רק ‫true אם מצב ההפעלה הוא STATE_READY, הערך של playWhenReady הוא true וההפעלה לא מושבתת
4. מיקום ההפעלה, כולל:
   • ‫Current media item index: האינדקס של MediaItem הנוכחי בפלייליסט.
   • ‫isPlayingAd: סימון שמציין אם מודעה שהוכנסה מוצגת.
   • ‫Current playback position: המיקום הנוכחי בהפעלה בתוך MediaItem הנוכחי או המודעה שהוכנסה.

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

האזנה לשינויים

משתמשים ב-Player.Listener כדי לחפש שינויים ב-Player. במאמר אירועים של נגן בתיעוד של ExoPlayer מוסבר איך ליצור מאזין ולהשתמש בו.

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

val handler = Handler(Looper.getMainLooper())
fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs)

Handler handler = new Handler(Looper.getMainLooper());
boolean checkPlaybackPosition(long delayMs) {
    return handler.postDelayed(() -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
    }, delayMs);
}

שליטה בהפעלה

בממשק Player יש הרבה דרכים לשנות את המצב ולשלוט בהפעלה:

• אמצעי בקרה בסיסיים להפעלה כמו play(), pause(), prepare() ו-stop().
• פעולות בפלייליסטים כמו addMediaItem() או removeMediaItem().
• חיפוש מיקום כדי לשנות את הפריט או המיקום הנוכחיים.
• מגדירים מצבי חזרה ומצב הפעלה אקראית.
• עדכון העדפות הבחירה של רצועות.
• מגדירים את מהירות ההפעלה.

הטמעות Player בהתאמה אישית

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

מתחילים בהחלפת השיטה getState(). השיטה הזו אמורה לאכלס את מצב השחקן הנוכחי כשהיא מופעלת, כולל:

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

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}

public class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build();
  }
}

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

מעבר לשיטה getState(), צריך להטמיע רק שיטות שמשמשות לפקודות שהנגן מצהיר שהן זמינות. מוצאים את שיטת הטיפול שאפשר לשנות שמתאימה לפונקציונליות שרוצים להטמיע. לדוגמה, אפשר לבטל את השיטה handleSeek() כדי לתמוך בפעולות כמו COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM ו-COMMAND_SEEK_TO_NEXT_MEDIA_ITEM.

שינוי הטמעות של Player

במקום ליצור Player בהתאמה אישית מלאה, אפשר להשתמש ב-ForwardingSimpleBasePlayer כדי לשנות את המצב וההתנהגות של Player קיים. פרטים נוספים זמינים במדריך בנושא דף ההתאמה האישית.