איך מתחילים?

בתרחישים לדוגמה פשוטים, כדי להתחיל להשתמש ב-ExoPlayer צריך לבצע את השלבים הבאים:

1. מוסיפים את ExoPlayer כחפיפה לפרויקט.
2. יוצרים מכונה של ExoPlayer.
3. מחברים את הנגן לתצוגה (לפלט וידאו ולקלט של משתמשים).
4. מכינים את הנגן עם MediaItem כדי להפעיל אותו.
5. שחרור הנגן בסיום.

השלבים האלה מתוארים בפירוט בהמשך. דוגמה מלאה זמינה בקטע PlayerActivity באפליקציית ההדגמה הראשית.

הוספת ExoPlayer כיחסי תלות

הוספת מודולים של ExoPlayer

הדרך הקלה ביותר להתחיל להשתמש ב-AndroidX Media3 היא להוסיף יחסי תלות של Gradle בספריות הנדרשות בקובץ build.gradle של מודול האפליקציה.

לדוגמה, כדי להסתמך על ExoPlayer עם תמיכה בהפעלה של DASH ורכיבי ממשק משתמש, אפשר להוסיף יחסי תלות במודולים באופן הבא:

implementation("androidx.media3:media3-exoplayer:1.4.1")
implementation("androidx.media3:media3-exoplayer-dash:1.4.1")
implementation("androidx.media3:media3-ui:1.4.1")

implementation "androidx.media3:media3-exoplayer:1.4.1"
implementation "androidx.media3:media3-exoplayer-dash:1.4.1"
implementation "androidx.media3:media3-ui:1.4.1"

כאשר 1.4.1 היא הגרסה המועדפת (אפשר למצוא את הגרסה האחרונה בהערות המוצר). כל המודולים צריכים להיות באותה גרסה.

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

מידע נוסף על המודולים הזמינים בספרייה זמין בדף Google Maven AndroidX Media.

הפעלת תמיכה ב-Java 8

אם עדיין לא הפעלתם את התמיכה ב-Java 8, עליכם להוסיף את הקטע הבא לקטע android בכל הקבצים build.gradle שמסתמכים על ExoPlayer:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

הפעלת multidex

אם גרסת Gradle minSdkVersion היא 20 ואילך, צריך להפעיל את multidex כדי למנוע שגיאות build.

יצירת הנגן

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

val player = ExoPlayer.Builder(context).build()

ExoPlayer player = new ExoPlayer.Builder(context).build();

הערה לגבי שימוש בשרשור

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

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

מידע נוסף על מודל השרשור של ExoPlayer זמין בקטע Threading model ב-Javadoc של ExoPlayer.

צירוף הנגן לתצוגה

ספריית ExoPlayer מספקת מגוון רכיבי ממשק משתמש מוכנים מראש להפעלת מדיה. למשל PlayerView, שכולל את ה-PlayerControlView, ה-SubtitleView ו-Surface שאליו הסרטון מעובד. אפשר לכלול קובץ PlayerView בקובץ ה-xml של הפריסה של האפליקציה. לדוגמה, כדי לקשר את הנגן לתצוגה:

// Bind the player to the view.
playerView.player = player

// Bind the player to the view.
playerView.setPlayer(player);

אפשר גם להשתמש ב-PlayerControlView כרכיב עצמאי, וזה שימושי בתרחישים לדוגמה שבהם יש רק אודיו.

השימוש ברכיבי ממשק המשתמש המובנים של ExoPlayer הוא אופציונלי. באפליקציות וידאו שמטמיעות ממשק משתמש משלהם, אפשר להגדיר את היעד SurfaceView, ‏ TextureView,‏ SurfaceHolder או Surface באמצעות השיטות setVideoSurfaceView, ‏ setVideoTextureView, ‏ setVideoSurfaceHolder ו-setVideoSurface של ExoPlayer, בהתאמה. אפשר להשתמש בשיטה addTextOutput של ExoPlayer כדי לקבל כתוביות שצריך להציג במהלך ההפעלה.

איך מאכלסים את הפלייליסט ומכינים את הנגן

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

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

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

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

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

שליטה בנגן

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

• play ו-pause מתחילים ומשהים את ההפעלה.
• seekTo מאפשרת לדלג בתוך המדיה.
• hasPrevious, ‏ hasNext, ‏ previous וגם next מאפשרים לנווט בפלייליסט.
• setRepeatMode קובע אם המדיה תופעל בלופ ואיך היא תופעל.
• setShuffleModeEnabled קובע אם הפלייליסט יופעל בסדר אקראי.
• setPlaybackParameters שינוי מהירות ההפעלה וגובה הצליל.

אם הנגן קשור ל-PlayerView או ל-PlayerControlView, אינטראקציה של משתמשים עם הרכיבים האלה תגרום להפעלה של השיטות התואמות בנגן.

שחרור הנגן

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