תחילת העבודה

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

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

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

הוספת ExoPlayer כתלות

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

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

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

Kotlin

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

Groovy

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

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

ל-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()
HelloWorld.kt

Java

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

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

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

אפשר לציין באופן מפורש את ה-thread שבו צריך לגשת למופע של ExoPlayer על ידי העברת Looper כשיוצרים את הנגן. אם לא מציינים Looper, המערכת משתמשת ב-Looper של השרשור שבו נוצר נגן, או אם לשרשור הזה אין Looper, המערכת משתמשת ב-Looper של השרשור הראשי של האפליקציה. בכל המקרים, אפשר לשלוח שאילתה לגבי Looper של השרשור שממנו צריך לגשת לשחקן באמצעות 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
HelloWorld.kt

Java

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

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

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

android:keepScreenOn="true"

אם האפליקציה משתמשת ב-Jetpack פיתוח נייטיב לממשק המשתמש, אפשר להשתמש ב-Composable Player מהספרייה 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)
HelloWorld.kt

מידע נוסף על שימוש ברכיבי ממשק המשתמש של 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()
HelloWorld.kt

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();
HelloWorld.java

‫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()
HelloWorld.kt

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();
HelloWorld.java

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

שליטה בנגן

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

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

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

הפעלת הנגן

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