תחילת העבודה

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

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

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

הוספת ExoPlayer כתלות

כדי להשתמש ב-ExoPlayer באפליקציה, צריך להוסיף את המודולים הנדרשים ולהפעיל תמיכה ב-Java 8.

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

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

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

Kotlin

implementation("androidx.media3:media3-exoplayer:1.11.1")
implementation("androidx.media3:media3-exoplayer-dash:1.11.1")
implementation("androidx.media3:media3-ui:1.11.1")
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

מגניב

implementation "androidx.media3:media3-exoplayer:1.11.1"
implementation "androidx.media3:media3-exoplayer-dash:1.11.1"
implementation "androidx.media3:media3-ui:1.11.1"
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

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

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

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

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

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

יצירת הנגן

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

Kotlin

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

Java

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

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

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

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

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

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

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

Kotlin

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

Java

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

השימוש ברכיבי ממשק המשתמש המובנים של Media3 הוא אופציונלי. באפליקציות וידאו שבהן מוטמע ממשק משתמש משלהן, אפשר להגדיר את היעד SurfaceView, ‏ TextureView, ‏ SurfaceHolder או Surface באמצעות השיטות setVideoSurfaceView,‏ setVideoTextureView, ‏ setVideoSurfaceHolder ו-setVideoSurface של הנגן, בהתאמה. אפשר להשתמש בקריאה החוזרת (callback) של Listener.onCues כדי לקבל כתוביות שצריך לעבד במהלך ההפעלה, וב-setImageOutput כדי לקבל תמונות מפוענחות.

כדי לשפר את חוויית המשתמש, מומלץ להוסיף את המאפיין keepScreenOn. אפשר לבדוק פעולות אחרות שגורמות למכשיר להישאר פעיל בדפים של עבודה ברקע.

android:keepScreenOn="true"

אם האפליקציה משתמשת ב-Jetpack Compose לממשק המשתמש, אפשר להשתמש ב-Player Composable מהספרייה media3-ui-compose-material3. ‫Player מציג סרטון וכולל ערכים מאוכלסים מראש של משבצות לרכיבי UI להפעלה. כדי לצרף אובייקט androidx.media3.common.Player לפונקציה קומפוזבילית androidx.media3.ui.compose.material3.Player, פשוט מעבירים אותו כארגומנט:

// Bind the player to the composable.
Player(player = player)

מידע נוסף על השימוש ברכיבי ממשק המשתמש של Media3 ועל ההתאמה האישית שלהם זמין בדף ממשק המשתמש.

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

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

Kotlin

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

Java

// 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 תומך ישירות בפלייליסטים, כך שאפשר להכין את הנגן עם כמה קובצי מדיה שיופעלו אחד אחרי השני:

Kotlin

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

Java

// 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.