תחילת העבודה

בתרחישי שימוש פשוטים, כדי להתחיל להשתמש ב-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.8.0")
implementation("androidx.media3:media3-exoplayer-dash:1.8.0")
implementation("androidx.media3:media3-ui:1.8.0")
implementation("androidx.media3:media3-ui-compose:1.8.0")

Groovy

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

כאשר 1.8.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()

Java

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

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

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

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

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

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

ספריית ExoPlayer מספקת מגוון רכיבי ממשק משתמש מוכנים מראש להפעלת מדיה. הם כוללים את 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);

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

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

android:keepScreenOn="true"

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